Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers-sandbox.uqpaytech.com/llms.txt

Use this file to discover all available pages before exploring further.

Every card follows a lifecycle from creation to cancellation. You manage transitions through the Update Card Status endpoint.

​
Status reference

StatusDescription
PENDINGCard creation request received and processing
ACTIVECard is ready for transactions
FROZENAll authorizations declined; card can be reactivated
BLOCKEDBlocked by UQPAY due to suspicious activity
PRE_CANCELPre-cancellation state; authorizations declined
CANCELLEDPermanently deactivated
FAILEDCard creation failed

​
Status flow

​
Freeze a card

Freezing temporarily disables all transactions. All incoming authorizations are declined until the card is unfrozen. 
curl -X POST https://api-sandbox.uqpaytech.com/api/v1/issuing/cards/{card_id}/status \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{"card_status": "FROZEN"}'
Response: 
{
  "card_id": "c0cef051-29c5-4796-b86a-cd5b684bfad7",
  "card_order_id": "c0cef051-29c5-4796-b86a-cd5ee34bfad7",
  "order_status": "PENDING"
}
A card.status.update.succeeded webhook fires once the freeze is applied: 
{
  "version": "V1.6.0",
  "event_name": "ISSUING",
  "event_type": "card.status.update.succeeded",
  "event_id": "54daa345-889a-4488-9002-935f63b7d3c9",
  "source_id": "3f3d036e-732c-4f9e-a4b7-3019c0adf749",
  "data": {
    "card_id": "3974bad1-247b-4939-8965-3223182fba1f",
    "card_number": "46119903****1244",
    "card_status": "FROZEN",
    "update_time": "2025-07-21T21:11:06+08:00"
  }
}

​
Unfreeze a card

To reactivate a frozen card, set the status back to ACTIVE: 
curl -X POST https://api-sandbox.uqpaytech.com/api/v1/issuing/cards/{card_id}/status \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{"card_status": "ACTIVE"}'

​
Cancel a card

Cancellation is irreversible. A cancelled card cannot be reactivated.
Set the card status to CANCELLED: 
curl -X POST https://api-sandbox.uqpaytech.com/api/v1/issuing/cards/{card_id}/status \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{"card_status": "CANCELLED"}'
The card first transitions to PRE_CANCEL:
  • All new authorizations are declined.
  • Previously authorized but unsettled transactions continue to settle normally.
  • After a 30-day waiting period, the card moves to CANCELLED.

​
Balance handling on cancellation

Card modeWhat happens to remaining balance
SingleRemaining balance is returned to the issuing balance automatically after the waiting period
ShareNo refund needed — no funds were transferred into the card
To avoid the 30-day wait, withdraw the remaining balance before cancelling the card using the Card Withdraw endpoint.

​
Webhook sequence

  1. card.status.update.succeeded with card_status: PRE_CANCEL — immediately after the cancel request
  2. card.status.update.succeeded with card_status: CANCELLED — after the waiting period ends

​
Webhooks

Status transitions trigger a card.status.update.succeeded webhook for these statuses: ACTIVE, FROZEN, BLOCKED, PRE_CANCEL, CANCELLED. This webhook does not fire for the initial activation of a physical card or the default ACTIVE status when a virtual card is issued. Those are covered by the Card Created and Activation Status webhooks respectively.