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

# Retrieve digital wallet token transition

> Use the /digitalwallettokentransitions/{token} endpoint to retrieve a specific digital wallet transition.

GET/digitalwallettokentransitions/\{token}

> [!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/retrieve-token-transition.md) instead.

Use the `/digitalwallettokentransitions/{token}` endpoint to retrieve a specific digital wallet transition.

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

## URL path parameters

| Fields | Description |
| - | - |
| token string  Required | Unique identifier of the digital wallet token transition. **Allowable Values:**  Existing digital wallet token transition token |

## URL query parameters

| Fields | Description |
| - | - |
| fields string  Optional | Comma-delimited list of fields to return (`field_1,field_2`, and so on). Leave blank to return all fields. **Allowable Values:**  Comma-delimited list of fields, or blank |

## Response body

| Fields | Description |
| - | - |
| token string  Returned | Unique identifier of the digital wallet token transition, and not the identifier of the digital wallet token itself. **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 |
| card\_swap object  Conditionally returned | Hashed version of the `card_swap` object. Specifies the old and new payment card tokens that were swapped. **Allowable Values:**  `newCardToken`, `previousCardToken` |
| card\_swap.**previousCardToken** string  Returned | Unique identifier of the old card from which the digital wallet tokens are transferred. **Allowable Values:**  1–36 chars |
| card\_swap.**newCardToken** string  Returned | Unique identifier of the new card to which the digital wallet tokens are transferred. **Allowable Values:**  1–36 chars |
| type string  Returned | Type of digital wallet token transition. `state.activated`, for example. **Allowable Values:**  `card.swap`, `fulfillment.requested`, `state.activated`, `state.reinstated`, `state.request_declined`, `state.suspended`, `state.terminated` |
| channel string  Returned | 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  Returned | Specifies the state to which to transition the digital wallet token. **Allowable Values:**  `ACTIVE`, `REQUESTED`, `REQUEST_DECLINED`, `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

Token in requested state

```json JSON expandable lines wrap theme={null}
{
  "token": "bb50c999-9c4e-3f99-90a0-a12ab30fe81b",
  "digital_wallet_token": {
    "token": "c45c201-ad5e-3f23-76a0-a08cb36fa90a"
  },
  "type": "fulfillment.requested",
  "channel": "TOKEN_SERVICE_PROVIDER",
  "state": "REQUESTED",
  "fulfillment_status": "DECISION_GREEN",
  "reason": "Token creation",
  "reason_code": "21",
  "created_time": "2025-09-06T22:52:13Z"
}
```

Card swap transition

```json JSON expandable lines wrap theme={null}
{
  "token": "cb40c400-ba4f-3f97-80b0-c09ab30fe63d",
  "digital_wallet_token": {
    "token": "cb45c201-ad5e-3f23-76a0-a08cb36fa90a"
  },
  "card_swap": {
    "previousCardToken": "card-token-1",
    "newCardToken": "card-token-2"
  },
  "type": "card.swap",
  "channel": "SYSTEM",
  "state": "ACTIVE",
  "fulfillment_status": "PROVISIONED",
  "reason": "New card",
  "reason_code": "14",
  "created_time": "2025-09-10T06:29:30Z"
}
```


## Related topics

- [Retrieve digital wallet token transition](https://www.marqeta.com/docs/core-api/digital-wallets-management/digital-wallet-token-transitions-wallets/retrieve-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)
- [List digital wallet token transitions](https://www.marqeta.com/docs/core-api/tokenization-as-a-service/digital-wallet-token-transitions-taas/list-digital-wallet-token-transitions.md)