POST/
Creates a card state transition to set the state of an existing card.
If your system uses IVR, you can send a POST request to /cards/getbypan to retrieve a card token, which you can then use in your POST request to /cardtransitions.
It may not be possible to move a card from one user to another once the card has been activated.
Request body
| Fields | Description |
|---|---|
| card_token string Required | Identifies the card whose state will transition. Allowable Values: 1–36 chars Existing card token.Send a GET request to /cards/user/{token} to retrieve card tokens for a specific user. |
| channel string Required | The mechanism by which the transition was initiated. - ADMIN - Indicates that the card transition was initiated through the Marqeta Dashboard. - API - Indicates that the card transition was initiated by you through the Core API. Use this value when creating a card transition with an API POST request.- FRAUD - Indicates that either Marqeta or the card network has determined that the card is fraudulent. - IVR - Indicates that the card transition was initiated through your Interactive Voice Response system. - SYSTEM - Indicates that the card transition was initiated by Marqeta. For example, Marqeta suspended the card due to excessive failed personal identification number (PIN) entries. Allowable Values: API, IVR, FRAUD, ADMIN, SYSTEM |
| reason string Optional | Additional information about the state change. 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 new state. Allowable Values: ACTIVE, SUSPENDED, TERMINATED |
| token string Optional | Unique identifier of the card transition. If you do not include a token, the system will generate one automatically. This token is referenced in other API calls, so we recommend that you define a simple string that is easy to remember. This value cannot be updated. Allowable Values: 1–36 chars |
| sync_state_with_dwts boolean Optional | Set this field to true to synchronize the state of the card’s associated token(s) with the card’s new state. The digital wallet tokens must be in a valid starting state for the given transition, which will reflect the card’s state transition. For example, if the card is transitioning from the ACTIVE state to the SUSPENDED state, only digital wallet tokens in the ACTIVE state will be synchronized with the card state transition and therefore be transitioned to the SUSPENDED state.Leave this field blank or set it to false to keep the states of the card and its digital wallet tokens independent.Allowable Values: true, false |
| validations object Optional | Contains information about the user. Allowable Values: user |
| validations.user object Optional | Contains information about the user. Allowable Values: birth_date, phone, random_name_line1_postfix, ssn |
| validations.user.birth_date datetime Optional | Date of birth of the user associated with this card. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| validations.user.phone string Optional | Telephone number of the user associated with this card. Allowable Values: 255 char max Format: 5105551212 or 510-555-1212 |
| validations.user.random_name_line1_postfix string Optional | Random six-digit numeric postfix generated for some bulk card orders. See Bulk Card Orders for more information about numeric postfixes. Allowable Values: 6 chars |
| validations.user.ssn string Optional | Social Security Number (SSN) of the user associated with this card. Allowable Values: 255 char max |
Sample request body
JSON
{
"token": "activate_05",
"state": "ACTIVE",
"reason": "I want to use this card, so activate it.",
"reason_code": "00",
"channel": "API",
"card_token": "my_user_01_card_01",
"validations": {
"user": {
"birth_date": "1990-01-31T00:00:00Z"
}
}
}
Response body
| Fields | Description |
|---|---|
| barcode string Returned | The barcode printed on the card, expressed as digits. Allowable Values: 10-20 chars |
| bulk_issuance_token string Conditionally returned | The unique identifier of the bulk card order. Allowable Values: 1-36 chars |
| card object Conditionally returned | Associates customer-injected metadata with the card. Allowable Values: metadata |
| card.metadata object Conditionally returned | Associates customer-injected metadata with the card. Allowable Values: You can define the names and values of up to 20 fields in the format "my_name_1": "my_value_1". |
| card_product_token string Returned | Unique identifier of the card product. Allowable Values: 36 char max |
| card_token string Returned | Unique identifier of the card. Allowable Values: 1–36 chars |
| channel string Returned | The mechanism by which the transition was initiated. - ADMIN - Indicates that the card transition was initiated through the Marqeta Dashboard. - API - Indicates that the card transition was initiated by you through the Core API. Use this value when creating a card transition with an API POST request.- FRAUD - Indicates that either Marqeta or the card network has determined that the card is fraudulent. - IVR - Indicates that the card transition was initiated through your Interactive Voice Response system. - SYSTEM - Indicates that the card transition was initiated by Marqeta. For example, Marqeta suspended the card due to excessive failed personal identification number (PIN) entries. Allowable Values: API, IVR, FRAUD, ADMIN, SYSTEM |
| created_time datetime Conditionally returned | Date and time when the resource was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| created_timestamp datetime Conditionally returned | Date and time when the resource was created. Expressed in UTC, with millisecond precision. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ss:SSSZ |
| expedite boolean Conditionally returned | A value of true indicates that you requested expedited processing of the card from your card fulfillment provider.Allowable Values: true, false |
| expiration string Returned | Expiration date in MMyy format.Allowable Values: Format: MMyy |
| expiration_time string Returned | Expiration date and time in UTC format. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| fulfillment object Conditionally returned | Specifies certain physical characteristics of a card, as well as shipment information. Allowable Values: card_fulfillment_reason, card_personalization, shipping |
| fulfillment.card_fulfillment_reason string Conditionally returned | Reason for card fulfillment. Allowable Values: NEW, LOST_STOLEN, EXPIRED |
| fulfillment.card_personalization object Returned | Specifies personalized attributes to be added to the card. Allowable Values: carrier, images, perso_type, text |
| fulfillment.card_personalization.carrier object Conditionally returned | Specifies attributes of the card carrier. Allowable Values: logo_file, logo_thumbnail_file, message_file, message_line, template_id |
| fulfillment.card_personalization.carrier.logo_file string Conditionally returned | Specifies an image to display on the card carrier. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
| fulfillment.card_personalization.carrier.logo_thumbnail_file string Conditionally returned | Specifies a thumbnail-sized rendering of the image specified in the logo_file field.Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
| fulfillment.card_personalization.carrier.message_file string Conditionally returned | Specifies a text file containing a custom message to print on the card carrier. Allowable Values: Contains the name of the text file and must match the name of the file you send to your fulfillment provider. |
| fulfillment.card_personalization.carrier.message_line string Conditionally returned | Specifies a custom message that appears on the card carrier. Allowable Values: 60 char max |
| fulfillment.card_personalization.carrier.message_line_2 string Conditionally returned | Specifies the second line of a custom message that appears on the card carrier. Allowable Values: 60 char max |
| fulfillment.card_personalization.carrier.template_id string Conditionally returned | Specifies the card carrier template to use. Allowable Values: Card carrier template ID |
| fulfillment.card_personalization.images object Conditionally returned | Specifies personalized images that appear on the card. Allowable Values: card, carrier, carrier_return_window, signature |
| fulfillment.card_personalization.images.card object Conditionally returned | Specifies personalized images that appear on the card. Allowable Values: name, thermal_color |
| fulfillment.card_personalization.images.card.name string Conditionally returned | Specifies a PNG image to display on the card. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
| fulfillment.card_personalization.images.card.thermal_color string Conditionally returned | Specifies the color of the image displayed on the card. Allowable Values: Contains the name of the color and must match one of the provider’s predefined colors. |
| fulfillment.card_personalization.images.carrier object Conditionally returned | Specifies personalized images that appear on the card carrier. Allowable Values: message_1, name |
| fulfillment.card_personalization.images.carrier.message_1 string Conditionally returned | Specifies a custom message that appears on the card carrier. Allowable Values: 60 char max |
| fulfillment.card_personalization.images.carrier.name string Conditionally returned | Specifies a PNG image to display on the card carrier. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
| fulfillment.card_personalization.images.carrier_return_window object Conditionally returned | Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders. Allowable Values: name |
| fulfillment.card_personalization.images.carrier_return_window.name string Conditionally returned | Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
| fulfillment.card_personalization.images.signature object Conditionally returned | Specifies a PNG image of the cardholder’s signature. Allowable Values: name |
| fulfillment.card_personalization.images.signature.name string Conditionally returned | Specifies a PNG image of the cardholder’s signature. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
| fulfillment.card_personalization.perso_type string Conditionally returned | Specifies the type of card personalization. Allowable Values: EMBOSS, LASER, FLAT |
| fulfillment.card_personalization.text object Returned | Specifies personalized text that appears on the card. Allowable Values: name_line_1, name_line_2, name_line_3 |
| fulfillment.card_personalization.text.name_line_1 object Returned | Specifies the first line of personalized text that appears on the card. Allowable Values: name_line_1.value21 char max; if name_line_1_numeric_postfix is true, 14 char max.Strings longer than the character limit are truncated. |
| fulfillment.card_personalization.text.name_line_1.value string Conditionally returned | Line of personalized text printed on the card. Allowable Values: 21 char max |
| fulfillment.card_personalization.text.name_line_2 object Conditionally returned | Specifies the second line of personalized text that appears on the card. Allowable Values: name_line_2.value |
| fulfillment.card_personalization.text.name_line_2.value string Conditionally returned | Line of personalized text printed on the card. Allowable Values: 21 char max |
| fulfillment.card_personalization.text.name_line_3 object Conditionally returned | Specifies the third line of personalized text that appears on the card. Allowable Values: name_line_3.value |
| fulfillment.card_personalization.text.name_line_3.value string Conditionally returned | Line of personalized text printed on the card. Allowable Values: 21 char max |
| fulfillment.shipping object Conditionally returned | Specifies shipping details for the order. Allowable Values: care_of_line, method, recipient_address, return_address |
| fulfillment.shipping.care_of_line string Conditionally returned | Adds the specified value as a care of (C/O) line to the mailing carrier. NOTE: This field can be specified on cards, card products, and bulk card orders. If you specify this field at multiple levels, the order of precedence is: card, bulk card order, card product. Allowable Values: 255 char max |
| fulfillment.shipping.method string Conditionally returned | Specifies the shipping service. Allowable Values: LOCAL_MAIL, LOCAL_MAIL_PACKAGE, GROUND, TWO_DAY, OVERNIGHT, INTERNATIONAL, INTERNATIONAL_PRIORITY, LOCAL_PRIORITY, FEDEX_EXPEDITED, FEDEX_REGULAR, UPS_EXPEDITED, UPS_REGULAR, USPS_EXPEDITED, USPS_REGULARShipping options vary by card provider. For details on the specific shipping companies and services offered by your card provider, contact your Marqeta representative. |
| fulfillment.shipping.recipient_address object Conditionally returned | Address to which the order will be shipped. In order to generate cards, a valid shipping address must be provided by one of these: - The card or bulk card order’s fulfillment.shipping.recipient_address field- The users’ address fields- The card product’s config.fulfillment.shipping.recipient_address fieldThe order of precedence from highest to lowest is card, user, card product. To be valid, an address must have the address1, city, state, and postal_code or zip fields populated. The country field defaults to USA if unpopulated.Allowable Values: Valid recipient_address object |
| fulfillment.shipping.recipient_address.address1 string Conditionally returned | Number and street of the address. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters. |
| fulfillment.shipping.recipient_address.address2 string Conditionally returned | Additional address information. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters. |
| fulfillment.shipping.recipient_address.city string Conditionally returned | City of the address. Allowable Values: 40 char max |
| fulfillment.shipping.recipient_address.country string Conditionally returned | Country of the address. Allowable Values: 40 char max English short name. For example, for the Kingdom of Spain, use the English short name “Spain”. The ISO maintains the full list of country codes. |
| fulfillment.shipping.recipient_address.first_name string Conditionally returned | First name of the addressee. Allowable Values: 40 char max |
| fulfillment.shipping.recipient_address.last_name string Conditionally returned | Last name of the addressee. Allowable Values: 40 char max |
| fulfillment.shipping.recipient_address.middle_name string Conditionally returned | Middle name of the addressee. Allowable Values: 40 char max |
| fulfillment.shipping.recipient_address.phone string Conditionally returned | Telephone number of the addressee. Allowable Values: 20 char max |
| fulfillment.shipping.recipient_address.postal_code string Conditionally returned | Postal code of the address. Allowable Values: 10 char max |
| fulfillment.shipping.recipient_address.state string Conditionally returned | State of the address. Allowable Values: 32 char max |
| fulfillment.shipping.recipient_address.zip string Conditionally returned | United States ZIP code of the address. Allowable Values: 10 char max |
| fulfillment.shipping.return_address object Conditionally returned | Address to which the order will be returned if shipping fails. Allowable Values: address1, address2, city, country, first_name, last_name, middle_name, phone, postal_code, state, zip |
| fulfillment.shipping.return_address.address1 string Conditionally returned | Number and street of the address. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters. |
| fulfillment.shipping.return_address.address2 string Conditionally returned | Additional address information. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters. |
| fulfillment.shipping.return_address.city string Conditionally returned | City of the address. Allowable Values: 40 char max |
| fulfillment.shipping.return_address.country string Conditionally returned | Country of the address. Allowable Values: 40 char max English short name. For example, for the Kingdom of Spain, use the English short name “Spain”. The ISO maintains the full list of country codes. |
| fulfillment.shipping.return_address.first_name string Conditionally returned | First name of the addressee. Allowable Values: 40 char max |
| fulfillment.shipping.return_address.last_name string Conditionally returned | Last name of the addressee. Allowable Values: 40 char max |
| fulfillment.shipping.return_address.middle_name string Conditionally returned | Middle name of the addressee. Allowable Values: 40 char max |
| fulfillment.shipping.return_address.phone string Conditionally returned | Telephone number of the addressee. Allowable Values: 20 char max |
| fulfillment.shipping.return_address.postal_code string Conditionally returned | Postal code of the address. Allowable Values: 10 char max |
| fulfillment.shipping.return_address.state string Conditionally returned | State of the address. Allowable Values: 32 char max |
| fulfillment.shipping.return_address.zip string Conditionally returned | United States ZIP code of the address. Allowable Values: 10 char max |
| fulfillment_status string Returned | Provides status information about the card related to order and delivery. The possible fulfillment states are: - ISSUED: Initial state of all newly created/issued cards - ORDERED: Card ordered through card fulfillment provider - REJECTED: Card rejected by card fulfillment provider - SHIPPED: Card shipped by card fulfillment provider - DELIVERED: Card delivered by the card fulfillment provider. - DIGITALLY_PRESENTED: Card digitally presented using the /cards/{token}/showpan endpoint; does not affect the delivery of physical cardsAllowable Values: ISSUED, ORDERED, REJECTED, SHIPPED, DELIVERED, DIGITALLY_PRESENTED |
| last_four string Returned | Last four digits of the card primary account number (PAN). Allowable Values: 4 chars |
| pan string Returned | Primary account number (PAN) of the card. Allowable Values: 16 char max |
| pin_is_set boolean Returned | Specifies if the personal identification number (PIN) has been set for the card. Allowable Values: 4 chars |
| reason string Conditionally returned | Additional information about the state change. Allowable Values: 255 char max |
| reason_code string Conditionally returned | A 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 |
| reissue_pan_from_card_token string Conditionally returned | Reissues the specified (“source”) card. Allowable Values: Existing card token |
| new_pan_from_card_token string Conditionally returned | Reissues the specified (“source”) card with a new primary account number (PAN). Allowable Values: Existing card token |
| state string Returned | Indicates the state of the card. Allowable Values: ACTIVE, SUSPENDED, TERMINATED, UNACTIVATED |
| token string Returned | Unique identifier of the card transition. Allowable Values: 1–36 chars |
| type string Returned | This field cannot be set directly using the /cardtransitions endpoint. A card transition’s type is managed by the Marqeta platform, based on the before and after state of the transition, as specified in the request’s state field.This field appears only when populated by the card fulfillment provider. The type field’s possible values are:- fulfillment.delivered: Card was delivered by the card fulfillment provider - fulfillment.digitally_presented: Card was digitally presented using the /cards/{token}/showpan endpoint; does not affect the delivery of physical cards- fulfillment.issued: Card was created/issued - fulfillment.ordered: Card was ordered from the card fulfillment provider - fulfillment.rejected: Card was rejected by the card fulfillment provider - fulfillment.shipped: Card was shipped by the card fulfillment provider - state.activated: Card was activated - state.limited: Card was limited - state.reinstated: Card was reinstated from a suspended state - state.suspended: Card was suspended - state.terminated: Card was terminated Allowable Values: fulfillment.delivered, fulfillment.digitally_presented, fulfillment.issued, fulfillment.ordered, fulfillment.rejected, fulfillment.shipped, state.activated, state.limited, state.reinstated, state.suspended, state.terminated |
| user object Conditionally returned | Associates customer-injected metadata with the cardholder. Allowable Values: metadata |
| user.metadata object Conditionally returned | Associates customer-injected metadata with the cardholder. Allowable Values: You can define the names and values of up to 20 fields in the format "my_name_1": "my_value_1". |
| user_token string Returned | Unique identifier of the cardholder. Allowable Values: 1–36 chars |
| validations object Conditionally returned | Contains information about the user. Allowable Values: Existing validations object |
| validations.user object Returned | Contains information about the user. Allowable Values: birth_date, phone, random_name_line1_postfix, ssn |
| validations.user.birth_date boolean Returned | Indicates whether the birth_date field in the request was validated.Allowable Values: true, false |
| validations.user.phone boolean Returned | Indicates whether the phone field in the request was validated.Allowable Values: true, false |
| validations.user.random_name_line1_postfix boolean Returned | Indicates whether the random_name_line1_postfix field in the request was validated.Allowable Values: true, false |
| validations.user.ssn boolean Returned | Indicates whether the ssn field in the request was validated.Allowable Values: true, false |
Sample response body
JSON
{
"token": "activate_05",
"card_token": "my_user_01_card_01",
"user_token": "my_user_01",
"state": "ACTIVE",
"reason": "I want to use this card, so activate it.",
"reason_code": "00",
"channel": "API",
"expedite": false,
"fulfillment_status": "ISSUED",
"validations": {
"user": {
"birth_date": true,
"phone": false,
"random_name_line1_postfix": false,
"ssn": false
}
},
"type": "state.activated",
"created_time": "2022-11-23T23:28:39Z",
"card_product_token": "my_cardproduct_01",
"last_four": "2160",
"pan": "1111115454542160",
"expiration": "1026",
"expiration_time": "2026-10-31T23:59:59Z",
"barcode": "11379418395311581864",
"pin_is_set": false,
"user": {
"metadata": {
"my_name_1": "my_value_1",
"my_name_2": "my_value_2"
}
}
}