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

# 卡令牌查询与状态通知

> 说明如何查询一张卡在数字钱包或商户处生成的令牌（token）及其状态，以及令牌状态变化时的 Webhook 通知。

## 📄 正文

持卡人把卡加入 Apple Pay、Google Pay 等数字钱包，或在商户、平台处保存卡片用于后续付款时，卡组织会为这张卡生成一个**令牌（token）**，支付时用令牌代替真实卡号。一张卡可以同时有多个令牌，例如一个在 Apple Pay、一个在某个电商平台。

DCS 提供两种方式让您掌握令牌情况：

* **查询接口**：随时查询一张卡当前有哪些令牌、各自处于什么状态。
* **Webhook 通知**：令牌状态发生变化时主动推送，见 [事件与数据结构](/zh/partner-managed/how-to-use/webhooks/events-and-schema.md#卡令牌（payment_tokenization）)。

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

***

## 查询卡的令牌列表

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

| 参数 | 类型 | 必填 | 说明 |
| :- | :- | :- | :- |
| `cardId` | string | 是 | 卡 ID |
| `tokenizationReferenceId` | string | 否 | 令牌引用号，传了只返回这一条 |
| `tokenizationStatus` | string | 否 | 按令牌状态过滤，取值见下文「令牌状态」 |

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

**请求示例**

```json theme={null}
{
  "cardId": "card_xxx",
  "tokenizationStatus": "ACTIVE"
}
```

**返回字段（`data.tokenizations[]`）**

| 字段 | 类型 | 说明 |
| :- | :- | :- |
| `cardId` | string | 卡 ID |
| `tokenizationReferenceId` | string | 令牌引用号，一条令牌的唯一标识。**长度不固定**，请按字符串处理，不要假定位数 |
| `maskedTokenization` | string | 令牌自身卡号的脱敏形态，只保留后 4 位，如 `******1111`。令牌没有自身卡号时为 `null` |
| `tokenizationRequestor` | string | 令牌请求方，取值见下文「令牌请求方」 |
| `tokenizationStatus` | string | 令牌状态，取值见下文「令牌状态」 |
| `reasonMessage` | string | 最近一次变化的原因说明，原样透传，**可能为空**。不是枚举，取值不固定，请勿用于程序判断 |

**返回示例**

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

***

## 令牌状态

| `tokenizationStatus` | 含义 |
| :- | :- |
| `INACTIVE` | 已创建，尚未激活 |
| `ACTIVE` | 已激活 |
| `SUSPENDED` | 已暂停，可恢复 |
| `DEACTIVATED` | 已停用 |

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

***

## 令牌请求方

`tokenizationRequestor` 表示是谁发起生成了这个令牌，取值如下：

`APPLE_PAY`、`GOOGLE_PAY`、`ALIPAY`、`GRAB`、`STRIPE`、`OPENAI`、`ANTHROPIC`、`AMAZON`、`PAYPAL`、`PIPO`、`RESSO`、`UBER`、`SHOPEE`、`CTRIP`、`TWITTER`、`TRUEMONEY`、`AGODA`、`CLOUDFLARE`、`MICROSOFT`、`CTP`、`OTHERS`

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

***

## 状态通知

令牌状态变化时，DCS 推送 `webhookType = PAYMENT_TOKENIZATION` 的 Webhook，`data` 的字段与查询接口返回的字段一致，只是令牌没有自身卡号时不带 `maskedTokenization`。字段说明见 [事件与数据结构](/zh/partner-managed/how-to-use/webhooks/events-and-schema.md#卡令牌（payment_tokenization）)。

请注意以下几点：

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

***

## 下一步

* [Apple Pay 与 Google Pay 绑卡](/zh/partner-managed/how-to-use/cards/push-provisioning.md)——让持卡人在您的应用内把卡加入数字钱包
* [卡管理](/zh/partner-managed/how-to-use/cards/card-management.md)——卡状态、冻结与注销
* [事件与数据结构](/zh/partner-managed/how-to-use/webhooks/events-and-schema.md)——Webhook 公共结构与各事件字段
* [授权拒绝与错误码](/zh/partner-managed/how-to-use/transactions/decline-codes.md)——接口错误码说明