Card Tokens and Status Notifications

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

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

{
  "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

{
  "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 for the field descriptions. Keep the following in mind:

Notifications are sent only when tokenizationStatus changes, including when a new token is created. No notification is sent when only reasonMessage changes.
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.
The same notification may arrive twice. Deduplicate by webhookId.
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—let cardholders add the card to a digital wallet from your app
Card management—card status, freezing and termination
Events and schema—the common webhook envelope and the fields of each event
Authorization declines and error codes—error codes returned by the endpoints

Getting Started

Basic Concepts

How to Use

Integration Resources

Customer Success

📄 Guide

List the tokens of a card

Token status

Token requestors

Status notifications

Next steps

​📄 Guide

​List the tokens of a card

​Token status

​Token requestors

​Status notifications

​Next steps

📄 Guide

List the tokens of a card

Token status

Token requestors

Status notifications

Next steps