Skip to main content
Migo Docs

Cardholders (CMS)

RESTRICTED API

Requires partner / operator authorization. See CMS → Home.

Operator-facing cardholder management. Every endpoint is scoped to a partnerId.

List cardholders in a partner​

curl "https://api.ali.app/cms/rest/app/partners/{partnerId}/cardholders?page=1&limit=50&searchText=maria" \
  -H "Authorization: Bearer <token>" \
  -H "x-user-token: Bearer <cms-user-token>"

Query params: page, limit, searchText (email, phone, document), sortBy, sortOrder.

Create a cardholder​

curl -X POST "https://api.ali.app/cms/rest/app/partners/{partnerId}/cardholders" \
  -H "Authorization: Bearer <token>" \
  -H "x-user-token: Bearer <cms-user-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "María",
    "lastName": "Ramírez",
    "address": "Calle Principal 123",
    "countryOfBirth": "GT",
    "dateOfBirth": "1990-05-12",
    "maritalStatus": "soltero",
    "gender": "F",
    "phoneNumber": "50255551234",
    "email": "maria@example.com",
    "documentType": "DPI",
    "documentNumber": "2345678901234",
    "cardId": 1
  }'

All fields are required. Enum values:

  • countryOfBirth — ISO country code (e.g. GT).
  • maritalStatus — soltero | casado | viudo | divorciado | separado.
  • gender — F | M | OTHER.
  • documentType — DPI | NIT | PASSPORT | LEGAL_ID | PERSONAL_ID | RESIDENCE_ID.
  • dateOfBirth — YYYY-MM-DD.
  • cardId — numeric ID of the card to assign to the new cardholder.

The create call delegates to the orchestrator / op-users services; the concrete response envelope is the standard { success, message, data }.

Get a cardholder (detail)​

Cardholder detail is fetched via POST (not GET). The body is optional and only carries an OTP when the operator is subject to OTP elevation (enforced by the conditional OTP guard).

curl -X POST "https://api.ali.app/cms/rest/app/partners/{partnerId}/cardholders/{cardholderId}" \
  -H "Authorization: Bearer <token>" \
  -H "x-user-token: Bearer <cms-user-token>" \
  -H "Content-Type: application/json" \
  -d '{ "otp": "123456" }'

otp is a 6-digit numeric code, required only when the user holds the OTP permission; omit the body otherwise.

List all cards in a partner​

Lists every card associated with the partner/client.

curl "https://api.ali.app/cms/rest/app/partners/{partnerId}/cards" \
  -H "Authorization: Bearer <token>" \
  -H "x-user-token: Bearer <cms-user-token>"

Cards of a cardholder​

# All cards (owned + linked)
curl "https://api.ali.app/cms/rest/app/partners/{partnerId}/cardholders/{cardholderId}/cards" \
  -H "Authorization: Bearer <token>" \
  -H "x-user-token: Bearer <cms-user-token>"

Card actions​

Per-card activate / block / unblock use PATCH:

# Activate
PATCH /app/partners/{partnerId}/cardholders/{cardholderId}/cards/{cardId}/activate

# Block
PATCH /app/partners/{partnerId}/cardholders/{cardholderId}/cards/{cardId}/block

# Unblock
PATCH /app/partners/{partnerId}/cardholders/{cardholderId}/cards/{cardId}/unblock

Bulk block / unblock by card id list (both endpoints require a 6-digit OTP):

# Bulk block
curl -X PATCH "https://api.ali.app/cms/rest/app/partners/{partnerId}/cardholders/cards/block" \
  -H "Authorization: Bearer <token>" \
  -H "x-user-token: Bearer <cms-user-token>" \
  -H "Content-Type: application/json" \
  -d '{ "cardIds": [1, 2, 3], "otp": "123456" }'

# Bulk unblock
curl -X PATCH "https://api.ali.app/cms/rest/app/partners/{partnerId}/cardholders/cards/unblock" \
  -H "Authorization: Bearer <token>" \
  -H "x-user-token: Bearer <cms-user-token>" \
  -H "Content-Type: application/json" \
  -d '{ "cardIds": [1, 2, 3], "otp": "123456" }'

Card funds operations​

amount is a number; observations is optional.

# Add funds
POST /app/partners/{partnerId}/cardholders/{cardholderId}/cards/funds/add
{ "cardId": 10, "amount": 150.0, "observations": "Monthly allowance" }

# Withdraw funds
POST /app/partners/{partnerId}/cardholders/{cardholderId}/cards/funds/withdraw
{ "cardId": 10, "amount": 25.0 }

# Transfer between two cards of the SAME cardholder
POST /app/partners/{partnerId}/cardholders/{cardholderId}/cards/transfers
{ "fromCardId": 10, "toCardId": 20, "amount": 50.0, "observations": "Balance reallocation" }

Transfers move funds between two cards belonging to the same cardholder; both cards must be active.

Movements / transaction history per card​

# List
GET /app/partners/{partnerId}/cardholders/{cardholderId}/cards/{cardId}/movements?from=2026-03-01&to=2026-03-31

# Single movement
GET /app/partners/{partnerId}/cardholders/{cardholderId}/cards/{cardId}/movements/{transferId}

# Download a PDF report (binary attachment)
GET /app/partners/{partnerId}/cardholders/{cardholderId}/cards/{cardId}/movements/report?from=2026-03-01&to=2026-03-31

The report endpoint is a GET that streams a binary PDF (Content-Disposition: attachment). Filter with from / to (and the standard page, limit, sortBy, sortOrder query params); there is no format field — output is always PDF.

Associate a third-party card​

curl -X POST "https://api.ali.app/cms/rest/app/partners/{partnerId}/cardholders/{cardholderId}/cards/association" \
  -H "Authorization: Bearer <token>" \
  -H "x-user-token: Bearer <cms-user-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "suffix": "4321",
    "alias": "Personal Visa"
  }'

email is the third-party card owner's email and suffix is the last digits of the card number.

List the third-party cards already associated with a cardholder:

curl "https://api.ali.app/cms/rest/app/partners/{partnerId}/cardholders/{cardholderId}/cards/association" \
  -H "Authorization: Bearer <token>" \
  -H "x-user-token: Bearer <cms-user-token>"

See Wallet → Third-party cards for the tokenization half of the flow.