Skip to main content
Migo Docs

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 paramRequiredPurpose
userIdYesThe cardholder who owns the card
clientNoBranding 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).

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, the flow has two steps: first link the existing physical card to the user, then activate it.

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"
}'
FieldRequiredNotes
cardyesCard number to link (must pass card verification)
aliasnoHuman-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 }'
FieldRequiredNotes
monthyesMonth to generate (1–12)
yearyesFour-digit year