Skip to main content
Physical cards are pre-manufactured and shipped to you or your cardholders. Unlike virtual cards, each physical card must be assigned to a cardholder and then activated before it can be used for transactions.
Prerequisites
  • A cardholder with cardholder_status: SUCCESS — see Create cardholders
  • A physical card number (provided by UQPAY as part of your card inventory)
  • Sufficient issuing balance if using a Single mode product

​
Step 1: Assign the card

Call the Assign Card endpoint to link a physical card to a cardholder. 
curl -X POST https://api-sandbox.uqpaytech.com/api/v1/issuing/cards/assign \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{
    "cardholder_id": "4438b25d-caa7-4dcf-a8e0-970f05a7bf31",
    "card_number": "4096360800121514",
    "card_currency": "SGD",
    "card_mode": "SINGLE"
  }'
Response: 
{
  "card_order_id": "07ad04df-39dd-44a1-bbc5-15b2eff6f709",
  "card_id": "b2c1b725-d8f1-4fbb-88a1-41bf9ffc8ead",
  "card_status": "PENDING",
  "order_status": "PENDING",
  "create_time": "2025-07-27T21:00:05+08:00",
  "risk_controls": {}
}
After assignment, two things happen:
  1. A card.activation.code webhook delivers the activation code.
  2. A card.create.succeeded webhook confirms the card was assigned. The card remains in PENDING status until activated.
An email notification with the activation code is also sent (configurable — can go to the cardholder or your institution email, or be disabled).
The activation code does not expire.

​
Step 2: Receive the activation code

Subscribe to the card.activation.code webhook to receive the activation code programmatically. 
{
  "version": "V1.6.0",
  "event_name": "ISSUING",
  "event_type": "card.activation.code",
  "event_id": "759e6599-d3cc-415e-94e7-dfdd5d3401d1",
  "source_id": "b2c1b725-d8f1-4fbb-88a1-41bf9ffc8ead",
  "data": {
    "activation_code": "81534005",
    "card_id": "b2c1b725-d8f1-4fbb-88a1-41bf9ffc8ead",
    "card_number": "40963608****1514"
  }
}

​
Step 3: Activate the card

Call the Activate Card endpoint with the activation code and a 6-digit PIN. 
curl -X POST https://api-sandbox.uqpaytech.com/api/v1/issuing/cards/activate \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{
    "card_id": "b2c1b725-d8f1-4fbb-88a1-41bf9ffc8ead",
    "activation_code": "81534005",
    "pin": "123456"
  }'
The PIN must be exactly 6 digits.
Upon successful activation, a card.activation.status webhook fires and an email confirmation is sent. 
{
  "version": "V1.6.0",
  "event_name": "ISSUING",
  "event_type": "card.activation.status",
  "event_id": "bd0a312b-25a3-46aa-b553-6b360d3a6ba7",
  "source_id": "b2c1b725-d8f1-4fbb-88a1-41bf9ffc8ead",
  "data": {
    "activation_status": "Activated",
    "card_id": "b2c1b725-d8f1-4fbb-88a1-41bf9ffc8ead",
    "card_number": "40963608****1514"
  }
}
The card status transitions from PENDING to ACTIVE. The card is now ready for transactions, including ATM withdrawals (for eligible BINs).

​
Reset PIN

You can change the card PIN at any time using the Reset Card PIN endpoint. The result is returned synchronously — no webhook is triggered. 
curl -X POST https://api-sandbox.uqpaytech.com/api/v1/issuing/cards/pin \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{
    "card_id": "b2c1b725-d8f1-4fbb-88a1-41bf9ffc8ead",
    "pin": "654321"
  }'