Card Lifecycle
This page is the canonical reference for card states and operations: setting up (activating) a card on a user, 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.
Set up a card on a userβ
A delivered card arrives inactive and cannot transact until it is set up on a user. There are two paths β pick whichever fits your integration. Only Option B (via API) requires linking the card first; in Option A the webview does it for you.
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 (including linking, which the webview performs internally).
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, the flow has two steps: first link the existing physical card to the user, then activate it.
Step 1 β Link the card to the userβ
POST /users/{userId}/cards links an existing physical card to the user. It requires a clientId query parameter and a body with the following fields:
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 |
Step 2 β Activate the cardβ
Then 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:
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:
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 |