Cardholder Management

A cardholder is a user who owns a Migo card. This page is the canonical reference for registering and managing cardholders on the Wallet Gateway. It is organized in two parts:

• Register a cardholder — create the user (POST /users).
• Manage a cardholder — find, profile, roles, states, and step-up verification.

All endpoints require a valid JWT (Authorization: Bearer <token>).

---

Register a cardholder

POST /users registers a new cardholder. It requires the USER_REGISTRATION application permission and supports two modes, chosen by the gateway from the request body:

• invitationCode present → validated as ExternalUserRegistrationDto (registration via a branch invitation code).
• otherwise → validated as CreateUserDto (direct registration with personal information).

Only the Authorization header is required; x-user-token does not apply to this endpoint.

Mode 1 — Branch invitation code

curl -X POST https://api.ali.app/rest/users \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "device-0000",
    "invitationCode": "INV-0000",
    "username": "user@example.com",
    "password": "<password>",
    "confirmPassword": "<password>",
    "termsAndConditionsAccepted": true
  }'

Field	Type	Required	Notes
deviceId	string	yes	Unique identifier of the device that started the registration
invitationCode	string	yes	Branch invitation code that grants access to register
username	string (email)	yes	Email address used as the username
password	string	yes	Account password (non-empty)
confirmPassword	string	yes	Must match password
nit	string	no	Tax identification number (NIT)
termsAndConditionsAccepted	boolean	no	Whether terms and conditions were accepted

Mode 2 — Direct registration

curl -X POST https://api.ali.app/rest/users \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Example",
    "lastName": "User",
    "address": "Example address",
    "countryOfBirth": "GTM",
    "placeOfBirth": "Example City",
    "gender": "M",
    "maritalStatus": "soltero",
    "phoneNumber": "+50200000000",
    "username": "user@example.com",
    "dateOfBirth": "1990-01-01",
    "termsAndConditionsAccepted": true,
    "identificationDocuments": [
      { "documentNumber": "XXXXXXXXXXXXX", "documentType": "DPI" }
    ]
  }'

Field	Type	Required	Notes
firstName	string	yes	First name
lastName	string	yes	Last name
address	string	yes	Residential address
countryOfBirth	Country enum	yes	ISO alpha-3 code (e.g. GTM). Alpha-2 input is normalized to alpha-3 by the gateway
placeOfBirth	string	yes	Free text
gender	Gender enum	yes	M, F or OTHER
phoneNumber	string	yes	Phone number in international format
dateOfBirth	string	yes	YYYY-MM-DD
identificationDocuments	array	yes	Array of { documentNumber, documentType } (both strings, e.g. documentType: "DPI")
username	string (email)	no	Email address used as the username
maritalStatus	MaritalStatus enum	no	soltero, casado, viudo, divorciado or separado
neighborhood	string	no	Neighborhood or district
termsAndConditionsAccepted	boolean	no	Whether terms and conditions were accepted
additionalData	object	no	Additional user metadata

There is no top-level email / documentId / birthDate in either mode — the email is username, and identity documents live in identificationDocuments.

Response

Both modes return the standard response envelope; on success the created user is returned under data:

{ "success": true, "data": { } }

On error, success is false and errors carries the detail. The envelope fields are success (boolean), optional message, optional data, and optional errors (array of { message, code }).

Generate an invitation code (for Mode 1)

The branch invitation code consumed by Mode 1 is created with POST /users/invitation-code (InvitationCodeGenerateDto):

curl -X POST https://api.ali.app/rest/users/invitation-code \
  -H "Authorization: Bearer <token>" \
  -H "x-user-token: <user-token>" \
  -H "Content-Type: application/json" \
  -d '{ "branchId": 24, "role": "owner" }'

role is one of owner, admin, cashier. The full onboarding flow is described in Tap to Phone → SDK install and Terminal Payments.

---

Manage a cardholder

Find a cardholder

GET /users retrieves a single user filtered by either id (numeric) or username (email) — at least one is required:

curl "https://api.ali.app/rest/users?username=user@example.com" \
  -H "Authorization: Bearer <token>" \
  -H "x-application-id: YOUR_APP_ID"

Account states

The auth_user.status values are:

State	Meaning
Pending	Account created, not yet activated
Active	Fully onboarded
Inactive	Deactivated
Blocked	Disabled (fraud, KYC issue, customer request)
PasswordResetRequired	Must reset password before continuing

There is no profile-update PATCH endpoint; card status changes go through the card block/unblock endpoints (see Card Lifecycle).

Verify a password

POST /users/{userId}/auth validates a password against the user's credentials — used for step-up confirmation before sensitive actions (VerifyPasswordDto):

curl -X POST "https://api.ali.app/rest/users/{userId}/auth" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "password": "<password>" }'

Profile image

PUT /users/{userId}/profile-image accepts a multipart/form-data upload with the field profileImage (max 5 MB; png, jpeg, jpg):

curl -X PUT "https://api.ali.app/rest/users/{userId}/profile-image" \
  -H "Authorization: Bearer <token>" \
  -F "profileImage=@avatar.jpg"

Push notification tokens

Register and remove the cardholder's FCM (Firebase Cloud Messaging) token so the platform can deliver push notifications:

# Register
curl -X POST "https://api.ali.app/rest/users/fcm-tokens" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "token": "fcm-token-abc123xyz" }'

# Remove (on logout / token rotation) — returns 204 No Content
curl -X DELETE "https://api.ali.app/rest/users/fcm-tokens/{token}" \
  -H "Authorization: Bearer <token>"

Roles

List the available roles and add/remove roles for a user:

# List roles
curl https://api.ali.app/rest/users/roles \
  -H "Authorization: Bearer <token>"

# Add / remove roles for a user
curl -X PATCH https://api.ali.app/rest/users/{id}/roles \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "addRoles": ["SHOP_ADMIN"], "removeRoles": [] }'

Related

• Card issuance flow
• Card lifecycle