> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Info>
  **Prerequisites**

  * A cardholder with `cardholder_status: SUCCESS` — see [Create cardholders](/card-issuance/v1.6/guide/create-and-manage-cardholders)
  * A physical card number (provided by UQPAY as part of your card inventory)
  * Sufficient issuing balance if using a Single mode product
</Info>

## Step 1: Assign the card

Call the [Assign Card](/card-issuance/v1.6/api-reference/assign-card) endpoint to link a physical card to a cardholder.

```bash theme={null}
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:**

```json theme={null}
{
  "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).

<Note>
  The activation code does not expire.
</Note>

## Step 2: Receive the activation code

Subscribe to the `card.activation.code` webhook to receive the activation code programmatically.

```json theme={null}
{
  "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](/card-issuance/v1.6/api-reference/activate-card) endpoint with the activation code and a 6-digit PIN.

```bash theme={null}
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"
  }'
```

<Warning>
  The PIN must be exactly **6 digits**.
</Warning>

Upon successful activation, a `card.activation.status` webhook fires and an email confirmation is sent.

```json theme={null}
{
  "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](/card-issuance/v1.6/api-reference/reset-pin) endpoint. The result is returned synchronously — no webhook is triggered.

```bash theme={null}
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](/card-issuance/v1.6/guide/core-concepts) — Virtual vs. physical, Single vs. Share
* [Card lifecycle](/card-issuance/v1.6/guide/card-lifecycle) — Freeze, unfreeze, or cancel cards
* [Assign Card API](/card-issuance/v1.6/api-reference/assign-card)
* [Activate Card API](/card-issuance/v1.6/api-reference/activate-card)
* [Activation Code webhook](/card-issuance/v1.6/webhooks/activation-code)
* [Activation Status webhook](/card-issuance/v1.6/webhooks/activation-status)