Skip to main content
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

FieldsDescription
card_token

string

Required		Identifies the card whose state will transition.

Allowable Values:

1–36 chars

Existing card token.

Send a GET request to /cards/user/{token} to retrieve card tokens for a specific user.
channel

string

Required		The mechanism by which the transition was initiated.

- ADMIN - Indicates that the card transition was initiated through the Marqeta Dashboard.
- API - Indicates that the card transition was initiated by you through the Core API. Use this value when creating a card transition with an API POST request.
- FRAUD - Indicates that either Marqeta or the card network has determined that the card is fraudulent.
- IVR - Indicates that the card transition was initiated through your Interactive Voice Response system.
- SYSTEM - Indicates that the card transition was initiated by Marqeta. For example, Marqeta suspended the card due to excessive failed personal identification number (PIN) entries.

Allowable Values:

API, IVR, FRAUD, ADMIN, SYSTEM
reason

string

Optional		Additional information about the state change.

Allowable Values:

255 char max
reason_code

string

Optional		Standard code describing the reason for the transition.

NOTE: This field is required if your program uses v2 of the user_card_state_version, which is a program-specific configuration value that is managed by Marqeta and cannot be accessed via the API. To learn more about the user_card_state_version program configuration, contact your Marqeta representative.

- 00: Object activated for the first time
- 01: Requested by you
- 02: Inactivity over time
- 03: This address cannot accept mail or the addressee is unknown
- 04: Negative account balance
- 05: Account under review
- 06: Suspicious activity was identified
- 07: Activity outside the program parameters was identified
- 08: Confirmed fraud was identified
- 09: Matched with an Office of Foreign Assets Control list
- 10: Card was reported lost
- 11: Card information was cloned
- 12: Account or card information was compromised
- 13: Temporary status change while on hold/leave
- 14: Initiated by Marqeta
- 15: Initiated by issuer
- 16: Card expired
- 17: Failed KYC
- 18: Changed to ACTIVE because information was properly validated
- 19: Changed to ACTIVE because account activity was properly validated
- 20: Change occurred prior to the normalization of reason codes
- 21: Initiated by a third party, often a digital wallet provider
- 22: PIN retry limit reached
- 23: Card was reported stolen
- 24: Address issue
- 25: Name issue
- 26: SSN issue
- 27: DOB issue
- 28: Email issue
- 29: Phone issue
- 30: Account/fulfillment mismatch
- 31: Other reason
- 32: Unblock request
- 86: Notification of death

Allowable Values:

00, 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 86
state

string

Required		Specifies the new state.

Allowable Values:

ACTIVE, SUSPENDED, TERMINATED
token

string

Optional		Unique identifier of the card transition.

If you do not include a token, the system will generate one automatically. This token is referenced in other API calls, so we recommend that you define a simple string that is easy to remember. This value cannot be updated.

Allowable Values:

1–36 chars
sync_state_with_dwts

boolean

Optional		Set this field to true to synchronize the state of the card’s associated token(s) with the card’s new state. The digital wallet tokens must be in a valid starting state for the given transition, which will reflect the card’s state transition. For example, if the card is transitioning from the ACTIVE state to the SUSPENDED state, only digital wallet tokens in the ACTIVE state will be synchronized with the card state transition and therefore be transitioned to the SUSPENDED state.

Leave this field blank or set it to false to keep the states of the card and its digital wallet tokens independent.

Allowable Values:

true, false
validations

object

Optional		Contains information about the user.

Allowable Values:

user
validations.user

object

Optional		Contains information about the user.

Allowable Values:

birth_date, phone, random_name_line1_postfix, ssn
validations.user.birth_date

datetime

Optional		Date of birth of the user associated with this card.

Allowable Values:

datetime

Format:
yyyy-MM-ddThh:mm:ssZ
validations.user.phone

string

Optional		Telephone number of the user associated with this card.

Allowable Values:

255 char max

