Card Transitions
Use the /cardtransitions API to set the state of an existing card.
Create card transition
Copy section link
Action: POST
Endpoint: /cardtransitions
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
Copy section link
| Fields | Description |
|---|---|
card_token
string
|
Identifies the card whose state will transition. Allowable Values: 1–36 chars Existing Send a |
channel
string
|
The mechanism by which the transition was initiated.
Allowable Values:
|
reason
string
|
Additional information about the state change. Allowable Values: 255 char max |
reason_code
string
|
Standard code describing the reason for the transition:
Allowable Values:
|
state
string
|
Specifies the new state. Allowable Values:
|
token
string
|
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
|
Set this field to Leave this field blank or set it to Allowable Values:
|
validations
object
|
Contains information about the user. Allowable Values:
|
validations.user
object
|
Contains information about the user. Allowable Values:
|
validations.user.birth_date
datetime
|
Date of birth of the user associated with this card. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
validations.user.phone
string
|
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
|
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
|
Social Security Number (SSN) of the user associated with this card. Allowable Values: 255 char max |
Response body
Copy section link
| Fields | Description |
|---|---|
barcode
string
|
The barcode printed on the card, expressed as digits. Allowable Values: 10-20 chars |
bulk_issuance_token
string
|
The unique identifier of the bulk card order. Allowable Values: 1-36 chars |
card
object
|
Associates customer-injected metadata with the card. Allowable Values:
|
card.metadata
object
|
Associates customer-injected metadata with the card. Allowable Values: You can define the names and values of up to 20 fields in the format |
card_product_token
string
|
Unique identifier of the card product. Allowable Values: 36 char max |
card_token
string
|
Unique identifier of the card. Allowable Values: 1–36 chars |
channel
string
|
The mechanism by which the transition was initiated.
Allowable Values:
|
created_time
datetime
|
Date and time when the resource was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
expedite
boolean
|
A value of Allowable Values:
|
expiration
string
|
Expiration date in Allowable Values: Format: MMyy |
expiration_time
string
|
Expiration date and time in UTC format. Allowable Values: Format: yyyy-MM-ddTHH:mm:ssZ |
fulfillment
object
|
Specifies certain physical characteristics of a card, as well as shipment information. Allowable Values:
|
fulfillment.card_fulfillment_reason
string
|
Reason for card fulfillment. Allowable Values:
|
fulfillment.card_personalization
object
|
Specifies personalized attributes to be added to the card. Allowable Values:
|
fulfillment.card_personalization.carrier
object
|
Specifies attributes of the card carrier. Allowable Values:
|
fulfillment.card_personalization.carrier.logo_file
string
|
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
|
Specifies a thumbnail-sized rendering of the image specified in the 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
|
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
|
Specifies a custom message that appears on the card carrier. Allowable Values: 60 char max |
fulfillment.card_personalization.carrier.template_id
string
|
Specifies the card carrier template to use. Allowable Values: Card carrier template ID |
fulfillment.card_personalization.images
object
|
Specifies personalized images that appear on the card. Allowable Values:
|
fulfillment.card_personalization.images.card
object
|
Specifies personalized images that appear on the card. Allowable Values:
|
fulfillment.card_personalization.images.card.name
string
|
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
|
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
|
Specifies personalized images that appear on the card carrier. Allowable Values:
|
fulfillment.card_personalization.images.carrier.message_1
string
|
Specifies a custom message that appears on the card carrier. Allowable Values: 60 char max |
fulfillment.card_personalization.images.carrier.name
string
|
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
|
Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders. Allowable Values:
|
fulfillment.card_personalization.images.carrier_return_window.name
string
|
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
|
Specifies a PNG image of the cardholder’s signature. Allowable Values:
|
fulfillment.card_personalization.images.signature.name
string
|
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
|
Specifies the type of card personalization. Allowable Values:
|
fulfillment.card_personalization.text
object
|
Specifies personalized text that appears on the card. Allowable Values:
|
fulfillment.card_personalization.text.name_line_1
object
|
Specifies the first line of personalized text that appears on the card. Allowable Values:
21 char max; if Strings longer than the character limit are truncated. |
fulfillment.card_personalization.text.name_line_1.value
string
|
Line of personalized text printed on the card. Allowable Values: 21 char max |
fulfillment.card_personalization.text.name_line_2
object
|
Specifies the second line of personalized text that appears on the card. Allowable Values:
|
fulfillment.card_personalization.text.name_line_2.value
string
|
Line of personalized text printed on the card. Allowable Values: 21 char max |
fulfillment.card_personalization.text.name_line_3
object
|
Specifies the third line of personalized text that appears on the card. Allowable Values:
|
fulfillment.card_personalization.text.name_line_3.value
string
|
Line of personalized text printed on the card. Allowable Values: 21 char max |
fulfillment.shipping
object
|
Specifies shipping details for the order. Allowable Values:
|
fulfillment.shipping.care_of_line
string
|
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
|
Specifies the shipping service. Allowable Values:
Shipping 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
|
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 order of precedence from highest to lowest is card, user, card product.
To be valid, an address must have the Allowable Values: Valid |
fulfillment.shipping.recipient_address.address1
string
|
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
|
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
|
City of the address. Allowable Values: 40 char max |
fulfillment.shipping.recipient_address.country
string
|
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
|
First name of the addressee. Allowable Values: 40 char max |
fulfillment.shipping.recipient_address.last_name
string
|
Last name of the addressee. Allowable Values: 40 char max |
fulfillment.shipping.recipient_address.middle_name
string
|
Middle name of the addressee. Allowable Values: 40 char max |
fulfillment.shipping.recipient_address.phone
string
|
Telephone number of the addressee. Allowable Values: 20 char max |
fulfillment.shipping.recipient_address.postal_code
string
|
Postal code of the address. Allowable Values: 10 char max |
fulfillment.shipping.recipient_address.state
string
|
State of the address. Allowable Values: 32 char max |
fulfillment.shipping.recipient_address.zip
string
|
United States ZIP code of the address. Allowable Values: 10 char max |
fulfillment.shipping.return_address
object
|
Address to which the order will be returned if shipping fails. Allowable Values:
|
fulfillment.shipping.return_address.address1
string
|
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
|
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
|
City of the address. Allowable Values: 40 char max |
fulfillment.shipping.return_address.country
string
|
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
|
First name of the addressee. Allowable Values: 40 char max |
fulfillment.shipping.return_address.last_name
string
|
Last name of the addressee. Allowable Values: 40 char max |
fulfillment.shipping.return_address.middle_name
string
|
Middle name of the addressee. Allowable Values: 40 char max |
fulfillment.shipping.return_address.phone
string
|
Telephone number of the addressee. Allowable Values: 20 char max |
fulfillment.shipping.return_address.postal_code
string
|
Postal code of the address. Allowable Values: 10 char max |
fulfillment.shipping.return_address.state
string
|
State of the address. Allowable Values: 32 char max |
fulfillment.shipping.return_address.zip
string
|
United States ZIP code of the address. Allowable Values: 10 char max |
fulfillment_status
string
|
Provides status information about the card related to order and delivery. The possible fulfillment states are:
Allowable Values:
|
last_four
string
|
Last four digits of the card primary account number (PAN). Allowable Values: 4 chars |
pan
string
|
Primary account number (PAN) of the card. Allowable Values: 16 char max |
pin_is_set
boolean
|
Specifies if the personal identification number (PIN) has been set for the card. Allowable Values: 4 chars |
reason
string
|
Additional information about the state change. Allowable Values: 255 char max |
reason_code
string
|
A standard code describing the reason for the transition:
Allowable Values:
|
reissue_pan_from_card_token
string
|
Reissues the specified ("source") card. Allowable Values: Existing card token |
new_pan_from_card_token
string
|
Reissues the specified ("source") card with a new primary account number (PAN). Allowable Values: Existing card token |
state
string
|
Indicates the state of the card. Allowable Values:
|
token
string
|
Unique identifier of the card transition. Allowable Values: 1–36 chars |
type
string
|
This field cannot be set directly using the This field appears only when populated by the card fulfillment provider.
The
Allowable Values:
|
user
object
|
Associates customer-injected metadata with the cardholder. Allowable Values:
|
user.metadata
object
|
Associates customer-injected metadata with the cardholder. Allowable Values: You can define the names and values of up to 20 fields in the format |
user_token
string
|
Unique identifier of the cardholder. Allowable Values: 1–36 chars |
validations
object
|
Contains information about the user. Allowable Values: Existing |
validations.user
object
|
Contains information about the user. Allowable Values:
|
validations.user.birth_date
boolean
|
Indicates whether the Allowable Values:
|
validations.user.phone
boolean
|
Indicates whether the Allowable Values:
|
validations.user.random_name_line1_postfix
boolean
|
Indicates whether the Allowable Values:
|
validations.user.ssn
boolean
|
Indicates whether the Allowable Values:
|
List transitions for card
Copy section link
Action: GET
Endpoint: /cardtransitions/card/{token}
Retrieves a list of the transitions for a specific card.
This endpoint supports field filtering and pagination.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
Unique identifier of the card. Allowable Values: Existing card token |
URL query parameters
Copy section link
| Fields | Description |
|---|---|
count
integer
|
Number of card transitions to retrieve. Allowable Values: 1-10 Default value: |
start_index
integer
|
Sort order index of the first resource in the returned array. Allowable Values: Any integer Default value: |
fields
string
|
Comma-delimited list of fields to return ( Allowable Values: Comma-delimited list of fields, or blank |
sort_by
string
|
Field on which to sort.
Use any field in the resource model, or one of the system fields Allowable Values:
Default value: |
Response body
Copy section link
| Fields | Description |
|---|---|
count
integer
|
Number of resources to retrieve. This field is returned if there are resources in your returned array. Allowable Values: 1-10 |
data
array of objects
|
Array of card transition objects. Objects are returned as appropriate to your query. Allowable Values: Valid array of one or more card transition objects |
data[].barcode
string
|
The barcode printed on the card, expressed as digits. Allowable Values: 10-20 chars |
data[].bulk_issuance_token
string
|
The unique identifier of the bulk card order. Allowable Values: 1-36 chars |
data[].card
object
|
Associates customer-injected metadata with the card. Allowable Values:
|
data[].card.metadata
object
|
Associates customer-injected metadata with the card. Allowable Values: You can define the names and values of up to 20 fields in the format |
data[].card_product_token
string
|
Unique identifier of the card product. Allowable Values: 36 char max |
data[].card_token
string
|
Unique identifier of the card. Allowable Values: 1–36 chars |
data[].channel
string
|
The mechanism by which the transition was initiated.
Allowable Values:
|
data[].created_time
datetime
|
Date and time when the resource was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
data[].expedite
boolean
|
A value of Allowable Values:
|
data[].expiration
string
|
Expiration date in Allowable Values: Format: MMyy |
data[].expiration_time
string
|
Expiration date and time in UTC format. Allowable Values: Format: yyyy-MM-ddTHH:mm:ssZ |
data[].fulfillment
object
|
Specifies certain physical characteristics of a card, as well as shipment information. Allowable Values:
|
data[].fulfillment.card_fulfillment_reason
string
|
Reason for card fulfillment. Allowable Values:
|
data[].fulfillment.card_personalization
object
|
Specifies personalized attributes to be added to the card. Allowable Values:
|
data[].fulfillment.card_personalization.carrier
object
|
Specifies attributes of the card carrier. Allowable Values:
|
data[].fulfillment.card_personalization.carrier.logo_file
string
|
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. |
data[].fulfillment.card_personalization.carrier.logo_thumbnail_file
string
|
Specifies a thumbnail-sized rendering of the image specified in the Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
data[].fulfillment.card_personalization.carrier.message_file
string
|
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. |
data[].fulfillment.card_personalization.carrier.message_line
string
|
Specifies a custom message that appears on the card carrier. Allowable Values: 60 char max |
data[].fulfillment.card_personalization.carrier.template_id
string
|
Specifies the card carrier template to use. Allowable Values: Card carrier template ID |
data[].fulfillment.card_personalization.images
object
|
Specifies personalized images that appear on the card. Allowable Values:
|
data[].fulfillment.card_personalization.images.card
object
|
Specifies personalized images that appear on the card. Allowable Values:
|
data[].fulfillment.card_personalization.images.card.name
string
|
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. |
data[].fulfillment.card_personalization.images.card.thermal_color
string
|
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. |
data[].fulfillment.card_personalization.images.carrier
object
|
Specifies personalized images that appear on the card carrier. Allowable Values:
|
data[].fulfillment.card_personalization.images.carrier.message_1
string
|
Specifies a custom message that appears on the card carrier. Allowable Values: 60 char max |
data[].fulfillment.card_personalization.images.carrier.name
string
|
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. |
data[].fulfillment.card_personalization.images.carrier_return_window
object
|
Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders. Allowable Values:
|
data[].fulfillment.card_personalization.images.carrier_return_window.name
string
|
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. |
data[].fulfillment.card_personalization.images.signature
object
|
Specifies a PNG image of the cardholder’s signature. Allowable Values:
|
data[].fulfillment.card_personalization.images.signature.name
string
|
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. |
data[].fulfillment.card_personalization.perso_type
string
|
Specifies the type of card personalization. Allowable Values:
|
data[].fulfillment.card_personalization.text
object
|
Specifies personalized text that appears on the card. Allowable Values:
|
data[].fulfillment.card_personalization.text.name_line_1
object
|
Specifies the first line of personalized text that appears on the card. Allowable Values:
21 char max; if Strings longer than the character limit are truncated. |
data[].fulfillment.card_personalization.text.name_line_1.value
string
|
Line of personalized text printed on the card. Allowable Values: 21 char max |
data[].fulfillment.card_personalization.text.name_line_2
object
|
Specifies the second line of personalized text that appears on the card. Allowable Values:
|
data[].fulfillment.card_personalization.text.name_line_2.value
string
|
Line of personalized text printed on the card. Allowable Values: 21 char max |
data[].fulfillment.card_personalization.text.name_line_3
object
|
Specifies the third line of personalized text that appears on the card. Allowable Values:
|
data[].fulfillment.card_personalization.text.name_line_3.value
string
|
Line of personalized text printed on the card. Allowable Values: 21 char max |
data[].fulfillment.shipping
object
|
Specifies shipping details for the order. Allowable Values:
|
data[].fulfillment.shipping.care_of_line
string
|
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 |
data[].fulfillment.shipping.method
string
|
Specifies the shipping service. Allowable Values:
Shipping options vary by card provider. For details on the specific shipping companies and services offered by your card provider, contact your Marqeta representative. |
data[].fulfillment.shipping.recipient_address
object
|
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 order of precedence from highest to lowest is card, user, card product.
To be valid, an address must have the Allowable Values: Valid |
data[].fulfillment.shipping.recipient_address.address1
string
|
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. |
data[].fulfillment.shipping.recipient_address.address2
string
|
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. |
data[].fulfillment.shipping.recipient_address.city
string
|
City of the address. Allowable Values: 40 char max |
data[].fulfillment.shipping.recipient_address.country
string
|
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. |
data[].fulfillment.shipping.recipient_address.first_name
string
|
First name of the addressee. Allowable Values: 40 char max |
data[].fulfillment.shipping.recipient_address.last_name
string
|
Last name of the addressee. Allowable Values: 40 char max |
data[].fulfillment.shipping.recipient_address.middle_name
string
|
Middle name of the addressee. Allowable Values: 40 char max |
data[].fulfillment.shipping.recipient_address.phone
string
|
Telephone number of the addressee. Allowable Values: 20 char max |
data[].fulfillment.shipping.recipient_address.postal_code
string
|
Postal code of the address. Allowable Values: 10 char max |
data[].fulfillment.shipping.recipient_address.state
string
|
State of the address. Allowable Values: 32 char max |
data[].fulfillment.shipping.recipient_address.zip
string
|
United States ZIP code of the address. Allowable Values: 10 char max |
data[].fulfillment.shipping.return_address
object
|
Address to which the order will be returned if shipping fails. Allowable Values:
|
data[].fulfillment.shipping.return_address.address1
string
|
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. |
data[].fulfillment.shipping.return_address.address2
string
|
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. |
data[].fulfillment.shipping.return_address.city
string
|
City of the address. Allowable Values: 40 char max |
data[].fulfillment.shipping.return_address.country
string
|
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. |
data[].fulfillment.shipping.return_address.first_name
string
|
First name of the addressee. Allowable Values: 40 char max |
data[].fulfillment.shipping.return_address.last_name
string
|
Last name of the addressee. Allowable Values: 40 char max |
data[].fulfillment.shipping.return_address.middle_name
string
|
Middle name of the addressee. Allowable Values: 40 char max |
data[].fulfillment.shipping.return_address.phone
string
|
Telephone number of the addressee. Allowable Values: 20 char max |
data[].fulfillment.shipping.return_address.postal_code
string
|
Postal code of the address. Allowable Values: 10 char max |
data[].fulfillment.shipping.return_address.state
string
|
State of the address. Allowable Values: 32 char max |
data[].fulfillment.shipping.return_address.zip
string
|
United States ZIP code of the address. Allowable Values: 10 char max |
data[].fulfillment_status
string
|
Provides status information about the card related to order and delivery. The possible fulfillment states are:
Allowable Values:
|
data[].last_four
string
|
Last four digits of the card primary account number (PAN). Allowable Values: 4 chars |
data[].pan
string
|
Primary account number (PAN) of the card. Allowable Values: 16 char max |
data[].pin_is_set
boolean
|
Specifies if the personal identification number (PIN) has been set for the card. Allowable Values: 4 chars |
data[].reason
string
|
Additional information about the state change. Allowable Values: 255 char max |
data[].reason_code
string
|
A standard code describing the reason for the transition:
Allowable Values:
|
data[].reissue_pan_from_card_token
string
|
Reissues the specified ("source") card. Allowable Values: Existing card token |
data[].new_pan_from_card_token
string
|
Reissues the specified ("source") card with a new primary account number (PAN). Allowable Values: Existing card token |
data[].state
string
|
Indicates the state of the card. Allowable Values:
|
data[].token
string
|
Unique identifier of the card transition. Allowable Values: 1–36 chars |
data[].type
string
|
This field cannot be set directly using the This field appears only when populated by the card fulfillment provider.
The
Allowable Values:
|
data[].user
object
|
Associates customer-injected metadata with the cardholder. Allowable Values:
|
data[].user.metadata
object
|
Associates customer-injected metadata with the cardholder. Allowable Values: You can define the names and values of up to 20 fields in the format |
data[].user_token
string
|
Unique identifier of the cardholder. Allowable Values: 1–36 chars |
data[].validations
object
|
Contains information about the user. Allowable Values: Existing |
data[].validations.user
object
|
Contains information about the user. Allowable Values:
|
data[].validations.user.birth_date
boolean
|
Indicates whether the Allowable Values:
|
data[].validations.user.phone
boolean
|
Indicates whether the Allowable Values:
|
data[].validations.user.random_name_line1_postfix
boolean
|
Indicates whether the Allowable Values:
|
data[].validations.user.ssn
boolean
|
Indicates whether the Allowable Values:
|
end_index
integer
|
Sort order index of the last resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer |
is_more
boolean
|
A value of This field is returned if there are resources in your returned array. Allowable Values:
|
start_index
integer
|
Sort order index of the first resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer |
Retrieve card transition
Copy section link
Action: GET
Endpoint: /cardtransitions/{token}
Retrieves a specific card transition. This endpoint supports field filtering.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
Unique identifier of the card transition.
Send a Allowable Values: Existing card transition token |
URL query parameters
Copy section link
| Fields | Description |
|---|---|
fields
string
|
Comma-delimited list of fields to return ( Allowable Values: Comma-delimited list of fields, or blank |
Response body
Copy section link
| Fields | Description |
|---|---|
barcode
string
|
The barcode printed on the card, expressed as digits. Allowable Values: 10-20 chars |
bulk_issuance_token
string
|
The unique identifier of the bulk card order. Allowable Values: 1-36 chars |
card
object
|
Associates customer-injected metadata with the card. Allowable Values:
|
card.metadata
object
|
Associates customer-injected metadata with the card. Allowable Values: You can define the names and values of up to 20 fields in the format |
card_product_token
string
|
Unique identifier of the card product. Allowable Values: 36 char max |
card_token
string
|
Unique identifier of the card. Allowable Values: 1–36 chars |
channel
string
|
The mechanism by which the transition was initiated.
Allowable Values:
|
created_time
datetime
|
Date and time when the resource was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
expedite
boolean
|
A value of Allowable Values:
|
expiration
string
|
Expiration date in Allowable Values: Format: MMyy |
expiration_time
string
|
Expiration date and time in UTC format. Allowable Values: Format: yyyy-MM-ddTHH:mm:ssZ |
fulfillment
object
|
Specifies certain physical characteristics of a card, as well as shipment information. Allowable Values:
|
fulfillment.card_fulfillment_reason
string
|
Reason for card fulfillment. Allowable Values:
|
fulfillment.card_personalization
object
|
Specifies personalized attributes to be added to the card. Allowable Values:
|
fulfillment.card_personalization.carrier
object
|
Specifies attributes of the card carrier. Allowable Values:
|
fulfillment.card_personalization.carrier.logo_file
string
|
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
|
Specifies a thumbnail-sized rendering of the image specified in the 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
|
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
|
Specifies a custom message that appears on the card carrier. Allowable Values: 60 char max |
fulfillment.card_personalization.carrier.template_id
string
|
Specifies the card carrier template to use. Allowable Values: Card carrier template ID |
fulfillment.card_personalization.images
object
|
Specifies personalized images that appear on the card. Allowable Values:
|
fulfillment.card_personalization.images.card
object
|
Specifies personalized images that appear on the card. Allowable Values:
|
fulfillment.card_personalization.images.card.name
string
|
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
|
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
|
Specifies personalized images that appear on the card carrier. Allowable Values:
|
fulfillment.card_personalization.images.carrier.message_1
string
|
Specifies a custom message that appears on the card carrier. Allowable Values: 60 char max |
fulfillment.card_personalization.images.carrier.name
string
|
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
|
Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders. Allowable Values:
|
fulfillment.card_personalization.images.carrier_return_window.name
string
|
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
|
Specifies a PNG image of the cardholder’s signature. Allowable Values:
|
fulfillment.card_personalization.images.signature.name
string
|
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
|
Specifies the type of card personalization. Allowable Values:
|
fulfillment.card_personalization.text
object
|
Specifies personalized text that appears on the card. Allowable Values:
|
fulfillment.card_personalization.text.name_line_1
object
|
Specifies the first line of personalized text that appears on the card. Allowable Values:
21 char max; if Strings longer than the character limit are truncated. |
fulfillment.card_personalization.text.name_line_1.value
string
|
Line of personalized text printed on the card. Allowable Values: 21 char max |
fulfillment.card_personalization.text.name_line_2
object
|
Specifies the second line of personalized text that appears on the card. Allowable Values:
|
fulfillment.card_personalization.text.name_line_2.value
string
|
Line of personalized text printed on the card. Allowable Values: 21 char max |
fulfillment.card_personalization.text.name_line_3
object
|
Specifies the third line of personalized text that appears on the card. Allowable Values:
|
fulfillment.card_personalization.text.name_line_3.value
string
|
Line of personalized text printed on the card. Allowable Values: 21 char max |
fulfillment.shipping
object
|
Specifies shipping details for the order. Allowable Values:
|
fulfillment.shipping.care_of_line
string
|
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
|
Specifies the shipping service. Allowable Values:
Shipping 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
|
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 order of precedence from highest to lowest is card, user, card product.
To be valid, an address must have the Allowable Values: Valid |
fulfillment.shipping.recipient_address.address1
string
|
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
|
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
|
City of the address. Allowable Values: 40 char max |
fulfillment.shipping.recipient_address.country
string
|
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
|
First name of the addressee. Allowable Values: 40 char max |
fulfillment.shipping.recipient_address.last_name
string
|
Last name of the addressee. Allowable Values: 40 char max |
fulfillment.shipping.recipient_address.middle_name
string
|
Middle name of the addressee. Allowable Values: 40 char max |
fulfillment.shipping.recipient_address.phone
string
|
Telephone number of the addressee. Allowable Values: 20 char max |
fulfillment.shipping.recipient_address.postal_code
string
|
Postal code of the address. Allowable Values: 10 char max |
fulfillment.shipping.recipient_address.state
string
|
State of the address. Allowable Values: 32 char max |
fulfillment.shipping.recipient_address.zip
string
|
United States ZIP code of the address. Allowable Values: 10 char max |
fulfillment.shipping.return_address
object
|
Address to which the order will be returned if shipping fails. Allowable Values:
|
fulfillment.shipping.return_address.address1
string
|
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
|
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
|
City of the address. Allowable Values: 40 char max |
fulfillment.shipping.return_address.country
string
|
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
|
First name of the addressee. Allowable Values: 40 char max |
fulfillment.shipping.return_address.last_name
string
|
Last name of the addressee. Allowable Values: 40 char max |
fulfillment.shipping.return_address.middle_name
string
|
Middle name of the addressee. Allowable Values: 40 char max |
fulfillment.shipping.return_address.phone
string
|
Telephone number of the addressee. Allowable Values: 20 char max |
fulfillment.shipping.return_address.postal_code
string
|
Postal code of the address. Allowable Values: 10 char max |
fulfillment.shipping.return_address.state
string
|
State of the address. Allowable Values: 32 char max |
fulfillment.shipping.return_address.zip
string
|
United States ZIP code of the address. Allowable Values: 10 char max |
fulfillment_status
string
|
Provides status information about the card related to order and delivery. The possible fulfillment states are:
Allowable Values:
|
last_four
string
|
Last four digits of the card primary account number (PAN). Allowable Values: 4 chars |
pan
string
|
Primary account number (PAN) of the card. Allowable Values: 16 char max |
pin_is_set
boolean
|
Specifies if the personal identification number (PIN) has been set for the card. Allowable Values: 4 chars |
reason
string
|
Additional information about the state change. Allowable Values: 255 char max |
reason_code
string
|
A standard code describing the reason for the transition:
Allowable Values:
|
reissue_pan_from_card_token
string
|
Reissues the specified ("source") card. Allowable Values: Existing card token |
new_pan_from_card_token
string
|
Reissues the specified ("source") card with a new primary account number (PAN). Allowable Values: Existing card token |
state
string
|
Indicates the state of the card. Allowable Values:
|
token
string
|
Unique identifier of the card transition. Allowable Values: 1–36 chars |
type
string
|
This field cannot be set directly using the This field appears only when populated by the card fulfillment provider.
The
Allowable Values:
|
user
object
|
Associates customer-injected metadata with the cardholder. Allowable Values:
|
user.metadata
object
|
Associates customer-injected metadata with the cardholder. Allowable Values: You can define the names and values of up to 20 fields in the format |
user_token
string
|
Unique identifier of the cardholder. Allowable Values: 1–36 chars |
validations
object
|
Contains information about the user. Allowable Values: Existing |
validations.user
object
|
Contains information about the user. Allowable Values:
|
validations.user.birth_date
boolean
|
Indicates whether the Allowable Values:
|
validations.user.phone
boolean
|
Indicates whether the Allowable Values:
|
validations.user.random_name_line1_postfix
boolean
|
Indicates whether the Allowable Values:
|
validations.user.ssn
boolean
|
Indicates whether the Allowable Values:
|