Card Status
A card's status tells you whether it can be used. You can freeze, unfreeze, or cancel a card with one endpoint:
POST /api/v2/cards/update-status
The change is not instant. The card provider has to confirm it, so the card shows PROCESSING for a short time first.
Status reference
| Status | Meaning | Who sets it | Can the card be used? |
|---|---|---|---|
ACTIVE | The card is working normally | You (unfreeze) or the card provider | Yes |
FROZEN | Temporarily disabled. All payments are declined until you unfreeze it | You (freeze) | No |
PROCESSING | A status change is waiting for the card provider. Newly requested cards also show this until they are issued | UC | No new status request is accepted |
BLOCKED | Blocked by the card provider, for example for risk reasons. You cannot change it with the API. Send an appeal instead | Card provider | No |
PRE_CANCEL | The card provider is closing the card | Card provider | No |
CANCELLED | Closed for good. This cannot be undone | You (cancel) or the card provider | No |
You can only request ACTIVE, FROZEN, or CANCELLED.
Status flow
- Freeze:
ACTIVE→FROZEN - Unfreeze:
FROZEN→ACTIVE - Cancel:
ACTIVEorFROZEN→CANCELLED. This is final. - Blocked: only the card provider can block a card. It goes back to
ACTIVEonly when your appeal is approved.
How a status change works
- You send
POST /api/v2/cards/update-status. - UC checks the request. If a check fails, you get an error and the card does not change. See Errors.
- If the checks pass, you get
200straight away, and the card moves toPROCESSING. - UC sends the change to the card provider.
- Provider confirms: the card gets the new status. The app gets a WebSocket event and your server gets a
card.status.update.resultwebhook. - Provider rejects: the card goes back to the status it had before.
200. Wait for the WebSocket event or the webhook, or read the card again with GET /api/v2/cards.Request
POST /api/v2/cards/update-status
| Field | Type | Required | Notes |
|---|---|---|---|
card_id | number | Yes | The local numeric card id from List Issued Cards. Not the UUID |
card_status | string | Yes | ACTIVE, FROZEN, or CANCELLED |
note | string | No | Your reason. It is saved in the card's status history |
- Send
Authorization: Bearer <access_token>. - The card must belong to the signed-in user.
- The route accepts plain JSON or the encrypted wrapper.
- Limit:
60requests per minute per IP.
Freeze a card
Freezing stops all payments on the card until you unfreeze it. The card and its balance stay as they are.
curl -X POST "$BASE_URL/api/v2/cards/update-status" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"card_id": 508, "card_status": "FROZEN", "note": "Lost my phone"}'
Response: the request is accepted and the card is now PROCESSING.
{
"trace_id": "",
"status_code": 200,
"message": "Card status update requested successfully",
"data": {
"id": 508,
"uuid": "0b6f3a52-4c1e-4f0e-9a51-7d2f8f1c2a10",
"card_id": "3974bad1-247b-4939-8965-3223182fba1f",
"card_type": "VIRTUAL",
"card_currency": "USD",
"available_balance": "120.00",
"status": "PROCESSING",
"note": "Lost my phone"
}
}
data is the full card object. Only some fields are shown here.
When the card provider confirms, the app gets this WebSocket event on the card.events channel:
{
"event": "CARD_STATUS_UPDATE_EVENT",
"channel": "card.events",
"data": {
"id": 508,
"card_uuid": "0b6f3a52-4c1e-4f0e-9a51-7d2f8f1c2a10",
"card_id": "3974bad1-247b-4939-8965-3223182fba1f",
"card_number": "****1244",
"mobile_user_id": 77,
"status": "SUCCESS",
"card_status": "FROZEN",
"event_type": "CARD_STATUS_UPDATE_EVENT",
"updated_at": "2026-11-04T10:21:06Z"
}
}
Your server also gets the card.status.update.result webhook:
{
"agent_id": "3a5ea71a-db96-4efd-8223-4713bc9d6ba3",
"data": {
"card_id": "3974bad1-247b-4939-8965-3223182fba1f",
"card_status": "FROZEN",
"failure_reason": null,
"status": "SUCCESS"
},
"event_at": "2026-11-04T10:21:06.121447Z",
"event_id": "23837adf-128b-557a-b902-614d4b7e7a05",
"event_type": "card.status.update.result",
"version": "1"
}
Unfreeze a card
Unfreezing makes a FROZEN card work again.
curl -X POST "$BASE_URL/api/v2/cards/update-status" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"card_id": 508, "card_status": "ACTIVE"}'
The response, WebSocket event, and webhook look the same as for a freeze, with card_status set to ACTIVE.
BLOCKED card with this endpoint. Send a blocked-card appeal instead.Cancel a card
Cancelling closes the card for good. You can cancel an ACTIVE or a FROZEN card.
curl -X POST "$BASE_URL/api/v2/cards/update-status" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"card_id": 508, "card_status": "CANCELLED", "note": "No longer needed"}'
Balance handling on cancellation
When the card provider confirms the cancellation, UC settles the card balance with the owner's USDT wallet at 1 USD = 1 USDT:
| Card balance | What happens | Wallet transaction type |
|---|---|---|
| More than 0 | The balance is refunded to the USDT wallet | CARD_CANCELLATION_REFUND |
| Less than 0 | The amount owed is taken from the USDT wallet, even if this makes the wallet balance negative | CARD_CANCELLATION_DEBIT |
| 0 | Nothing moves | — |
- Settlement happens once per card. A repeated callback never moves money twice.
- The card balance becomes
0after settlement. - The user does not need to empty the card before cancelling.
Event sequence
200response, card isPROCESSING- The card provider confirms, and the card becomes
CANCELLED - The balance is settled with the USDT wallet
- WebSocket
CARD_STATUS_UPDATE_EVENTwithcard_status: "CANCELLED", and thecard.status.update.resultwebhook
Errors
These errors come back in the response body status_code. The card does not change.
status_code | When | Message |
|---|---|---|
400 | card_id or card_status is missing, or card_status is not ACTIVE, FROZEN, or CANCELLED | Validation error |
400 | The card is already PROCESSING | Your card is being processed. Please wait. |
400 | The card is BLOCKED | This card is blocked. Please submit an appeal request to continue. |
400 | The card already has the status you asked for | Card status is already FROZEN (for example) |
401 | The access token is missing or not valid | — |
404 | The card does not exist or does not belong to this user | Card not found |
429 | More than 60 requests per minute from one IP | — |
Webhooks
| Event | When |
|---|---|
card.status.update.result | The card provider has finished the status change. status is SUCCESS or FAILED, and card_status is the card's status after processing |
See the Integration Guide to verify the webhook signature.
Related
- Card List: find the card
idand read the current status - Blocked card appeal
- WebSocket
- Event Types