Format: 5105551212 or 510-555-1212
validations.user.random_name_line1_postfix

string

Optional		Random six-digit numeric postfix generated for some bulk card orders.

See Bulk Card Orders for more information about numeric postfixes.

Allowable Values:

6 chars
validations.user.ssn

string

Optional		Social Security Number (SSN) of the user associated with this card.

Allowable Values:

255 char max

​
Sample request body

JSON
{
  "token": "activate_05",
  "state": "ACTIVE",
  "reason": "I want to use this card, so activate it.",
  "reason_code": "00",
  "channel": "API",
  "card_token": "my_user_01_card_01",
  "validations": {
    "user": {
      "birth_date": "1990-01-31T00:00:00Z"
    }
  }
}

​
Response body

FieldsDescription
barcode

string

Returned		The barcode printed on the card, expressed as digits.

Allowable Values:

10-20 chars
bulk_issuance_token

string

Conditionally returned		The unique identifier of the bulk card order.

Allowable Values:

1-36 chars
card

object

Conditionally returned		Associates customer-injected metadata with the card.

Allowable Values:

metadata
card.metadata

object

Conditionally returned		Associates customer-injected metadata with the card.

Allowable Values:

You can define the names and values of up to 20 fields in the format "my_name_1": "my_value_1".
card_product_token

string

Returned		Unique identifier of the card product.

Allowable Values:

36 char max
card_token

string

Returned		Unique identifier of the card.

Allowable Values:

1–36 chars
channel

string

Returned		The mechanism by which the transition was initiated.

- ADMIN - Indicates that the card transition was initiated through the Marqeta Dashboard.
- API - Indicates that the card transition was initiated by you through the Core API. Use this value when creating a card transition with an API POST request.
- FRAUD - Indicates that either Marqeta or the card network has determined that the card is fraudulent.
- IVR - Indicates that the card transition was initiated through your Interactive Voice Response system.
- SYSTEM - Indicates that the card transition was initiated by Marqeta. For example, Marqeta suspended the card due to excessive failed personal identification number (PIN) entries.

Allowable Values:

API, IVR, FRAUD, ADMIN, SYSTEM
created_time

datetime

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

Allowable Values:

datetime

Format:
yyyy-MM-ddThh:mm:ssZ
created_timestamp

datetime

Conditionally returned		Date and time when the resource was created. Expressed in UTC, with millisecond precision.

Allowable Values:

datetime

Format:
yyyy-MM-ddThh:mm:ss:SSSZ
expedite

boolean

Conditionally returned		A value of true indicates that you requested expedited processing of the card from your card fulfillment provider.

Allowable Values:

true, false
expiration

string

Returned		Expiration date in MMyy format.

Allowable Values:

Format: MMyy
expiration_time

string

Returned		Expiration date and time in UTC format.

Allowable Values:

datetime

Format:
yyyy-MM-ddThh:mm:ssZ
fulfillment

object

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

Allowable Values:

card_fulfillment_reason, card_personalization, shipping
fulfillment.card_fulfillment_reason

string

Conditionally returned		Reason for card fulfillment.

Allowable Values:

NEW, LOST_STOLEN, EXPIRED
fulfillment.card_personalization

object

Returned		Specifies personalized attributes to be added to the card.

Allowable Values:

carrier, images, perso_type, text
fulfillment.card_personalization.carrier

object

Conditionally returned		Specifies attributes of the card carrier.

Allowable Values:

logo_file, logo_thumbnail_file, message_file, message_line, template_id
fulfillment.card_personalization.carrier.logo_file

string

Conditionally returned		Specifies an image to display on the card carrier.

Allowable Values:

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
fulfillment.card_personalization.carrier.logo_thumbnail_file

string

Conditionally returned		Specifies a thumbnail-sized rendering of the image specified in the logo_file field.

Allowable Values:

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
fulfillment.card_personalization.carrier.message_file

string

Conditionally returned		Specifies a text file containing a custom message to print on the card carrier.

