Cards

Card Status

Card statuses, how they change, and how to freeze, unfreeze, or cancel a card.

A card's status tells you whether it can be used. You can freeze, unfreeze, or cancel a card with one endpoint:

POST /api/v1/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

StatusMeaningWho sets itCan the card be used?
ACTIVEThe card is working normallyYou (unfreeze) or the card providerYes
FROZENTemporarily disabled. All payments are declined until you unfreeze itYou (freeze)No
PROCESSINGA status change is waiting for the card provider. Newly requested cards also show this until they are issuedUCNo new status request is accepted
BLOCKEDBlocked by the card provider, for example for risk reasons. You cannot change it with the API. Send an appeal insteadCard providerNo
PRE_CANCELThe card provider is closing the cardCard providerNo
CANCELLEDClosed for good. This cannot be undoneYou (cancel) or the card providerNo

You can only request ACTIVE, FROZEN, or CANCELLED.

Status flow

Card status flow: an ACTIVE card can be frozen and a FROZEN card can be unfrozen back to ACTIVE. ACTIVE and FROZEN cards can be cancelled, and CANCELLED is final. The card provider can block an ACTIVE card; a BLOCKED card goes back to ACTIVE only when an appeal is approved.You can changeCard providerFinalACTIVECard can be usedFROZENAll payments declinedBLOCKEDCannot be changed by APICANCELLEDClosed · cannot be undoneFreezeUnfreezeProvider blocksAppeal approvedCancel
  • Freeze: ACTIVE → FROZEN
  • Unfreeze: FROZEN → ACTIVE
  • Cancel: ACTIVE or FROZEN → CANCELLED. This is final.
  • Blocked: only the card provider can block a card. It goes back to ACTIVE only when your appeal is approved.

How a status change works

How a status change works: the client sends POST update-status. If a check fails the API returns an error and nothing changes. Otherwise the card moves to PROCESSING and the request goes to the card provider. If the provider confirms, the card gets the new status and the app and your server are notified; a cancelled card also has its remaining balance settled with the USDT wallet. If the provider rejects the request, the card goes back to its previous status.1 · Request2 · Done2 · RejectedPOST /api/v1/cards/update-statuscard_status = FROZEN · ACTIVE · CANCELLEDCheck failsError · no changePROCESSINGSent to card provider · waitNew status savedWebSocket + webhook sentIf CANCELLEDBalance → USDT walletPrevious statusChange rolled backAccepted · 200Provider confirmsProvider rejectsCancel only
  1. You send POST /api/v1/cards/update-status.
  2. UC checks the request. If a check fails, you get an error and the card does not change. See Errors.
  3. If the checks pass, you get 200 straight away, and the card moves to PROCESSING.
  4. UC sends the change to the card provider.
  5. Provider confirms: the card gets the new status. The app gets a WebSocket event.
  6. Provider rejects: the card goes back to the status it had before.
Do not show the new status as soon as you get 200. Wait for the WebSocket event, or read the card again with GET /api/v1/cards.

Request

POST /api/v1/cards/update-status

FieldTypeRequiredNotes
card_idnumberYesThe local numeric card id from List Issued Cards. Not the UUID
card_statusstringYesACTIVE, FROZEN, or CANCELLED
notestringNoYour 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: 60 requests 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/v1/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"
  }
}

Unfreeze a card

Unfreezing makes a FROZEN card work again.

curl -X POST "$BASE_URL/api/v1/cards/update-status" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"card_id": 508, "card_status": "ACTIVE"}'

The response and WebSocket event look the same as for a freeze, with card_status set to ACTIVE.

You cannot unfreeze a 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/v1/cards/update-status" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"card_id": 508, "card_status": "CANCELLED", "note": "No longer needed"}'
A cancelled card cannot be made active again. Ask the user to confirm before you send this request.

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 balanceWhat happensWallet transaction type
More than 0The balance is refunded to the USDT walletCARD_CANCELLATION_REFUND
Less than 0The amount owed is taken from the USDT wallet, even if this makes the wallet balance negativeCARD_CANCELLATION_DEBIT
0Nothing moves—
  • Settlement happens once per card. A repeated callback never moves money twice.
  • The card balance becomes 0 after settlement.
  • The user does not need to empty the card before cancelling.

Event sequence

  1. 200 response, card is PROCESSING
  2. The card provider confirms, and the card becomes CANCELLED
  3. The balance is settled with the USDT wallet
  4. WebSocket CARD_STATUS_UPDATE_EVENT with card_status: "CANCELLED"

Errors

These errors come back in the response body status_code. The card does not change.

status_codeWhenMessage
400card_id or card_status is missing, or card_status is not ACTIVE, FROZEN, or CANCELLEDValidation error
400The card is already PROCESSINGYour card is being processed. Please wait.
400The card is BLOCKEDThis card is blocked. Please submit an appeal request to continue.
400The card already has the status you asked forCard status is already FROZEN (for example)
401The access token is missing or not valid—
404The card does not exist or does not belong to this userCard not found
429More than 60 requests per minute from one IP—
Copyright © 2026