签发实体卡

实体卡是预制好并寄送给你或你的持卡人的卡片。与虚拟卡不同，每张实体卡必须先绑定给一位持卡人，然后激活之后才能用于交易。

前置条件

一位 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": {}
}

绑定完成后会发生两件事：

card.activation.code webhook 会下发激活码。
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 码

通过管理卡片 PIN 修改 PIN。不传 type 时默认为 SET，按首次设置 PIN 处理。如需在不提供旧 PIN 的情况下重置已有 PIN，必须显式传入 type: RESET。响应仅表示异步受理；使用 card_order_id 通过订单查询或卡更新 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",
    "type": "RESET"
  }'

核心概念 —— 虚拟卡与实体卡、Single 与 Share
卡生命周期 —— 冻结、解除冻结或注销卡片
Assign Card API
Activate Card API
Activation Code webhook
Activation Status webhook

入门

持卡人

卡片

充值

管理与安全

集成

参考

步骤1：绑定卡片

步骤2：接收激活码

步骤3：激活卡片

重置 PIN 码

​步骤1：绑定卡片

​步骤2：接收激活码

​步骤3：激活卡片

​重置 PIN 码

​相关链接

步骤1：绑定卡片

步骤2：接收激活码

步骤3：激活卡片

重置 PIN 码

相关链接