Allowable Values:

Contains the name of the text file and must match the name of the file you send to your fulfillment provider.
fulfillment.card_personalization.carrier.message_line

string

Conditionally returned		Specifies a custom message that appears on the card carrier.

Allowable Values:

60 char max
fulfillment.card_personalization.carrier.message_line_2

string

Conditionally returned		Specifies the second line of a custom message that appears on the card carrier.

Allowable Values:

60 char max
fulfillment.card_personalization.carrier.template_id

string

Conditionally returned		Specifies the card carrier template to use.

Allowable Values:

Card carrier template ID
fulfillment.card_personalization.images

object

Conditionally returned		Specifies personalized images that appear on the card.

Allowable Values:

card, carrier, carrier_return_window, signature
fulfillment.card_personalization.images.card

object

Conditionally returned		Specifies personalized images that appear on the card.

Allowable Values:

name, thermal_color
fulfillment.card_personalization.images.card.name

string

Conditionally returned		Specifies a PNG image to display on the card.

Allowable Values:

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
fulfillment.card_personalization.images.card.thermal_color

string

Conditionally returned		Specifies the color of the image displayed on the card.

Allowable Values:

Contains the name of the color and must match one of the provider’s predefined colors.
fulfillment.card_personalization.images.carrier

object

Conditionally returned		Specifies personalized images that appear on the card carrier.

Allowable Values:

message_1, name
fulfillment.card_personalization.images.carrier.message_1

string

Conditionally returned		Specifies a custom message that appears on the card carrier.

Allowable Values:

60 char max
fulfillment.card_personalization.images.carrier.name

string

Conditionally returned		Specifies a PNG image to display on the card carrier.

Allowable Values:

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
fulfillment.card_personalization.images.carrier_return_window

object

Conditionally returned		Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders.

Allowable Values:

name
fulfillment.card_personalization.images.carrier_return_window.name

string

Conditionally returned		Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders.

Allowable Values:

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
fulfillment.card_personalization.images.signature

object

Conditionally returned		Specifies a PNG image of the cardholder’s signature.

Allowable Values:

name
fulfillment.card_personalization.images.signature.name

string

Conditionally returned		Specifies a PNG image of the cardholder’s signature.

Allowable Values:

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
fulfillment.card_personalization.perso_type

string

Conditionally returned		Specifies the type of card personalization.

Allowable Values:

EMBOSS, LASER, FLAT
fulfillment.card_personalization.text

object

Returned		Specifies personalized text that appears on the card.

Allowable Values:

name_line_1, name_line_2, name_line_3
fulfillment.card_personalization.text.name_line_1

object

Returned		Specifies the first line of personalized text that appears on the card.

Allowable Values:

name_line_1.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
- 32: Unblock request
- 86: Notification of death

Allowable Values:

00, 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 86
reissue_pan_from_card_token

string

Conditionally returned		Reissues the specified (“source”) card.

Allowable Values:

Existing card token
new_pan_from_card_token

string

Conditionally returned		Reissues the specified (“source”) card with a new primary account number (PAN).

Allowable Values:

Existing card token
state

string

Returned		Indicates the state of the card.

Allowable Values:

ACTIVE, SUSPENDED, TERMINATED, UNACTIVATED
token

string

Returned		Unique identifier of the card transition.

Allowable Values:

1–36 chars
type

string

Returned		This field cannot be set directly using the /cardtransitions endpoint. A card transition’s type is managed by the Marqeta platform, based on the before and after state of the transition, as specified in the request’s state field.

This field appears only when populated by the card fulfillment provider. The type field’s possible values are:

- fulfillment.delivered: Card was delivered by the card fulfillment provider
- fulfillment.digitally_presented: Card was digitally presented using the /cards/{token}/showpan endpoint; does not affect the delivery of physical cards
- fulfillment.issued: Card was created/issued
- fulfillment.ordered: Card was ordered from the card fulfillment provider
- fulfillment.rejected: Card was rejected by the card fulfillment provider
- fulfillment.shipped: Card was shipped by the card fulfillment provider
- state.activated: Card was activated
- state.limited: Card was limited
- state.reinstated: Card was reinstated from a suspended state
- state.suspended: Card was suspended
- state.terminated: Card was terminated

