Issue physical cards

Assign pre-manufactured physical cards to cardholders and activate them for use.

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"
  }'

Related

• Core concepts — Virtual vs. physical, Single vs. Share
• Card lifecycle — Freeze, unfreeze, or cancel cards
• Assign Card API
• Activate Card API
• Activation Code webhook
• Activation Status webhook