Card token APIs
A card token is a digital substitute of a card number used for payments from a mobile wallet (Apple Pay, Google Pay) or by other token requestors (e.g. merchants storing the card for recurring payments). Instead of the real card number (PAN), the payment uses a token number (DPAN) linked to the card. One card can have several tokens — e.g. one per phone or watch the cardholder added the card to.
How tokens come into existence
Tokens are not created through the LightCMS API. The cardholder adds the card to a wallet on their device, the wallet provider asks the card scheme and the card processor to issue a token, and LightCMS is informed by the card processor. From then on LightCMS keeps track of the token and of every change of it — the token API gives the external system a read view of this information.
A card can be tokenized when its CPD allows it. Such a card can be used through its tokens right
after it is created — it is in DIGITALLY_ACTIVE status even before its card plastic is activated
(see Card APIs).
Identifying a token
A token is known under several identifiers, because several parties take part in its life:
| Identifier | Assigned by | Typical use |
|---|---|---|
cmsTokenId |
LightCMS | Stable reference to the token for all LightCMS token APIs |
tokenId |
Card processor | Matching with the card processor's records |
tokenUniqueReferenceId |
Card scheme / token service | Matching with wallet provider and card scheme records |
| DPAN (masked) | Card scheme / token service | The token number as it appears in transactions |
The external system should store cmsTokenId when it wants to refer to a token later — the token
APIs look a token up by cmsTokenId only.
How to use token APIs
GET /v3/cards/{cardId}/tokens
List the tokens of a card (e.g. to show it in a mobile or internet banking application). Contains information on which devices and in which wallets the card is enrolled and whether each token is active.
GET /v3/cards/tokens/{cmsTokenId}
Returns detail information of the token.
GET /v3/cards/tokens/{cmsTokenId}/history
The token history shows how the token evolved — when it was provisioned, on which device, and every change of its status.
Token status
LightCMS holds status of token. This status is derived from internal cmsStatus and status of card processor cpStatus. Only the final status is relevant for external systems.
List of statuses:
- ACTIVE - token can be used for the payments
- INACTIVE - token is terminated and cannot be used again
- SUSPENDED - token is temporarily unusable
- DEACTIVATED - same as INACTIVE
A token belongs to a card, so it can be used only while the card itself allows it — a blocked or revoked card cannot be used through its tokens either.
Tokens and card replacement
When a card is replaced, its tokens are carried over to the
successor card. The cardholder does not have to add the new card to their wallets again, and the
token keeps its cmsTokenId and history. The token APIs return the token under the successor card
from then on.
Risk information
When a token is provisioned, the wallet provider and the card scheme assess the risk of the
request — e.g. how trustworthy the wallet account and the device are, and whether the wallet
provider recommends approving the token. LightCMS stores this assessment with the token. The
meaning of the codes can be resolved through the enumeration endpoints
(GET /v3/enumeration/token…, GET /v3/enumeration/walletProviderRecommendation).