卡令牌查询与状态通知

​

📄 正文

• 查询接口：随时查询一张卡当前有哪些令牌、各自处于什么状态。
• Webhook 通知：令牌状态发生变化时主动推送，见 事件与数据结构。

目前只支持 Visa 卡。对其他卡组织的卡调用查询接口，会返回 DAPI_CARD_SCHEME_NOT_SUPPORT。

​

查询卡的令牌列表

POST /open-api/card/v1/tokenization-list

• 多个条件同时生效，返回同时满足的令牌。
• 不分页：按创建时间倒序，最多返回最近的 500 条。
• 尚未完成的绑卡不会出现在列表中。
• 该卡没有任何令牌时，tokenizations 为空数组。
• 卡不存在或不属于您的企业时，返回 DAPI_CARD_NOT_FOUND；tokenizationStatus 传了不在取值范围内的值时，返回 DAPI_TOKENIZATION_STATUS_INVALID。

{
  "cardId": "card_xxx",
  "tokenizationStatus": "ACTIVE"
}

{
  "code": "...",
  "message": "...",
  "data": {
    "tokenizations": [
      {
        "cardId": "card_xxx",
        "tokenizationReferenceId": "DNITHE000000000000000002",
        "maskedTokenization": "******1111",
        "tokenizationRequestor": "APPLE_PAY",
        "tokenizationStatus": "ACTIVE",
        "reasonMessage": null
      },
      {
        "cardId": "card_xxx",
        "tokenizationReferenceId": "DNITHE000000000000000001",
        "maskedTokenization": "******2222",
        "tokenizationRequestor": "GOOGLE_PAY",
        "tokenizationStatus": "SUSPENDED",
        "reasonMessage": "*Suspend due to card blocked"
      }
    ]
  }
}

​

令牌状态

• 没有终态：任何状态都可能再次变化。例如持卡人把卡重新加回钱包时，DEACTIVATED 的令牌会回到 INACTIVE，并沿用原来的 tokenizationReferenceId。收到 DEACTIVATED 后，请继续处理这条令牌后续的通知。
• 后续接入其他卡组织时，状态取值可能增加，请对无法识别的取值做兼容处理。

​

令牌请求方

• 返回 OTHERS 表示请求方不在上面列出的取值中，不代表数据缺失。
• 取值会随业务需要增加，请对无法识别的取值做兼容处理。

​

状态通知

1. 只在 tokenizationStatus 变化时推送，新生成令牌时也会推送。reasonMessage 变了但状态没变时不推送。
2. 从功能上线起推送，不补推上线前的历史变化。需要当前全量情况时，请调用查询接口。
3. 同一条通知可能收到两次，请按 webhookId 去重。
4. 不保证按发生顺序到达：同一令牌的多条通知可能先后颠倒，令牌的最新状态以查询接口为准。收到通知后，可以用通知里的 cardId 和 tokenizationReferenceId 调用查询接口核对。

​

下一步

• Apple Pay 与 Google Pay 绑卡——让持卡人在您的应用内把卡加入数字钱包
• 卡管理——卡状态、冻结与注销
• 事件与数据结构——Webhook 公共结构与各事件字段
• 授权拒绝与错误码——接口错误码说明