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

# Token Lifecycle Management

> A token has a life of its own once provisioned: it can be suspended, reactivated, or terminated, and it responds to what happens to the card behind it.

## Token States

A token moves through these states:

| State              | Meaning                                                             |
| ------------------ | ------------------------------------------------------------------- |
| `REQUESTED`        | Provisioning has been requested and is being decided                |
| `ACTIVE`           | The token can transact. Reachable from `REQUESTED` or `SUSPENDED`.  |
| `REQUEST_DECLINED` | The request was refused, or the cardholder did not complete step-up |
| `SUSPENDED`        | Temporarily blocked. Reachable from `ACTIVE`, and reversible.       |
| `TERMINATED`       | Permanently dead. Irreversible.                                     |

<Info>
  **`state` is the field that matters.** A token with `state` of `ACTIVE` can transact. The Synctera console also shows a processor-level fulfillment status reflecting the colour-path decision — useful context when diagnosing a challenged provisioning, but it is not exposed as a top-level API field and can lag behind `state` after a step-up. Trust `state`.
</Info>

Card lifecycle events propagate to tokens automatically:

* **Reissue** — tokens move to the replacement card, so the cardholder does not re-add it to their wallet
* **Termination** — tokens on the card are terminated
* **Reassignment** — when a virtual card moves to a new cardholder, tokens provisioned to the previous cardholder are terminated

<Info>
  A token can remain active after the cardholder removes the card from their wallet. `removed_from_wallet_time` records the removal; `state` records whether the token can still transact. Terminate it explicitly if it should not.
</Info>

## Managing Tokens

### List and Inspect

[List Digital Wallet Tokens](/v2/reference/listdigitalwallettokens) returns the tokens provisioned for a card. [Get Digital Wallet Token](/v2/reference/getdigitalwallettoken) returns one.

Fields worth knowing:

| Field                      | Use                                                                                |
| -------------------------- | ---------------------------------------------------------------------------------- |
| `state`                    | Whether the token can transact                                                     |
| `type`                     | `APPLE_PAY`, `ANDROID_PAY`, or another requestor for merchant card-on-file tokens  |
| `device`                   | Device id, name, type, IP address, and location — useful when diagnosing a decline |
| `token_reference_id`       | The token's identifier within the card network, for network-side queries           |
| `removed_from_wallet_time` | When the cardholder removed the card from their wallet                             |
| `processor_data`           | Raw processor data, including the fulfillment status shown in the console          |

### Suspend, Reactivate, or Terminate

<CodeGroup>
  ```shell Shell theme={"system"}
  curl -X PATCH "$baseurl/v2/cards/digital_wallet_tokens/{DIGITAL_WALLET_TOKEN_ID}" \
    -H "Authorization: Bearer $apikey" \
    -H 'Content-Type: application/json' \
    --data-binary '{
      "status": "SUSPENDED"
    }'
  ```
</CodeGroup>

`status` accepts `ACTIVE`, `SUSPENDED`, and `TERMINATED`. Suspension is reversible; termination is not.

Suspend a token when a device is lost but the card is fine — it blocks wallet spend without disturbing the physical card. Terminate when the device is gone for good.

See [Update Digital Wallet Token Status](/v2/reference/updatedigitalwallettokenstatus).

### Webhooks

| Event                             | Fires when                                                                                                                                 |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `CARD.DIGITALWALLETTOKEN.CREATED` | Provisioning is requested, by any method                                                                                                   |
| `CARD.DIGITALWALLETTOKEN.UPDATED` | A token's status changes — through your own PATCH, when a pending request is approved or refused, or when a card is reissued or terminated |

Subscribe to both. `CREATED` tells you an attempt happened; `UPDATED` tells you how it ended. See the [Webhooks guide](/v2/docs/webhooks-guide).

## Next Steps

<CardGroup cols={2}>
  <Card title="Provisioning Decisions" href="/v2/docs/digital-wallets-provisioning-decisions" icon="shield">
    Why a token was never created in the first place.
  </Card>

  <Card title="Tokenization Overview" href="/v2/docs/digital-wallets" icon="wallet">
    How tokenization works and what your program needs.
  </Card>
</CardGroup>