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

# Create digital wallet token transition

> Use the /digitalwallettokentransitions endpoint to transition a digital wallet token from one state to another.

POST/digitalwallettokentransitions

> [!NOTE]
>
> Use this endpoint if you use Marqeta only for tokenization as a service and are not a Marqeta card issuer.
> If Marqeta is your card issuer, use the [Digital Wallets Management endpoint](https://www.marqeta.com/docs/core-api/digital-wallets-management/digital-wallet-token-transitions-wallets/create-token-transition.md) instead.

Use the `/digitalwallettokentransitions` endpoint to transition a digital wallet token from one state to another.

## Header parameter

| Fields | Description |
| - | - |
| req-sys-id string  Optional | Random pseudo-unique identifier of a request, used for troubleshooting between multiple parties. Usually a globally unique identifier (GUID). **Allowable Values:**  1–36 chars |

## Request body

| Fields | Description |
| - | - |
| token string  Optional | Unique identifier of the digital wallet token transition, and not the identifier of the digital wallet token itself. If you do not include a value for the token field, the system will generate one automatically. This value is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated. **Allowable Values:**  1–36 chars |
| reason\_code string  Required | Code describing the reason for the transition. Marqeta does not validate what is provided, although Marqeta-sourced changes use standard codes. **Allowable Values:**  1–255 chars |
| token\_reference\_id string  Optional | Unique identifier of the digital wallet token within the card network. `token_reference_id` is unique at the card network level. This is the primary identifier for Visa. **Allowable Values:**  1–255 chars |
| channel string  Required | Mechanism by which the transition was initiated. `API`, for example. **Allowable Values:**  `ADMIN`, `API`, `DIGITAL_WALLET`, `FRAUD`, `IVR`, `MARQETA_DASHBOARD`, `SYSTEM`, `TOKEN_SERVICE_PROVIDER` |
| state string  Required | Specifies the state to which the digital wallet token transitions. **Allowable Values:**  `ACTIVE`, `REQUESTED`, `REQUEST_DECLINED`, `SUSPENDED`, `TERMINATED` |
| digital\_wallet\_token object  Required | Hashed version of Marqeta's unique identifier for the digital wallet tokens. **Allowable Values:**  `token` |
| digital\_wallet\_token.**token** string  Required | Marqeta's unique identifier for the digital wallet token. **Allowable Values:**  1–36 chars |
| reason string  Optional | Descriptive reason for the transition. **Allowable Values:**  255 char max |

## Sample request body

Activate token request

```json JSON expandable lines wrap theme={null}
{
  "state": "ACTIVE",
  "reason_code": "01",
  "reason": "Customer Request",
  "digital_wallet_token": {
    "token": "my_digital_wallet_token_01"
  },
  "channel": "API"
}
```

## Response body

| Fields | Description |
| - | - |
| token string  Returned | Unique identifier for the digital wallet token transition. **Allowable Values:**  1–36 chars |
| digital\_wallet\_token object  Returned | Hashed version of Marqeta's unique identifier for the digital wallet tokens. **Allowable Values:**  `token` |
| digital\_wallet\_token.**token** string  Returned | Marqeta's unique identifier for the digital wallet token. **Allowable Values:**  1–36 chars |
| type string  Returned | Type of digital wallet token transition. `state.activated`, for example. **Allowable Values:**  `card.swap`, `state.activated`, `state.reinstated`, `state.suspended`, `state.terminated` |
| channel string  Returned | Mechanism by which the transition was initiated. **Allowable Values:**  `API` |
| state string  Returned | Specifies the state to which the digital wallet token transitions. **Allowable Values:**  `ACTIVE`, `SUSPENDED`, `TERMINATED` |
| fulfillment\_status string  Returned | Digital wallet token's provisioning status. **Allowable Values:**  `DECISION_GREEN`, `DECISION_RED`, `DECISION_YELLOW`, `PROVISIONED`, `REJECTED` |
| reason string  Conditionally returned | Descriptive reason for the transition. **Allowable Values:**  255 char max |
| reason\_code string  Returned | Code describing the reason for the transition. Marqeta does not validate what is provided, although Marqeta-sourced changes use standard codes. **Allowable Values:**  1–255 chars |
| created\_time datetime  Returned | Date and time when the resource was created, in UTC. **Allowable Values:**  date-time **Format:** yyyy-MM-ddThh:mm:ssZ |

## Sample response body

```json JSON expandable lines wrap theme={null}
{
  "token": "my_dwt_transition_01",
  "digital_wallet_token": {
    "token": "my_digital_wallet_token_01"
  },
  "type": "state.activated",
  "channel": "API",
  "state": "ACTIVE",
  "fulfillment_status": "PROVISIONED",
  "reason": "Customer Request",
  "reason_code": "01",
  "created_time": "2025-09-10T06:30:20Z"
}
```


## Related topics

- [Create digital wallet token transition](https://www.marqeta.com/docs/core-api/digital-wallets-management/digital-wallet-token-transitions-wallets/create-token-transition.md)
- [Digital Wallet Token Transitions Overview](https://www.marqeta.com/docs/core-api/digital-wallets-management/digital-wallet-token-transitions-wallets.md)
- [Digital Wallets Management Overview](https://www.marqeta.com/docs/core-api/digital-wallets-management.md)
- [Tokenization-as-a-Service Overview](https://www.marqeta.com/docs/core-api/tokenization-as-a-service.md)
- [Retrieve digital wallet token](https://www.marqeta.com/docs/core-api/digital-wallets-management/digital-wallet-tokens-wallets/retrieve-token.md)