Allowable Values:

fulfillment.delivered, fulfillment.digitally_presented, fulfillment.issued, fulfillment.ordered, fulfillment.rejected, fulfillment.shipped, state.activated, state.limited, state.reinstated, state.suspended, state.terminated
user

object

Conditionally returned		Associates customer-injected metadata with the cardholder.

Allowable Values:

metadata
user.metadata

object

Conditionally returned		Associates customer-injected metadata with the cardholder.

Allowable Values:

You can define the names and values of up to 20 fields in the format "my_name_1": "my_value_1".
user_token

string

Returned		Unique identifier of the cardholder.

Allowable Values:

1–36 chars
validations

object

Conditionally returned		Contains information about the user.

Allowable Values:

Existing validations object
validations.user

object

Returned		Contains information about the user.

Allowable Values:

birth_date, phone, random_name_line1_postfix, ssn
validations.user.birth_date

boolean

Returned		Indicates whether the birth_date field in the request was validated.

Allowable Values:

true, false
validations.user.phone

boolean

Returned		Indicates whether the phone field in the request was validated.

Allowable Values:

true, false
validations.user.random_name_line1_postfix

boolean

Returned		Indicates whether the random_name_line1_postfix field in the request was validated.

Allowable Values:

true, false
validations.user.ssn

boolean

Returned		Indicates whether the ssn field in the request was validated.

Allowable Values:

true, false

​
Sample response body

JSON
{
  "token": "activate_05",
  "card_token": "my_user_01_card_01",
  "user_token": "my_user_01",
  "state": "ACTIVE",
  "reason": "I want to use this card, so activate it.",
  "reason_code": "00",
  "channel": "API",
  "expedite": false,
  "fulfillment_status": "ISSUED",
  "validations": {
    "user": {
      "birth_date": true,
      "phone": false,
      "random_name_line1_postfix": false,
      "ssn": false
    }
  },
  "type": "state.activated",
  "created_time": "2022-11-23T23:28:39Z",
  "card_product_token": "my_cardproduct_01",
  "last_four": "2160",
  "pan": "1111115454542160",
  "expiration": "1026",
  "expiration_time": "2026-10-31T23:59:59Z",
  "barcode": "11379418395311581864",
  "pin_is_set": false,
  "user": {
    "metadata": {
      "my_name_1": "my_value_1",
      "my_name_2": "my_value_2"
    }
  }
}

​
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

FieldsDescription
token

string

Required		Unique identifier of the card.

Allowable Values:

Existing card token

​
URL query parameters

FieldsDescription
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

FieldsDescription
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:

datetime

Format:
yyyy-MM-ddThh:mm:ssZ
data[].created_timestamp

datetime

Conditionally returned		Date and time when the resource was created. Expressed in UTC, with millisecond precision.

Allowable Values:

datetime

Format:
yyyy-MM-ddThh:mm:ss:SSSZ
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:

datetime

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

string

Conditionally returned		Specifies the second line of a custom message that appears on the card carrier.

Allowable Values:

60 char max
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
- 32: Unblock request
- 86: Notification of death

Allowable Values:

