Skip to main content
A payment token is a secure digital replacement for a card’s actual card number (PAN). It is used instead of the real card number when making payments, helping to keep the card details protected. Payment tokens are commonly used when a card is added to a digital wallet, such as Apple Pay or Google Pay, but they can also be used in other payment services, such as Click to Pay. Token lifecycle management means controlling whether an individual token can be used for payments throughout its lifecycle. This includes activating, suspending, resuming, or permanently deactivating the token. Enfuce keeps a digital wallet token’s status in sync with its card automatically. When a card is blocked, its tokens are suspended along with it; when the card is unblocked, they’re resumed. That link between card and token is always on: there is no way to turn it off, and a token cannot be made to ignore a card status change. What you can do is manage an individual token directly through the Enfuce Wallet API. This is a separate, finer layer of control for situations where the card itself is fine, but a single token or device needs its own treatment. This matters when, for example, a cardholder loses one device but should keep their physical card and their other wallets working, or when a single token needs a status correction that has nothing to do with the card. Token lifecycle management through the API is supported for both Mastercard and Visa tokens, with one exception for activation, covered below.

​
Default behaviour: how card status changes affect tokens

This always happens: a card status change can’t be applied without affecting its tokens. So when something has gone wrong with the card itself, such as a compromised card that should stop working everywhere, changing the card’s status is enough on its own: every token linked to it is handled automatically. The reverse holds too: managing an individual token does not change the status of the underlying card or other tokens linked to the same card. Acting on one token is fully contained to that token: the card and every other wallet stay exactly as they were. Use individual token lifecycle management when the event concerns a specific token or device while the card should otherwise remain available. For example, a cardholder might lose one device but still have their physical card and another token active elsewhere.

​
Token lifecycle actions

You can perform the following actions on an individual token, exposed through the Wallet API’s Change token status endpoint:
Activation through the API is only possible for Visa tokens. Mastercard does not send Enfuce the token details until after the token has been activated, so an inactive Mastercard token cannot be activated this way. In most cases, an inactive Mastercard token needs to be activated through the Mastercard’s MDES portal instead.
activate is intended for supporting staff use only and should not be exposed directly to cardholders. Activation depends on confirming that the required authentication or verification has actually been completed. That is a judgement call for your operations team, not something to surface as a self-service option in a cardholder-facing app or portal.

​
Token status

An INACTIVE token typically represents one still going through the provisioning process. When a cardholder adds a card to a digital wallet, the token isn’t necessarily available for payment right away. Depending on the outcome of the authentication and risk decision made by Enfuce, the relevant network (Visa or Mastercard), and the digital wallet provider, the token can become active, remain pending activation, or have its provisioning request declined. Until the required authentication has been completed, it stays INACTIVE. This is also why activate is distinct from resume:
  • Use activate when a token is awaiting activation and has not yet become active.
  • Use resume when a previously active token was suspended and should now be restored.

​
How token lifecycle management works

To manage an individual token:
1

Retrieve the tokens

Retrieve the tokens associated with the card using the Get tokens for a given cardId endpoint.
2

Identify the token

Identify the token you want to manage using its tokenId.
3

Change the status

Use the Change token status endpoint with the appropriate lifecycle action.

​
Retrieve tokens associated with a card

Use:
The endpoint returns the tokens associated with the card. The available information includes the Token Unique Reference ID, Token Requestor ID, wallet provider, and token status. The response also contains the tokenId required for lifecycle management, and device information where applicable: the device name, device type (phone, tablet, watch, vehicle, and so on), a masked device identifier, and the last four digits of any associated mobile number. Device information is only present for tokens provisioned to a physical device, such as mobile wallets like Apple Pay, Google Pay, or Samsung Pay. It’s absent for tokens that aren’t tied to a device, such as Visa Click to Pay. Where present, it can help you identify the correct token when the same card has been provisioned to multiple devices.

​
Change the status of an individual token

Use:
Provide the tokenId of the token you want to manage and one of the supported actions: activate, suspend, resume, deactivate. The tokenId used for the lifecycle operation can be retrieved using the Get tokens endpoint. For the complete request and response specification, see the Change token status endpoint in the Wallet API documentation.

​
Common use cases

​
Activate an inactive token

Once the cardholder has successfully completed the required authentication or verification for a token stuck in INACTIVE, you can use the activate action to bring it into service. This applies to Visa tokens only; see the note above for how to handle an inactive Mastercard token.
This action is intended for supporting staff use only and should not be exposed directly to cardholders. Activation depends on confirming that the required authentication or verification has actually been completed. That is a judgement call for your operations team, not something to surface as a self-service option in a cardholder-facing app or portal.

​
Temporarily suspend a token

A cardholder may report that a device containing their digital wallet is temporarily unavailable or potentially lost, while the underlying card itself should remain available. Instead of blocking the card and consequently affecting all associated tokens, you can suspend the token associated with the affected device. The physical card and other tokens associated with the card can remain available for use. If the device is recovered and it is safe to continue using the token, use the resume action to restore the suspended token.

​
Resume a suspended token

Use the resume action when a previously active token has been suspended and should become available for payment again. For example, if a token was temporarily suspended because the cardholder could not locate their device, the token can be resumed once the device has been recovered and its use is considered safe.

​
Permanently deactivate a token

If a device has been permanently lost, compromised, or should no longer be trusted, you can deactivate the token associated with that device. Unlike suspension, deactivation is permanent. Once a token is deactivated, it cannot be brought back by resume or activate, or by any other means. If the cardholder later wants to use the card in a digital wallet again, a new token needs to be provisioned.

​
Correcting a token status inconsistency

In some situations, the status of an individual token may not reflect the intended state due to a prior lifecycle event, technical issue, or external update. For example, a token may remain INACTIVE after the required activation steps have been completed, or remain SUSPENDED even though it should be available for use. With token lifecycle management, you can fix this on the affected token directly, independently of the card:
  • Use activate when an inactive token should be activated after the required authentication or verification has been completed. This applies to Visa tokens only; an inactive Mastercard token typically needs to be activated through the Mastercard’s MDES portal.
  • Use resume when a suspended token should be restored to active use. Before changing the token status, make sure that the reason for the current status has been resolved and that the token is eligible to be activated or resumed.