/
60 minute read
April 21, 2023

Card Transitions

Use the /cardtransitions API to set the state of an existing card.

Create card transition

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

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

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

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:

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
Copied

Is this helpful?

Yes
No

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:

Format: yyyy-MM-ddThh:mm:ssZ

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:

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

21 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_REGULAR

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

The 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 cards

Allowable 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

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

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
Copied

Is this helpful?

Yes
No

List transitions for card

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

Fields Description

token

string
Required

Unique identifier of the card.

Allowable Values:

Existing card token

URL query parameters

Fields Description

count

integer
Optional

Number of card transitions to retrieve.

Allowable Values:

1-10

Default value:
5

start_index

integer
Optional

Sort order index of the first resource in the returned array.

Allowable Values:

Any integer

Default value:
0

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

sort_by

string
Optional

Field on which to sort. Use any field in the resource model, or one of the system fields lastModifiedTime or createdTime. Prefix the field name with a hyphen (-) to sort in descending order. Omit the hyphen to sort in ascending order.

Allowable Values:

createdTime, lastModifiedTime, or any field in the resource model

Default value:
-createdTime

Response body

Fields Description

count

integer
Conditionally returned

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
Conditionally returned

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
Returned

The barcode printed on the card, expressed as digits.

Allowable Values:

10-20 chars

data[].bulk_issuance_token

string
Conditionally returned

The unique identifier of the bulk card order.

Allowable Values:

1-36 chars

data[].card

object
Conditionally returned

Associates customer-injected metadata with the card.

Allowable Values:

metadata

data[].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".

data[].card_product_token

string
Returned

Unique identifier of the card product.

Allowable Values:

36 char max

data[].card_token

string
Returned

Unique identifier of the card.

Allowable Values:

1–36 chars

data[].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

data[].created_time

datetime
Conditionally returned

Date and time when the resource was created, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

data[].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

data[].expiration

string
Returned

Expiration date in MMyy format.

Allowable Values:

Format: MMyy

data[].expiration_time

string
Returned

Expiration date and time in UTC format.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

data[].fulfillment

object
Conditionally returned

Specifies certain physical characteristics of a card, as well as shipment information.

Allowable Values:

card_fulfillment_reason, card_personalization, shipping

data[].fulfillment.card_fulfillment_reason

string
Conditionally returned

Reason for card fulfillment.

Allowable Values:

NEW, LOST_STOLEN, EXPIRED

data[].fulfillment.card_personalization

object
Returned

Specifies personalized attributes to be added to the card.

Allowable Values:

carrier, images, perso_type, text

data[].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

data[].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.

data[].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.

data[].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.

data[].fulfillment.card_personalization.carrier.message_line

string
Conditionally returned

Specifies a custom message that appears on the card carrier.

Allowable Values:

60 char max

data[].fulfillment.card_personalization.carrier.template_id

string
Conditionally returned

Specifies the card carrier template to use.

Allowable Values:

Card carrier template ID

data[].fulfillment.card_personalization.images

object
Conditionally returned

Specifies personalized images that appear on the card.

Allowable Values:

card, carrier, carrier_return_window, signature

data[].fulfillment.card_personalization.images.card

object
Conditionally returned

Specifies personalized images that appear on the card.

Allowable Values:

name, thermal_color

data[].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.

data[].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.

data[].fulfillment.card_personalization.images.carrier

object
Conditionally returned

Specifies personalized images that appear on the card carrier.

Allowable Values:

message_1, name

data[].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

data[].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.

data[].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

data[].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.

data[].fulfillment.card_personalization.images.signature

object
Conditionally returned

Specifies a PNG image of the cardholder’s signature.

Allowable Values:

name

data[].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.

data[].fulfillment.card_personalization.perso_type

string
Conditionally returned

Specifies the type of card personalization.

Allowable Values:

EMBOSS, LASER, FLAT

data[].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

data[].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.value

21 char max; if name_line_1_numeric_postfix is true, 14 char max.

Strings longer than the character limit are truncated.

data[].fulfillment.card_personalization.text.name_line_1.value

string
Conditionally returned

Line of personalized text printed on the card.

Allowable Values:

21 char max

data[].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

data[].fulfillment.card_personalization.text.name_line_2.value

string
Conditionally returned

Line of personalized text printed on the card.

Allowable Values:

21 char max

data[].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

data[].fulfillment.card_personalization.text.name_line_3.value

string
Conditionally returned

Line of personalized text printed on the card.

Allowable Values:

21 char max

data[].fulfillment.shipping

object
Conditionally returned

Specifies shipping details for the order.

Allowable Values:

care_of_line, method, recipient_address, return_address

data[].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

data[].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_REGULAR

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

The 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

data[].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.

data[].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.

data[].fulfillment.shipping.recipient_address.city

string
Conditionally returned

City of the address.

Allowable Values:

40 char max

data[].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.

