> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enfuce.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Token lifecycle management

> Manage the lifecycle of individual digital wallet tokens through the Enfuce Wallet API.

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

| **Card event**               | **Token behaviour**                                                         |
| ---------------------------- | --------------------------------------------------------------------------- |
| Card temporarily blocked     | Associated tokens are automatically suspended                               |
| Temporary card block removed | Associated tokens are automatically resumed                                 |
| Card closed                  | Associated tokens are automatically deactivated                             |
| Card closed due to fraud     | Associated tokens are automatically deactivated                             |
| Lost or stolen card replaced | Existing tokens can be transferred to the replacement card where applicable |

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:

| **Action**   | **Description**                                                                                  |
| ------------ | ------------------------------------------------------------------------------------------------ |
| `activate`   | Activates an inactive token after the required authentication or verification has been completed |
| `suspend`    | Temporarily prevents the token from being used. The token can later be resumed                   |
| `resume`     | Restores a suspended token and makes it available for use again                                  |
| `deactivate` | Permanently disables the token                                                                   |

<Warning>
  `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.
</Warning>

## Token status

| **Token status** | **What it means**                                                                                                                                                     |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ACTIVE`         | The token has been successfully provisioned and activated and is available for payment                                                                                |
| `INACTIVE`       | The token has been provisioned, but activation has not yet been completed. Further cardholder authentication or verification is required before the token can be used |
| `SUSPENDED`      | The token was previously available for use but has been temporarily suspended. It can be resumed                                                                      |
| `DEACTIVE`       | The token has been permanently deactivated and can no longer be used                                                                                                  |

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:

<Steps>
  <Step title="Retrieve the tokens">
    Retrieve the tokens associated with the card using the `Get tokens for a given cardId` endpoint.
  </Step>

  <Step title="Identify the token">
    Identify the token you want to manage using its `tokenId`.
  </Step>

  <Step title="Change the status">
    Use the `Change token status` endpoint with the appropriate lifecycle action.
  </Step>
</Steps>

### Retrieve tokens associated with a card

Use:

```text theme={null}
GET /v1/card/{cardId}/tokens
```

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:

```text theme={null}
PUT /v1/tokens/{tokenId}/{action}
```

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](/payment/api/token-management/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.

<Warning>
  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.
</Warning>

### 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.