Token lifecycle management
Understanding the token lifecycle process allows you to stay up to date on token information, such as metadata changes, token state changes, provisioned token details, and the status of bulk tokens. The token lifecycle can be managed by both you and the card issuer. Once a notification event occurs, the information is shared with all participants who have token processing.
To enable token lifecycle notifications, subscribe to the tokenLifecycleNotification event type in the Notifications API by performing a POST call to the /subscriptions endpoint and submitting the sub-types you wish to enable.
Here's a list of all the available token lifecycle notification sub-types:
| Notification even sub-type | Description |
|---|---|
| All | All notifications related to tokens. |
| CardDetailsUpdate | Notification about any metadata changes that occurred for the tokenized card product. |
| TokenStateChange | Notification about potential changes in the token and its state. |
| TokenProvisionUpdate | Notification about asynchronously provisioned token information for future processing. |
| BulkTokenUpdate | Notification about the status information of bulk tokenization files. |
Token state change
A token state change provides you with information about the token and whether it can be used for processing. After provisioning, the token is normally set to the ACTIVE state. However, you should be prepared for situations when a token is INACTIVE after provisioning. This indicates that the card issuer must complete an additional action(s) before they activate a token.
Token state management
Token state changes can be managed by either you or the card issuer. Additionally, you should provide this information when a change occurs between you and the consumer, such as the placing, holding, reactivation, or cancellation of a subscription.
A token can have multiple states during its lifecycle. The processing rules with specific states for a token must be honored, as shown in the following table:
| State | Definition | Processing |
|---|---|---|
| ACTIVE | The token is active for processing. | The token can be used for all transactions. |
| INACTIVE | The token is in an inactive state. | The token has been provisioned. However, it cannot be used for processing until it has been activated by the issuer of the card. |
| DELETED | The token has been deleted. | The token has been deleted and cannot be used for processing. Tokens must be removed from your card-on-file solutions. The card must be re-tokenized if the relationship between you and your consumer is re-established. You can also set this state to indicate that a consumer has terminated their subscription. |
| SUSPENDED | The token has been suspended from processing. | Indicates that the consumer or issuer has temporarily chosen to suspend transactions with the token. You can also set this state for a token if a consumer places their subscriptions on hold. The token must be activated before any transactions can be processed with the token. Note: Visa does not allow you to suspend tokens. |
The following diagram shows how a token's state can change during its lifecycle:
Card details update
The card details update lifecycle message provides you with information related to a tokenized card account, such as information about the token, and/or the underlying card account. Additional information provided includes issuer-provided updates, such as the terms and conditions.
There is a two-step process to receive updates:
- Use the token requestor identifier (TRID) to receive a lifecycle message.
- The TRID is then used to request an update using the GET api/tokens/{tokenReferenceId}/details endpoint.