data[].fulfillment.shipping.recipient_address.first_name

string
Conditionally returned

First name of the addressee.

Allowable Values:

40 char max

data[].fulfillment.shipping.recipient_address.last_name

string
Conditionally returned

Last name of the addressee.

Allowable Values:

40 char max

data[].fulfillment.shipping.recipient_address.middle_name

string
Conditionally returned

Middle name of the addressee.

Allowable Values:

40 char max

data[].fulfillment.shipping.recipient_address.phone

string
Conditionally returned

Telephone number of the addressee.

Allowable Values:

20 char max

data[].fulfillment.shipping.recipient_address.postal_code

string
Conditionally returned

Postal code of the address.

Allowable Values:

10 char max

data[].fulfillment.shipping.recipient_address.state

string
Conditionally returned

State of the address.

Allowable Values:

32 char max

data[].fulfillment.shipping.recipient_address.zip

string
Conditionally returned

United States ZIP code of the address.

Allowable Values:

10 char max

data[].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

data[].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.

data[].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.

data[].fulfillment.shipping.return_address.city

string
Conditionally returned

City of the address.

Allowable Values:

40 char max

data[].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.

data[].fulfillment.shipping.return_address.first_name

string
Conditionally returned

First name of the addressee.

Allowable Values:

40 char max

data[].fulfillment.shipping.return_address.last_name

string
Conditionally returned

Last name of the addressee.

Allowable Values:

40 char max

data[].fulfillment.shipping.return_address.middle_name

string
Conditionally returned

Middle name of the addressee.

Allowable Values:

40 char max

data[].fulfillment.shipping.return_address.phone

string
Conditionally returned

Telephone number of the addressee.

Allowable Values:

20 char max

data[].fulfillment.shipping.return_address.postal_code

string
Conditionally returned

Postal code of the address.

Allowable Values:

10 char max

data[].fulfillment.shipping.return_address.state

string
Conditionally returned

State of the address.

Allowable Values:

32 char max

data[].fulfillment.shipping.return_address.zip

string
Conditionally returned

United States ZIP code of the address.

Allowable Values:

10 char max

data[].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 cards

Allowable Values:

ISSUED, ORDERED, REJECTED, SHIPPED, DELIVERED, DIGITALLY_PRESENTED

data[].last_four

string
Returned

Last four digits of the card primary account number (PAN).

Allowable Values:

4 chars

data[].pan

string
Returned

Primary account number (PAN) of the card.

Allowable Values:

16 char max

data[].pin_is_set

boolean
Returned

Specifies if the personal identification number (PIN) has been set for the card.

Allowable Values:

4 chars

data[].reason

string
Conditionally returned

Additional information about the state change.

Allowable Values:

255 char max

data[].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

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

data[].reissue_pan_from_card_token

string
Conditionally returned

Reissues the specified ("source") card.

Allowable Values:

Existing card token

data[].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

data[].state

string
Returned

Indicates the state of the card.

Allowable Values:

ACTIVE, SUSPENDED, TERMINATED, UNACTIVATED

data[].token

string
Returned

Unique identifier of the card transition.

Allowable Values:

1–36 chars

data[].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

data[].user

object
Conditionally returned

Associates customer-injected metadata with the cardholder.

Allowable Values:

metadata

data[].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".

data[].user_token

string
Returned

Unique identifier of the cardholder.

Allowable Values:

1–36 chars

data[].validations

object
Conditionally returned

Contains information about the user.

Allowable Values:

Existing validations object

data[].validations.user

object
Returned

Contains information about the user.

Allowable Values:

birth_date, phone, random_name_line1_postfix, ssn

data[].validations.user.birth_date

boolean
Returned

Indicates whether the birth_date field in the request was validated.

Allowable Values:

true, false

data[].validations.user.phone

boolean
Returned

Indicates whether the phone field in the request was validated.

Allowable Values:

true, false

data[].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

data[].validations.user.ssn

boolean
Returned

Indicates whether the ssn field in the request was validated.

Allowable Values:

true, false

end_index

integer
Conditionally returned

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
Conditionally returned

A value of true indicates that more unreturned resources exist. A value of false indicates that no more unreturned resources exist.

This field is returned if there are resources in your returned array.

Allowable Values:

true, false

start_index

integer
Conditionally returned

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

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Retrieve card transition

Action: GET
Endpoint: /cardtransitions/{token}

Retrieves a specific card transition. This endpoint supports field filtering.

URL path parameters

Fields Description

token

string
Required

Unique identifier of the card transition. Send a GET request to /cardtransitions/card/{token} to retrieve card transition tokens for a specific card.

Allowable Values:

Existing card 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

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:

Format: yyyy-MM-ddThh:mm:ssZ

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:

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

21 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_REGULAR

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

The 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 cards

Allowable 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

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

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
Copied

Is this helpful?

Yes
No

Subscribe to our developer newsletter