00, 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 86
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
{
  "count": 2,
  "start_index": 0,
  "end_index": 1,
  "is_more": false,
  "data": [
    {
      "token": "suspend_01",
      "card_token": "my_user_01_card_01",
      "user_token": "my_user_01",
      "state": "SUSPENDED",
      "reason": "I do not want to use this card, so suspend it.",
      "reason_code": "01",
      "channel": "API",
      "expedite": false,
      "fulfillment_status": "ISSUED",
      "validations": {
        "user": {
          "birth_date": true,
          "phone": false,
          "random_name_line1_postfix": false,
          "ssn": false
        }
      },
      "type": "state.suspended",
      "created_time": "2021-01-12T19:54:12Z",
      "card_product_token": "my_cardproduct_01",
      "last_four": "2160",
      "pan": "1111115454542160",
      "expiration": "1026",
      "expiration_time": "2026-10-31T23:59:59Z",
      "barcode": "11379418395311581864",
      "pin_is_set": false,
      "user": {
        "metadata": {
          "my_name_1": "my_value_1",
          "my_name_2": "my_value_2"
        }
      }
    },
    {
      "token": "activate_05",
      "card_token": "my_user_01_card_01",
      "user_token": "my_user_01",
      "state": "ACTIVE",
      "reason": "I want to use this card, so activate it.",
      "reason_code": "00",
      "channel": "API",
      "expedite": false,
      "fulfillment_status": "ISSUED",
      "validations": {
        "user": {
          "birth_date": true,
          "phone": false,
          "random_name_line1_postfix": false,
          "ssn": false
        }
      },
      "type": "state.activated",
      "created_time": "2022-02-23T23:28:39Z",
      "card_product_token": "my_cardproduct_01",
      "last_four": "2160",
      "pan": "1111115454542160",
      "expiration": "1026",
      "expiration_time": "2027-10-31T23:59:59Z",
      "barcode": "11379418395311581864",
      "pin_is_set": false,
      "user": {
        "metadata": {
          "my_name_1": "my_value_1",
          "my_name_2": "my_value_2"
        }
      }
    }
  ]
}

​
Retrieve card transition

Action: GET
Endpoint: /cardtransitions/{token} Retrieves a specific card transition. This endpoint supports field filtering.

​
URL path parameters

FieldsDescription
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

FieldsDescription
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

FieldsDescription
barcode

string

Returned		The barcode printed on the card, expressed as digits.

Allowable Values:

10-20 chars
bulk_issuance_token

string

Conditionally returned		The unique identifier of the bulk card order.

Allowable Values:

1-36 chars
card

object

Conditionally returned		Associates customer-injected metadata with the card.

Allowable Values:

metadata
card.metadata

object

Conditionally returned		Associates customer-injected metadata with the card.

Allowable Values:

You can define the names and values of up to 20 fields in the format "my_name_1": "my_value_1".
card_product_token

string

Returned		Unique identifier of the card product.

Allowable Values:

36 char max
card_token

string

Returned		Unique identifier of the card.

Allowable Values:

1–36 chars
channel

string

Returned		The mechanism by which the transition was initiated.

- ADMIN - Indicates that the card transition was initiated through the Marqeta Dashboard.
- API - Indicates that the card transition was initiated by you through the Core API. Use this value when creating a card transition with an API POST request.
- FRAUD - Indicates that either Marqeta or the card network has determined that the card is fraudulent.
- IVR - Indicates that the card transition was initiated through your Interactive Voice Response system.
- SYSTEM - Indicates that the card transition was initiated by Marqeta. For example, Marqeta suspended the card due to excessive failed personal identification number (PIN) entries.

Allowable Values:

API, IVR, FRAUD, ADMIN, SYSTEM
created_time

datetime

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

Allowable Values:

datetime

Format:
yyyy-MM-ddThh:mm:ssZ
created_timestamp

datetime

Conditionally returned		Date and time when the resource was created. Expressed in UTC, with millisecond precision.

Allowable Values:

datetime

Format:
yyyy-MM-ddThh:mm:ss:SSSZ
expedite

boolean

Conditionally returned		A value of true indicates that you requested expedited processing of the card from your card fulfillment provider.

Allowable Values:

true, false
expiration

string

Returned		Expiration date in MMyy format.

Allowable Values:

Format: MMyy
expiration_time

string

Returned		Expiration date and time in UTC format.

Allowable Values:

datetime

Format:
yyyy-MM-ddThh:mm:ssZ
fulfillment

