跳转到主要内容
实体卡是预制好并寄送给你或你的持卡人的卡片。与虚拟卡不同，每张实体卡必须先绑定给一位持卡人，然后激活之后才能用于交易。
前置条件
  • 一位 cardholder_status: SUCCESS 的持卡人 —— 参见创建持卡人
  • 一个实体卡卡号（由 UQPAY 作为你卡片库存的一部分提供）
  • 如果使用 Single mode 产品，需要有充足的发卡账户余额

​
步骤1：绑定卡片

调用 Assign Card 接口，把一张实体卡关联到持卡人。 
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"
  }'
响应： 
{
  "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": {}
}
绑定完成后会发生两件事：
  1. card.activation.code webhook 会下发激活码。
  2. card.create.succeeded webhook 确认卡片已绑定。卡片会保持 PENDING 状态，直到被激活。
系统同时会发送一封包含激活码的邮件通知（可配置 —— 可以发给持卡人或你的机构邮箱，也可以关闭）。
激活码不会过期。

​
步骤2：接收激活码

订阅 card.activation.code webhook，即可以编程方式接收激活码。 
{
  "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"
  }
}

​
步骤3：激活卡片

使用激活码和一个 6 位 PIN 码，调用 Activate Card 接口。 
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"
  }'
PIN 码必须正好 6 位数字。
激活成功后，会触发一次 card.activation.status webhook，并发送一封邮件确认。 
{
  "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"
  }
}
卡片状态从 PENDING 变更为 ACTIVE。此时卡片已可用于交易，包括 ATM 取现（仅限支持的 BIN）。

​
重置 PIN 码

你可以随时通过 Reset Card PIN 接口修改卡片的 PIN 码。结果同步返回 —— 不会触发 webhook。 
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"
  }'