POST/
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 instead.
/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 requestJSON
{
"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
{
"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"
}