object

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

Allowable Values:

card_fulfillment_reason, card_personalization, shipping
fulfillment.card_fulfillment_reason

string

Conditionally returned		Reason for card fulfillment.

Allowable Values:

NEW, LOST_STOLEN, EXPIRED
fulfillment.card_personalization

object

Returned		Specifies personalized attributes to be added to the card.

Allowable Values:

carrier, images, perso_type, text
fulfillment.card_personalization.carrier

object

Conditionally returned		Specifies attributes of the card carrier.

Allowable Values:

logo_file, logo_thumbnail_file, message_file, message_line, template_id
fulfillment.card_personalization.carrier.logo_file

string

Conditionally returned		Specifies an image to display on the card carrier.

Allowable Values:

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
fulfillment.card_personalization.carrier.logo_thumbnail_file

string

Conditionally returned		Specifies a thumbnail-sized rendering of the image specified in the logo_file field.

Allowable Values:

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
fulfillment.card_personalization.carrier.message_file

string

Conditionally returned		Specifies a text file containing a custom message to print on the card carrier.

Allowable Values:

Contains the name of the text file and must match the name of the file you send to your fulfillment provider.
fulfillment.card_personalization.carrier.message_line

string

Conditionally returned		Specifies a custom message that appears on the card carrier.

Allowable Values:

60 char max
fulfillment.card_personalization.carrier.message_line_2

string

Conditionally returned		Specifies the second line of a custom message that appears on the card carrier.

Allowable Values:

60 char max
fulfillment.card_personalization.carrier.template_id

string

Conditionally returned		Specifies the card carrier template to use.

Allowable Values:

Card carrier template ID
fulfillment.card_personalization.images

object

Conditionally returned		Specifies personalized images that appear on the card.

Allowable Values:

card, carrier, carrier_return_window, signature
fulfillment.card_personalization.images.card

object

Conditionally returned		Specifies personalized images that appear on the card.

Allowable Values:

name, thermal_color
fulfillment.card_personalization.images.card.name

string

Conditionally returned		Specifies a PNG image to display on the card.

Allowable Values:

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
fulfillment.card_personalization.images.card.thermal_color

string

Conditionally returned		Specifies the color of the image displayed on the card.

Allowable Values:

Contains the name of the color and must match one of the provider’s predefined colors.
fulfillment.card_personalization.images.carrier

object

Conditionally returned		Specifies personalized images that appear on the card carrier.

Allowable Values:

message_1, name
fulfillment.card_personalization.images.carrier.message_1

string

Conditionally returned		Specifies a custom message that appears on the card carrier.

Allowable Values:

60 char max
fulfillment.card_personalization.images.carrier.name

string

Conditionally returned		Specifies a PNG image to display on the card carrier.

Allowable Values:

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
fulfillment.card_personalization.images.carrier_return_window

object

Conditionally returned		Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders.

Allowable Values:

name
fulfillment.card_personalization.images.carrier_return_window.name

string

Conditionally returned		Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders.

Allowable Values:

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
fulfillment.card_personalization.images.signature

object

Conditionally returned		Specifies a PNG image of the cardholder’s signature.

Allowable Values:

name
fulfillment.card_personalization.images.signature.name

string

Conditionally returned		Specifies a PNG image of the cardholder’s signature.

Allowable Values:

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
fulfillment.card_personalization.perso_type

string

Conditionally returned		Specifies the type of card personalization.

Allowable Values:

EMBOSS, LASER, FLAT
fulfillment.card_personalization.text

object

Returned		Specifies personalized text that appears on the card.

Allowable Values:

name_line_1, name_line_2, name_line_3
fulfillment.card_personalization.text.name_line_1

object

Returned		Specifies the first line of personalized text that appears on the card.

Allowable Values:

name_line_1.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
- 32: Unblock request
- 86: Notification of death

Allowable Values:

00, 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 86
reissue_pan_from_card_token

string

