Skip to main content
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.

​
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 has zero effect on the underlying card or on any other token 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 wallet 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:
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 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. The token cannot be resumed after it has been deactivated. 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.
  • 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.