POST/
Use this endpoint if Marqeta is your card issuer.
If you use Marqeta only for tokenization as a service, use the Tokenization-as-a-Service endpoint instead.
Request body
| Fields | Description |
|---|---|
| channel string Optional | Mechanism by which the transition was initiated. Allowable Values: TOKEN_SERVICE_PROVIDER, TOKEN_SERVICE_PROVIDER_API, DIGITAL_WALLET, API, IVR, FRAUD, ADMIN, SYSTEM |
| digital_wallet_token object Required | Contains identifiers of the digital wallet token resource and the card resource. Allowable Values: Unique identifiers of the digital wallet token resource and the card resource |
| digital_wallet_token.token string Required | Unique identifier of the digital wallet token resource. Allowable Values: 1–36 chars |
| digital_wallet_token.card_token string Optional | Unique identifier of the card resource to use for the provisioning request. Allowable Values: 1–36 chars |
| reason string Optional | The reason for the transition. Allowable Values: 255 char max |
| reason_code string Optional | Standard code describing the reason for the transition. NOTE: This field is required if your program uses v2 of the user_card_state_version, which is a program-specific configuration value that is managed by Marqeta and cannot be accessed via the API. To learn more about the user_card_state_version program configuration, contact your Marqeta representative.- 00: Object activated for the first time - 01: Requested by you - 02: Inactivity over time - 03: This address cannot accept mail or the addressee is unknown - 04: Negative account balance - 05: Account under review - 06: Suspicious activity was identified - 07: Activity outside the program parameters was identified - 08: Confirmed fraud was identified - 09: Matched with an Office of Foreign Assets Control list - 10: Card was reported lost - 11: Card information was cloned - 12: Account or card information was compromised - 13: Temporary status change while on hold/leave - 14: Initiated by Marqeta - 15: Initiated by issuer - 16: Card expired - 17: Failed KYC - 18: Changed to ACTIVE because information was properly validated- 19: Changed to ACTIVE because account activity was properly validated- 20: Change occurred prior to the normalization of reason codes - 21: Initiated by a third party, often a digital wallet provider - 22: PIN retry limit reached - 23: Card was reported stolen - 24: Address issue - 25: Name issue - 26: SSN issue - 27: DOB issue - 28: Email issue - 29: Phone issue - 30: Account/fulfillment mismatch - 31: Other reason - 32: Unblock request - 86: Notification of death Allowable Values: 00, 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 86 |
| state string Required | Specifies the state to which the digital wallet token will transition. The original state is REQUESTED. You cannot modify the state if its current value is either REQUEST_DECLINED or TERMINATED.Allowable Values: ACTIVE, SUSPENDED, TERMINATED |
| token string Optional | The unique identifier of the digital wallet token transition (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 |
| token_reference_id string Optional | The unique identifier of the digital wallet token within the card network. The token_reference_id is unique at the card network level.Allowable Values: 255 char max |
Sample request body
JSON
{
"token": "my_transition_04",
"digital_wallet_token": {
"token": "my_digital_wallet_token_0987"
},
"state": "ACTIVE",
"reason": "Passed additional identity verification",
"reason_code": "18"
}
Response body
| Fields | Description |
|---|---|
| card_swap object Conditionally returned | Contains identifiers for swapping digital wallet tokens between cards. Allowable Values: new_card_token, previous_card_token |
| card_swap.new_card_token string Returned | Unique identifier of the new card resource to which the digital wallet tokens are assigned. Allowable Values: 1–36 chars |
| card_swap.previous_card_token string Returned | Unique identifier of the existing card resource that has digital wallet tokens assigned to it. Allowable Values: 1–36 chars |
| channel string Returned | Mechanism by which the transition was initiated. Allowable Values: TOKEN_SERVICE_PROVIDER, DIGITAL_WALLET, API, IVR, FRAUD, ADMIN, SYSTEM, TOKEN_SERVICE_PROVIDER_API |
| created_time datetime Conditionally returned | Date and time when the transition was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| digital_wallet_token object Returned | Contains identifiers of the digital wallet token resource and the card resource. Allowable Values: Unique identifiers of the digital wallet token resource and the card resource |
| digital_wallet_token.token string Returned | Unique identifier of the digital wallet token resource. Allowable Values: 1–36 chars |
| digital_wallet_token.card_token string Conditionally returned | Unique identifier of the card resource to use for the provisioning request. Allowable Values: 1–36 chars |
| fulfillment_status string Returned | Provisioning status of the digital wallet token. Allowable Values: DECISION_RED, DECISION_YELLOW, DECISION_GREEN, REJECTED, PROVISIONED |
| reason string Conditionally returned | Reason for the transition. Allowable Values: 255 char max |
| reason_code string Conditionally returned | Standard code describing the reason for the transition: - 00: Object activated for the first time - 01: Requested by you - 02: Inactivity over time - 03: This address cannot accept mail or the addressee is unknown - 04: Negative account balance - 05: Account under review - 06: Suspicious activity was identified - 07: Activity outside the program parameters was identified - 08: Confirmed fraud was identified - 09: Matched with an Office of Foreign Assets Control list - 10: Card was reported lost - 11: Card information was cloned - 12: Account or card information was compromised - 13: Temporary status change while on hold/leave - 14: Initiated by Marqeta - 15: Initiated by issuer - 16: Card expired - 17: Failed KYC - 18: Changed to ACTIVE because information was properly validated- 19: Changed to ACTIVE because account activity was properly validated- 20: Change occurred prior to the normalization of reason codes - 21: Initiated by a third party, often a digital wallet provider - 22: PIN retry limit reached - 23: Card was reported stolen - 24: Address issue - 25: Name issue - 26: SSN issue - 27: DOB issue - 28: Email issue - 29: Phone issue - 30: Account/fulfillment mismatch - 31: Other reason - 32: Unblock request - 86: Notification of death Allowable Values: 00, 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 86 |
| state string Returned | Specifies the state to which the digital wallet token is transitioning. Allowable Values: REQUESTED, REQUEST_DECLINED, ACTIVE, SUSPENDED, TERMINATED |
| 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 |
| type string Returned | Type of digital wallet token transition. state.activated, for example.Allowable Values: 36 char max |
Sample response body
JSON
{
"token": "my_transition_04",
"digital_wallet_token": {
"token": "my_digital_wallet_token_0987"
},
"type": "state.activated",
"channel": "API",
"state": "ACTIVE",
"fulfillment_status": "PROVISIONED",
"reason": "Passed additional identity verification",
"reason_code": "18",
"created_time": "2026-02-23T18:57:45Z"
}
Error responses
| HTTP Status | Description |
|---|---|
| 400 | Bad request. |
| 409 | Token already associated with a different payload. |
| 422 | Unprocessable entity. Use error_code to determine the cause:- 422003 — The token service provider (TSP) returned an unresolvable error. The token state was not changed. Retry later; if the error persists, contact Marqeta support.- 422004 — Marqeta detected a state mismatch between Marqeta and the TSP. The error_message field reports both states (for example, Marqeta state: <marqeta_state>. TSP state: <tsp_state>.). Reconcile the digital wallet token’s state with the TSP before retrying.Marqeta state allowable values: REQUESTED, ACTIVE, SUSPENDED, TERMINATEDTSP state allowable values: NOT_FOUND, INVALID_DATA, REQUIRED_DATA_MISSING, INACTIVE, ACTIVE, SUSPENDED, TERMINATED |
Sample error response bodies
422003:JSON
{
"error_message": "Unsuccessful response from token services gateway",
"error_code": "422003"
}
JSON
{
"error_code": "422004",
"error_message": "Incorrect operation attempted. Marqeta state: ACTIVE. TSP state: TERMINATED."
}