Card Lifecycle

This page is the canonical reference for card states and operations: issuing a Migo physical card, linking an existing card, activating, blocking, updating the alias, reading details, and generating statements. For the end-to-end onboarding sequence, see the Card issuance flow; for cardholder/user registration, see Cardholder management.

Issue a card

This is the Migo-issued (physical) card issuance endpoint. It takes no request body — the card is created for the user identified in the path:

curl -X POST https://api.ali.app/rest/users/{userId}/cards/virtuals \
  -H "Authorization: Bearer <token>" \
  -H "x-application-id: YOUR_APP_ID"

Card identifiers are numeric. The newly created card needs a PIN before it can authorize transactions — see PIN management.

Link an existing card to a user

POST /users/{userId}/cards links an existing card to the user (it is not a physical-card issuance endpoint). It requires a clientId query parameter and an ExternalLinkCardUserDto body:

curl -X POST "https://api.ali.app/rest/users/{userId}/cards?clientId=YOUR_CLIENT_ID" \
  -H "Authorization: Bearer <token>" \
  -H "x-application-id: YOUR_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "card": "4111111111111111",
    "alias": "My Personal Card"
  }'

Field	Required	Notes
card	yes	Card number to link (must pass card verification)
alias	no	Human-readable alias for the card

Activate a card

A delivered card arrives inactive and cannot transact until it is activated. There are two activation paths — pick whichever fits your integration:

Option A — Hosted activation webview (cardholder self-service)

The cardholder activates the card themselves through Migo's hosted card-activation webview. Open it with the cardholder's userId:

https://web.migopayments.com/card-activation?client=migoDeveloper&userId=YOUR_USER_ID

Query param	Required	Purpose
userId	Yes	The cardholder who owns the card
client	No	Branding hint for the activation screen (your client slug)

On the webview the cardholder enters the card number and the cardholder name printed on the plastic, and confirms. The webview associates the card with the user and activates it — no API integration is required on your side.

note

Use the sandbox host for testing: https://sandbox.migopayments.com/card-activation?client=migoDeveloper&userId=YOUR_USER_ID.

Option B — API activation (from your backend)

If you activate cards from your own backend, call the activation endpoint. It takes no request body (only the path parameters) and activates the given card for the given user:

curl -X POST https://api.ali.app/rest/users/{userId}/cards/{cardId}/activate \
  -H "Authorization: Bearer <token>" \
  -H "x-application-id: YOUR_APP_ID"

Both paths produce the same result: an active card ready to transact. For where activation sits in the overall onboarding sequence, see the Card issuance flow.

Block / unblock

Blocking is reversible and useful for lost-card events or temporary holds. Both endpoints take no body — they switch the card status to BLOCK / UNBLOCK:

# Block
curl -X POST https://api.ali.app/rest/users/{userId}/cards/{cardId}/block \
  -H "Authorization: Bearer <token>"

# Unblock
curl -X POST https://api.ali.app/rest/users/{userId}/cards/{cardId}/unblock \
  -H "Authorization: Bearer <token>"

A blocked card rejects all authorizations until it is unblocked.

The gateway also exposes a card-scoped variant of block/unblock keyed by card plus auth user (used by operator/permissioned flows rather than the cardholder's own session). Both take no body:

# Block / unblock a card for a specific auth user
curl -X POST https://api.ali.app/rest/cards/{cardId}/users/{authUserId}/block \
  -H "Authorization: Bearer <token>"

curl -X POST https://api.ali.app/rest/cards/{cardId}/users/{authUserId}/unblock \
  -H "Authorization: Bearer <token>"

Update alias

PATCH /cards/{cardId} updates only the card alias (UpdateCardDto):

curl -X PATCH https://api.ali.app/rest/cards/{cardId} \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "alias": "Groceries" }'

There is no state/reason field and no dedicated close-card endpoint. To unload a card balance, use a WITHDRAW_FUNDS operation — see Assign Funds.

Card details endpoint

curl "https://api.ali.app/rest/users/{userId}/cards/{cardId}?token=<view-token>" \
  -H "Authorization: Bearer <token>"

GET /users/{userId}/cards/{cardId} ("Check Card Details") returns sensitive card details (e.g. PAN/CVV) and requires a single-use view token in the token query parameter. It is not a plain balance/movements read.

Statements

The statements endpoint generates a monthly account statement for a given month and year (CreateStatementDto):

curl -X POST https://api.ali.app/rest/cards/{cardId}/statements \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "month": 3, "year": 2026 }'

Field	Required	Notes
month	yes	Month to generate (1–12)
year	yes	Four-digit year