Token Lifecycle Management

A token has a life: created, activated, possibly suspended and resumed, eventually deleted or replaced. Its expiry is normally tied to the expiry of the PAN it was provisioned from.

Managing that life is your responsibility, and it is the part of tokenization most often under-scoped. Provisioning is a project. Lifecycle is forever.

States and transitions

stateDiagram-v2
    [*] --> Unmapped: provisioning starts
    Unmapped --> Active: digitization.complete
    Unmapped --> [*]: Digitization_Exception

    Active --> Suspended: StopToken
    Suspended --> Active: UnStopToken
    Active --> Deleted: DeleteToken
    Suspended --> Deleted: DeleteToken

    Active --> Active: Replacement
    Active --> Deleted: Deleted_from_device

Who can change a token's state

Two directions, and you need to handle both.

You call us

All four take card_id. token_reference is the Token Unique Reference you stored from digitization.complete.

📘

Stop and unstop can operate on the whole card. On /token/stop and /token/unstop, token_reference is optional. Omit it and the action applies to every token on the card. That is usually what you want when a card is lost: one call, every device.

On /token/delete, token_reference is required. Deletion is per token.

We call you

UnDosTres notifies you of every state change with an AdministrativeMessage, whoever triggered it.

All five carry the same KLV set: 254 digitized pan, 255 wallet id, 910 device id, 911 pan expiry, 912 masked FPAN, 913 Token Unique Reference, 915 token requestor id, 923 event type, 924 event reason code. All five expect resultCode back.

❗️

You will receive events you did not trigger. A cardholder deleting a card from their phone generates digitization.event.Deleted_from_device with no API call from you. If your token store only updates when you call an endpoint, it will drift out of sync within days of launch. Update state on the callback, not on your own request.

Reason codes

/token/stop, /token/unstop and /token/delete all take a reason:

When unstopping, use the same reason you used to stop.

/token/activate uses a different, shorter set:

Use C when a call centre agent did the authentication. It is what distinguishes an agent-assisted activation in any later review, so it is worth getting right rather than defaulting everything to A.

All four endpoints accept an optional free-text comment, up to 500 characters. Use it. When someone investigates a token six months from now, "Cardholder reported lost, case INC-4471" is worth a great deal more than an empty field.

The rule that matters most

Map your card statuses onto token statuses, and enforce it automatically.

You have your own card lifecycle, with whatever statuses your business uses. Tokens have three practical states: active, temporarily suspended, and deleted. Every card status you support needs a defined token consequence.

The one that causes real harm if missed:

❗️

If a card is permanently closed, its tokens must be deleted. A closed card whose tokens are still active leaves a live payment credential sitting in a cardholder's phone. Deleting the card in your system does nothing to the wallet on its own. You must call /token/delete for each token, or /token/stop without a token_reference if the closure may be reversed.

A suggested mapping to adapt:

Review your account statuses too, not just card statuses. If closing an account closes its cards, the token consequence has to follow.

Card renewal and replacement

When a card is renewed or replaced, the token does not have to be re-provisioned. The token-to-PAN mapping is updated behind the scenes, and the cardholder keeps paying with their phone without touching anything. The wallet may show updated last-four digits.

You will see digitization.event.Replacement when this happens.

Do not delete tokens on renewal. Deleting them forces every cardholder to re-add their card to every wallet, which is a support incident and an avoidable drop in wallet activity.

Visibility

Two read endpoints, and the difference matters:

Use ListActiveTokens for anything a cardholder sees, such as "your card is in 2 wallets". Use ListAllTokens for support and investigation, because it is the only one that shows failed and deleted attempts.

Neither is a substitute for your own token store. Store what arrives on the callbacks; use these to reconcile.

Related

• Use Cases and Runbook — the situation-to-action lookup
• Manual Provisioning
• Tokenization Overview — token states explained