Token Lifecycle Management

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.

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.

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

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.

Managing Tokens

List and Inspect

List Digital Wallet Tokens returns the tokens provisioned for a card. Get Digital Wallet Token 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

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"
  }'

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.

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.

Overview

Onboard a Personal Customer

Onboard a Business Customer

Create Accounts

Link External Accounts

Link External Cards

Issue Cards

Move Money

Get Transactions

Dispute Transactions

Platform Tools

Use Cases

Token Lifecycle Management

Token States

Managing Tokens

List and Inspect

Suspend, Reactivate, or Terminate

Webhooks

Next Steps

Provisioning Decisions

Tokenization Overview

​Token States

​Managing Tokens

​List and Inspect

​Suspend, Reactivate, or Terminate

​Webhooks

​Next Steps

Provisioning Decisions

Tokenization Overview

Token States

Managing Tokens

List and Inspect

Suspend, Reactivate, or Terminate

Webhooks

Next Steps