Conditionally returned		Reissues the specified (“source”) card.

Allowable Values:

Existing card token
new_pan_from_card_token

string

Conditionally returned		Reissues the specified (“source”) card with a new primary account number (PAN).

Allowable Values:

Existing card token
state

string

Returned		Indicates the state of the card.

Allowable Values:

ACTIVE, SUSPENDED, TERMINATED, UNACTIVATED
token

string

Returned		Unique identifier of the card transition.

Allowable Values:

1–36 chars
type

string

Returned		This field cannot be set directly using the /cardtransitions endpoint. A card transition’s type is managed by the Marqeta platform, based on the before and after state of the transition, as specified in the request’s state field.

This field appears only when populated by the card fulfillment provider. The type field’s possible values are:

- fulfillment.delivered: Card was delivered by the card fulfillment provider
- fulfillment.digitally_presented: Card was digitally presented using the /cards/{token}/showpan endpoint; does not affect the delivery of physical cards
- fulfillment.issued: Card was created/issued
- fulfillment.ordered: Card was ordered from the card fulfillment provider
- fulfillment.rejected: Card was rejected by the card fulfillment provider
- fulfillment.shipped: Card was shipped by the card fulfillment provider
- state.activated: Card was activated
- state.limited: Card was limited
- state.reinstated: Card was reinstated from a suspended state
- state.suspended: Card was suspended
- state.terminated: Card was terminated

Allowable Values:

fulfillment.delivered, fulfillment.digitally_presented, fulfillment.issued, fulfillment.ordered, fulfillment.rejected, fulfillment.shipped, state.activated, state.limited, state.reinstated, state.suspended, state.terminated
user

object

Conditionally returned		Associates customer-injected metadata with the cardholder.

Allowable Values:

metadata
user.metadata

object

Conditionally returned		Associates customer-injected metadata with the cardholder.

Allowable Values:

You can define the names and values of up to 20 fields in the format "my_name_1": "my_value_1".
user_token

string

Returned		Unique identifier of the cardholder.

Allowable Values:

1–36 chars
validations

object

Conditionally returned		Contains information about the user.

Allowable Values:

Existing validations object
validations.user

object

Returned		Contains information about the user.

Allowable Values:

birth_date, phone, random_name_line1_postfix, ssn
validations.user.birth_date

boolean

Returned		Indicates whether the birth_date field in the request was validated.

Allowable Values:

true, false
validations.user.phone

boolean

Returned		Indicates whether the phone field in the request was validated.

Allowable Values:

true, false
validations.user.random_name_line1_postfix

boolean

Returned		Indicates whether the random_name_line1_postfix field in the request was validated.

Allowable Values:

true, false
validations.user.ssn

boolean

Returned		Indicates whether the ssn field in the request was validated.

Allowable Values:

true, false

​
Sample response body

JSON
{
  "token": "activate_05",
  "card_token": "my_user_01_card_01",
  "user_token": "my_user_01",
  "state": "ACTIVE",
  "reason": "I want to use this card, so activate it.",
  "reason_code": "00",
  "channel": "API",
  "expedite": false,
  "fulfillment_status": "ISSUED",
  "validations": {
    "user": {
      "birth_date": true,
      "phone": false,
      "random_name_line1_postfix": false,
      "ssn": false
    }
  },
  "type": "state.activated",
  "created_time": "2022-02-23T23:28:39Z",
  "card_product_token": "my_cardproduct_01",
  "last_four": "2160",
  "pan": "1111115454542160",
  "expiration": "1026",
  "expiration_time": "2027-10-31T23:59:59Z",
  "barcode": "11379418395311581864",
  "pin_is_set": false,
  "user": {
    "metadata": {
      "my_name_1": "my_value_1",
      "my_name_2": "my_value_2"
    }
  }
}

Related topics

User TransitionsAccount TransitionsBusiness TransitionsCardholder and Card Management in EuropeSynchronizing Digital Wallet Tokens with Card State