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

# Card Tokens and Status Notifications

> How to look up the tokens created for a card in digital wallets or at merchants, check their status, and receive webhook notifications when a token's status changes.

## 📄 Guide

When a cardholder adds a card to a digital wallet such as Apple Pay or Google Pay, or saves the card with a merchant or platform for future payments, the card scheme creates a **token** for that card. Payments are then made with the token instead of the real card number. One card can have several tokens at the same time, for example one in Apple Pay and one with an e-commerce platform.

DCS gives you two ways to keep track of them:

* **Query endpoint**: look up which tokens a card has and the status of each one, at any time.
* **Webhook notification**: DCS pushes a notification when a token's status changes. See [Events and schema](/en/partner-managed/how-to-use/webhooks/events-and-schema.md#card-tokenization).

> Only **Visa** cards are supported for now. Calling the query endpoint for a card of another scheme returns `DAPI_CARD_SCHEME_NOT_SUPPORT`.

***

## List the tokens of a card

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

| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `cardId` | string | Yes | Card ID |
| `tokenizationReferenceId` | string | No | Token reference ID. When supplied, only that token is returned |
| `tokenizationStatus` | string | No | Filter by token status. See "Token status" below for the values |

* All supplied conditions apply together; only tokens matching all of them are returned.
* **No pagination**: results are sorted by creation time, newest first, and at most the latest 500 are returned.
* Provisioning attempts that have not completed yet are not listed.
* When the card has no tokens, `tokenizations` is an empty array.
* If the card does not exist or does not belong to your enterprise, `DAPI_CARD_NOT_FOUND` is returned. If `tokenizationStatus` is not one of the allowed values, `DAPI_TOKENIZATION_STATUS_INVALID` is returned.

**Request example**

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

**Response fields (`data.tokenizations[]`)**

| Field | Type | Description |
| :- | :- | :- |
| `cardId` | string | Card ID |
| `tokenizationReferenceId` | string | Token reference ID; it uniquely identifies a token. **Its length is not fixed**: treat it as a string and do not assume a number of characters |
| `maskedTokenization` | string | The token's own number in masked form, showing only the last 4 digits, such as `******1111`. `null` if the token has no number of its own |
| `tokenizationRequestor` | string | Token requestor. See "Token requestors" below for the values |
| `tokenizationStatus` | string | Token status. See "Token status" below for the values |
| `reasonMessage` | string | Reason for the latest change, passed through as is. **May be empty**. It is not an enum and its values are not guaranteed, so do not use it in program logic |

**Response example**

```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"
      }
    ]
  }
}
```

***

## Token status

| `tokenizationStatus` | Meaning |
| :- | :- |
| `INACTIVE` | Created, not yet activated |
| `ACTIVE` | Activated |
| `SUSPENDED` | Suspended; can be resumed |
| `DEACTIVATED` | Deactivated |

* **There is no final status**: any status can change again. For example, when a cardholder adds the card back to a wallet, a `DEACTIVATED` token returns to `INACTIVE` and keeps its original `tokenizationReferenceId`. Keep processing later notifications for a token even after you receive `DEACTIVATED`.
* New status values may be added when other card schemes are supported. Handle values you do not recognize gracefully.

***

## Token requestors

`tokenizationRequestor` tells you who requested the token. The values are:

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

* `OTHERS` means the requestor is not one of the values listed above. **It does not mean the data is missing**.
* Values may be added over time. Handle values you do not recognize gracefully.

***

## Status notifications

When a token's status changes, DCS sends a webhook with `webhookType = PAYMENT_TOKENIZATION`. The fields in `data` are the same as those returned by the query endpoint, except that `maskedTokenization` is omitted if the token has no number of its own. See [Events and schema](/en/partner-managed/how-to-use/webhooks/events-and-schema.md#card-tokenization) for the field descriptions.

Keep the following in mind:

1. **Notifications are sent only when `tokenizationStatus` changes**, including when a new token is created. No notification is sent when only `reasonMessage` changes.
2. **Notifications start from the date this feature goes live**. Changes before that are not sent. To get the full current picture, call the query endpoint.
3. **The same notification may arrive twice**. Deduplicate by `webhookId`.
4. **Notifications are not guaranteed to arrive in order**: several notifications for the same token may arrive out of sequence. The query endpoint is the source of truth for a token's latest status. After receiving a notification, you can call it with the `cardId` and `tokenizationReferenceId` from the notification to confirm.

***

## Next steps

* [Push Provisioning / Digital Wallets](/en/partner-managed/how-to-use/cards/push-provisioning.md)—let cardholders add the card to a digital wallet from your app
* [Card management](/en/partner-managed/how-to-use/cards/card-management.md)—card status, freezing and termination
* [Events and schema](/en/partner-managed/how-to-use/webhooks/events-and-schema.md)—the common webhook envelope and the fields of each event
* [Authorization declines and error codes](/en/partner-managed/how-to-use/transactions/decline-codes.md)—error codes returned by the endpoints