/
50 minute read
March 24, 2022

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

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

state

string
Required

Specifies the new state.

Allowable Values:

ACTIVE, SUSPENDED, TERMINATED

token

string
Optional

The 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

validations

object
Optional

Contains information about the user.

Allowable Values:

Valid validations object

validations.user

object
Optional

Contains information about the user.

Allowable Values:

Valid validations.user object

validations.user.birth_date

datetime
Optional

The birth date of the user associated with this card.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

validations.user.phone

string
Optional

The 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

A 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

The Social Security number 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 numerals.

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:

Existing card.metadata object

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

The unique identifier of the card product.

Allowable Values:

36 char max

card_token

string
Returned

The 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 PIN entries.

Allowable Values:

API, IVR, FRAUD, ADMIN, SYSTEM

created_time

datetime
Conditionally returned

The date and time when the resource was created, in UTC. 2021-10-26T20:03:05Z, for example.

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

The expiration date in MMyy format.

Allowable Values:

Format: MMyy

expiration_time

string
Returned

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

Existing fulfillment object

fulfillment.card_fulfillment_reason

string
Conditionally returned

The reason for card fulfillment.

Allowable Values:

NEW, LOST_STOLEN, EXPIRED

fulfillment.card_personalization

object
Returned

Allows personalized attributes to be added to the card.

Allowable Values:

Valid card_personalization object

fulfillment.card_personalization.carrier

object
Conditionally returned

Specifies attributes of the card carrier.

Allowable Values:

Valid carrier object

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. Also specifies attributes of the card carrier, if your fulfillment provider is Perfect Plastic Printing or IDEMIA.

Allowable Values:

Valid images object

fulfillment.card_personalization.images.card

object
Conditionally returned

Specifies personalized images that appear on the card.

Allowable Values:

Valid images.card object

fulfillment.card_personalization.images.carrier

object
Conditionally returned

Specifies personalized images that appear on the card carrier.

Allowable Values:

Valid carrier object

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:

Valid carrier_return_window object

fulfillment.card_personalization.images.signature

object
Conditionally returned

Specifies a PNG image of the cardholder’s signature.

Allowable Values:

Valid signature object

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:

Valid text object

fulfillment.card_personalization.text.name_line_1

object
Returned

First line of personalized text printed on the card.

Allowable Values:

name_line1.value

fulfillment.card_personalization.text.name_line_2

object
Conditionally returned

Second line of personalized text printed on the card.

Allowable Values:

name_line2.value

fulfillment.card_personalization.text.name_line_3

object
Conditionally returned

Third line of personalized text printed on the card.

Allowable Values:

name_line3.value

fulfillment.shipping

object
Conditionally returned

Specifies the shipping details for the card.

Allowable Values:

Valid shipping object

fulfillment.shipping.care_of_line

string
Conditionally returned

Adds the specified value as a C/O (care of) line to the mailing carrier.

NOTE: This field overrides the equivalent field on the associated card product.

Allowable Values:

255 char max

fulfillment.shipping.method

string
Conditionally returned

Specifies the shipping service.

Allowable Values:

LOCAL_MAIL, GROUND, TWO_DAY, OVERNIGHT, INTERNATIONAL, 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 card will be shipped.

For individual card orders: If no recipient_address is specified for the card, then the recipient_address for the user is used. If no recipient_address is specified for the user, then the recipient_address for the card product is used. For an address to be valid for use, its address1, city, state, and postal_code fields must be populated. The country is assumed to be the United States if the country field is unpopulated.

Allowable Values:

Valid recipient_address object

fulfillment.shipping.recipient_address.address1

string
Conditionally returned

Number and street.

Allowable Values:

255 char max

Lower character limits may be imposed by providers. Perfect Plastic Printing and IDEMIA limit chars to 100, and Arroweye Solutions limits chars to 50.

fulfillment.shipping.recipient_address.address2

string
Conditionally returned

Additional address information.

Allowable Values:

255 char max

Lower character limits may be imposed by providers. Perfect Plastic Printing and IDEMIA limit chars to 100, and Arroweye Solutions limits chars to 50.

fulfillment.shipping.recipient_address.city

string
Conditionally returned

City.

Allowable Values:

40 char max

fulfillment.shipping.recipient_address.country

string
Conditionally returned

Country.

Allowable Values:

40 char max

The short English name. For example, "Spain".

The ISO maintains the full list of country codes. This list includes the item "United States of America (the)," but "United States of America" is acceptable.

fulfillment.shipping.recipient_address.first_name

string
Conditionally returned

First name.

Allowable Values:

40 char max

fulfillment.shipping.recipient_address.last_name

string
Conditionally returned

Last name.

Allowable Values:

40 char max

fulfillment.shipping.recipient_address.middle_name

string
Conditionally returned

Middle name.

Allowable Values:

40 char max

fulfillment.shipping.recipient_address.phone

string
Conditionally returned

Telephone number.

Allowable Values:

20 char max

fulfillment.shipping.recipient_address.postal_code

string
Conditionally returned

Postal code.

Allowable Values:

10 char max

fulfillment.shipping.recipient_address.state

string
Conditionally returned

State.

Allowable Values:

32 char max

fulfillment.shipping.recipient_address.zip

string
Conditionally returned

United States ZIP code.

Allowable Values:

10 char max

fulfillment.shipping.return_address

object
Conditionally returned

Address to which cards will be returned if shipping fails.

Allowable Values:

Valid return_address object

fulfillment.shipping.return_address.address1

string
Conditionally returned

Number and street.

Allowable Values:

255 char max

Lower character limits may be imposed by providers. Perfect Plastic Printing and IDEMIA limit chars to 100, and Arroweye Solutions limits chars to 50.

fulfillment.shipping.return_address.address2

string
Conditionally returned

Additional address information.

Allowable Values:

255 char max

Lower character limits may be imposed by providers. Perfect Plastic Printing and IDEMIA limit chars to 100, and Arroweye Solutions limits chars to 50.

fulfillment.shipping.return_address.city

string
Conditionally returned

City.

Allowable Values:

40 char max

fulfillment.shipping.return_address.country

string
Conditionally returned

Country.

Allowable Values:

40 char max

The short English name. For example, "Spain".

The ISO maintains the full list of country codes. This list includes the item "United States of America (the)," but "United States of America" is acceptable.

fulfillment.shipping.return_address.first_name

string
Conditionally returned

First name.

Allowable Values:

40 char max

fulfillment.shipping.return_address.last_name

string
Conditionally returned

Last name.

Allowable Values:

40 char max

fulfillment.shipping.return_address.middle_name

string
Conditionally returned

Middle name.

Allowable Values:

40 char max

fulfillment.shipping.return_address.phone

string
Conditionally returned

Telephone number.

Allowable Values:

20 char max

fulfillment.shipping.return_address.postal_code

string
Conditionally returned

Postal code.

Allowable Values:

10 char max

fulfillment.shipping.return_address.state

string
Conditionally returned

State.

Allowable Values:

32 char max

fulfillment.shipping.return_address.zip

string
Conditionally returned

United States ZIP code.

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

The last four digits of the card PAN.

Allowable Values:

4 chars

pan

string
Returned

The 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 card (known as the "source" card).

Allowable Values:

Existing card token

state

string
Returned

Indicates the state of the card.

Allowable Values:

ACTIVE, SUSPENDED, TERMINATED, UNACTIVATED

token

string
Returned

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

  • state.activated: Card was activated

  • state.reinstated: Card was reinstated from a suspended state

  • state.suspended: Card was suspended

  • state.terminated: Card was terminated

  • state.limited: Card was limited

  • 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.reordered: Card was reordered from the card fulfillment provider

  • fulfillment.shipped: Card was shipped by the card fulfillment provider.

  • fulfillment.delivered: Card was delivered by the card fulfillment provider

Allowable Values:

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

user

object
Conditionally returned

Associates customer-injected metadata with the cardholder.

Allowable Values:

Existing cardholder.metadata object

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

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

Valid validations.user object

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

The unique identifier of the card.

Allowable Values:

Existing card token

URL query parameters
Fields Description

count

integer
Optional

The number of card transitions to retrieve.

Allowable Values:

1-10

start_index

integer
Optional

The sort order index of the first resource in the returned array.

Allowable Values:

Any integer

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:

lastModifiedTime, createdTime, or any field in the resource model

Response body
Fields Description

count

integer
Conditionally returned

The number of resources to retrieve.

Allowable Values:

1-10

data

array of objects
Conditionally returned

An array of card transitions.

Allowable Values:

Existing card transition array

data[].barcode

string
Returned

The barcode printed on the card, expressed as numerals.

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:

Existing card.metadata object

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

The unique identifier of the card product.

Allowable Values:

36 char max

data[].card_token

string
Returned

The 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 PIN entries.

Allowable Values:

API, IVR, FRAUD, ADMIN, SYSTEM

data[].created_time

datetime
Conditionally returned

The date and time when the resource was created, in UTC. 2021-10-26T20:03:05Z, for example.

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

The expiration date in MMyy format.

Allowable Values:

Format: MMyy

data[].expiration_time

string
Returned

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

Existing fulfillment object

data[].fulfillment.card_fulfillment_reason

string
Conditionally returned

The reason for card fulfillment.

Allowable Values:

NEW, LOST_STOLEN, EXPIRED

data[].fulfillment.card_personalization

object
Returned

Allows personalized attributes to be added to the card.

Allowable Values:

Valid card_personalization object

data[].fulfillment.card_personalization.carrier

object
Conditionally returned

Specifies attributes of the card carrier.

Allowable Values:

Valid carrier object

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. Also specifies attributes of the card carrier, if your fulfillment provider is Perfect Plastic Printing or IDEMIA.

Allowable Values:

Valid images object

data[].fulfillment.card_personalization.images.card

object
Conditionally returned

Specifies personalized images that appear on the card.

Allowable Values:

Valid images.card object

data[].fulfillment.card_personalization.images.carrier

object
Conditionally returned

Specifies personalized images that appear on the card carrier.

Allowable Values:

Valid carrier object

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:

Valid carrier_return_window object

data[].fulfillment.card_personalization.images.signature

object
Conditionally returned

Specifies a PNG image of the cardholder’s signature.

Allowable Values:

Valid signature object

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:

Valid text object

data[].fulfillment.card_personalization.text.name_line_1

object
Returned

First line of personalized text printed on the card.

Allowable Values:

name_line1.value

data[].fulfillment.card_personalization.text.name_line_2

object
Conditionally returned

Second line of personalized text printed on the card.

Allowable Values:

name_line2.value

data[].fulfillment.card_personalization.text.name_line_3

object
Conditionally returned

Third line of personalized text printed on the card.

Allowable Values:

name_line3.value

data[].fulfillment.shipping

object
Conditionally returned

Specifies the shipping details for the card.

Allowable Values:

Valid shipping object

data[].fulfillment.shipping.care_of_line

string
Conditionally returned

Adds the specified value as a C/O (care of) line to the mailing carrier.

NOTE: This field overrides the equivalent field on the associated card product.

Allowable Values:

255 char max

data[].fulfillment.shipping.method

string
Conditionally returned

Specifies the shipping service.

Allowable Values:

LOCAL_MAIL, GROUND, TWO_DAY, OVERNIGHT, INTERNATIONAL, 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 card will be shipped.

For individual card orders: If no recipient_address is specified for the card, then the recipient_address for the user is used. If no recipient_address is specified for the user, then the recipient_address for the card product is used. For an address to be valid for use, its address1, city, state, and postal_code fields must be populated. The country is assumed to be the United States if the country field is unpopulated.

Allowable Values:

Valid recipient_address object

data[].fulfillment.shipping.recipient_address.address1

string
Conditionally returned

Number and street.

Allowable Values:

255 char max

Lower character limits may be imposed by providers. Perfect Plastic Printing and IDEMIA limit chars to 100, and Arroweye Solutions limits chars to 50.

data[].fulfillment.shipping.recipient_address.address2

string
Conditionally returned

Additional address information.

Allowable Values:

255 char max

Lower character limits may be imposed by providers. Perfect Plastic Printing and IDEMIA limit chars to 100, and Arroweye Solutions limits chars to 50.

data[].fulfillment.shipping.recipient_address.city

string
Conditionally returned

City.

Allowable Values:

40 char max

data[].fulfillment.shipping.recipient_address.country

string
Conditionally returned

Country.

Allowable Values:

40 char max

The short English name. For example, "Spain".

The ISO maintains the full list of country codes. This list includes the item "United States of America (the)," but "United States of America" is acceptable.

data[].fulfillment.shipping.recipient_address.first_name

string
Conditionally returned

First name.

Allowable Values:

40 char max

data[].fulfillment.shipping.recipient_address.last_name

string
Conditionally returned

Last name.

Allowable Values:

40 char max

data[].fulfillment.shipping.recipient_address.middle_name

string
Conditionally returned

Middle name.

Allowable Values:

40 char max

data[].fulfillment.shipping.recipient_address.phone

string
Conditionally returned

Telephone number.

Allowable Values:

20 char max

data[].fulfillment.shipping.recipient_address.postal_code

string
Conditionally returned

Postal code.

Allowable Values:

10 char max

data[].fulfillment.shipping.recipient_address.state

string
Conditionally returned

State.

Allowable Values:

32 char max

data[].fulfillment.shipping.recipient_address.zip

string
Conditionally returned

United States ZIP code.

Allowable Values:

10 char max

data[].fulfillment.shipping.return_address

object
Conditionally returned

Address to which cards will be returned if shipping fails.

Allowable Values:

Valid return_address object

data[].fulfillment.shipping.return_address.address1

string
Conditionally returned

Number and street.

Allowable Values:

255 char max

Lower character limits may be imposed by providers. Perfect Plastic Printing and IDEMIA limit chars to 100, and Arroweye Solutions limits chars to 50.

data[].fulfillment.shipping.return_address.address2

string
Conditionally returned

Additional address information.

Allowable Values:

255 char max

Lower character limits may be imposed by providers. Perfect Plastic Printing and IDEMIA limit chars to 100, and Arroweye Solutions limits chars to 50.

data[].fulfillment.shipping.return_address.city

string
Conditionally returned

City.

Allowable Values:

40 char max

data[].fulfillment.shipping.return_address.country

string
Conditionally returned

Country.

Allowable Values:

40 char max

The short English name. For example, "Spain".

The ISO maintains the full list of country codes. This list includes the item "United States of America (the)," but "United States of America" is acceptable.

data[].fulfillment.shipping.return_address.first_name

string
Conditionally returned

First name.

Allowable Values:

40 char max

data[].fulfillment.shipping.return_address.last_name

string
Conditionally returned

Last name.

Allowable Values:

40 char max

data[].fulfillment.shipping.return_address.middle_name

string
Conditionally returned

Middle name.

Allowable Values:

40 char max

data[].fulfillment.shipping.return_address.phone

string
Conditionally returned

Telephone number.

Allowable Values:

20 char max

data[].fulfillment.shipping.return_address.postal_code

string
Conditionally returned

Postal code.

Allowable Values:

10 char max

data[].fulfillment.shipping.return_address.state

string
Conditionally returned

State.

Allowable Values:

32 char max

data[].fulfillment.shipping.return_address.zip

string
Conditionally returned

United States ZIP code.

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

The last four digits of the card PAN.

Allowable Values:

4 chars

data[].pan

string
Returned

The 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 card (known as the "source" card).

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

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

  • state.activated: Card was activated

  • state.reinstated: Card was reinstated from a suspended state

  • state.suspended: Card was suspended

  • state.terminated: Card was terminated

  • state.limited: Card was limited

  • 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.reordered: Card was reordered from the card fulfillment provider

  • fulfillment.shipped: Card was shipped by the card fulfillment provider.

  • fulfillment.delivered: Card was delivered by the card fulfillment provider.

Allowable Values:

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

data[].user

object
Conditionally returned

Associates customer-injected metadata with the cardholder.

Allowable Values:

Existing cardholder.metadata object

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

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

Valid validations.user object

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

The sort order index of the last resource in the returned array.

Allowable Values:

Any integer

is_more

boolean
Conditionally returned

A value of true indicates that more unreturned resources exist.

Allowable Values:

true, false

start_index

integer
Conditionally returned

The sort order index of the first resource in the 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

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

lastModifiedTime, createdTime, or any field in the resource model

Response body
Fields Description

barcode

string
Returned

The barcode printed on the card, expressed as numerals.

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:

Existing card.metadata object

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

The unique identifier of the card product.

Allowable Values:

36 char max

card_token

string
Returned

The 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 PIN entries.

Allowable Values:

API, IVR, FRAUD, ADMIN, SYSTEM

created_time

datetime
Conditionally returned

The date and time when the resource was created, in UTC. 2021-10-26T20:03:05Z, for example.

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

The expiration date in MMyy format.

Allowable Values:

Format: MMyy

expiration_time

string
Returned

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

Existing fulfillment object

fulfillment.card_fulfillment_reason

string
Conditionally returned

The reason for card fulfillment.

Allowable Values:

NEW, LOST_STOLEN, EXPIRED

fulfillment.card_personalization

object
Returned

Allows personalized attributes to be added to the card.

Allowable Values:

Valid card_personalization object

fulfillment.card_personalization.carrier

object
Conditionally returned

Specifies attributes of the card carrier.

Allowable Values:

Valid carrier object

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. Also specifies attributes of the card carrier, if your fulfillment provider is Perfect Plastic Printing or IDEMIA.

Allowable Values:

Valid images object

fulfillment.card_personalization.images.card

object
Conditionally returned

Specifies personalized images that appear on the card.

Allowable Values:

Valid images.card object

fulfillment.card_personalization.images.carrier

object
Conditionally returned

Specifies personalized images that appear on the card carrier.

Allowable Values:

Valid carrier object

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:

Valid carrier_return_window object

fulfillment.card_personalization.images.signature

object
Conditionally returned

Specifies a PNG image of the cardholder’s signature.

Allowable Values:

Valid signature object

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:

Valid text object

fulfillment.card_personalization.text.name_line_1

object
Returned

First line of personalized text printed on the card.

Allowable Values:

name_line1.value

fulfillment.card_personalization.text.name_line_2

object
Conditionally returned

Second line of personalized text printed on the card.

Allowable Values:

name_line2.value

fulfillment.card_personalization.text.name_line_3

object
Conditionally returned

Third line of personalized text printed on the card.

Allowable Values:

name_line3.value

fulfillment.shipping

object
Conditionally returned

Specifies the shipping details for the card.

Allowable Values:

Valid shipping object

fulfillment.shipping.care_of_line

string
Conditionally returned

Adds the specified value as a C/O (care of) line to the mailing carrier.

NOTE: This field overrides the equivalent field on the associated card product.

Allowable Values:

255 char max

fulfillment.shipping.method

string
Conditionally returned

Specifies the shipping service.

Allowable Values:

LOCAL_MAIL, GROUND, TWO_DAY, OVERNIGHT, INTERNATIONAL, 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 card will be shipped.

For individual card orders: If no recipient_address is specified for the card, then the recipient_address for the user is used. If no recipient_address is specified for the user, then the recipient_address for the card product is used. For an address to be valid for use, its address1, city, state, and postal_code fields must be populated. The country is assumed to be the United States if the country field is unpopulated.

Allowable Values:

Valid recipient_address object

fulfillment.shipping.recipient_address.address1

string
Conditionally returned

Number and street.

Allowable Values:

255 char max

Lower character limits may be imposed by providers. Perfect Plastic Printing and IDEMIA limit chars to 100, and Arroweye Solutions limits chars to 50.

fulfillment.shipping.recipient_address.address2

string
Conditionally returned

Additional address information.

Allowable Values:

255 char max

Lower character limits may be imposed by providers. Perfect Plastic Printing and IDEMIA limit chars to 100, and Arroweye Solutions limits chars to 50.

fulfillment.shipping.recipient_address.city

string
Conditionally returned

City.

Allowable Values:

40 char max

fulfillment.shipping.recipient_address.country

string
Conditionally returned

Country.

Allowable Values:

40 char max

The short English name. For example, "Spain".

The ISO maintains the full list of country codes. This list includes the item "United States of America (the)," but "United States of America" is acceptable.

fulfillment.shipping.recipient_address.first_name

string
Conditionally returned

First name.

Allowable Values:

40 char max

fulfillment.shipping.recipient_address.last_name

string
Conditionally returned

Last name.

Allowable Values:

40 char max

fulfillment.shipping.recipient_address.middle_name

string
Conditionally returned

Middle name.

Allowable Values:

40 char max

fulfillment.shipping.recipient_address.phone

string
Conditionally returned

Telephone number.

Allowable Values:

20 char max

fulfillment.shipping.recipient_address.postal_code

string
Conditionally returned

Postal code.

Allowable Values:

10 char max

fulfillment.shipping.recipient_address.state

string
Conditionally returned

State.

Allowable Values:

32 char max

fulfillment.shipping.recipient_address.zip

string
Conditionally returned

United States ZIP code.

Allowable Values:

10 char max

fulfillment.shipping.return_address

object
Conditionally returned

Address to which cards will be returned if shipping fails.

Allowable Values:

Valid return_address object

fulfillment.shipping.return_address.address1

string
Conditionally returned

Number and street.

Allowable Values:

255 char max

Lower character limits may be imposed by providers. Perfect Plastic Printing and IDEMIA limit chars to 100, and Arroweye Solutions limits chars to 50.

fulfillment.shipping.return_address.address2

string
Conditionally returned

Additional address information.

Allowable Values:

255 char max

Lower character limits may be imposed by providers. Perfect Plastic Printing and IDEMIA limit chars to 100, and Arroweye Solutions limits chars to 50.

fulfillment.shipping.return_address.city

string
Conditionally returned

City.

Allowable Values:

40 char max

fulfillment.shipping.return_address.country

string
Conditionally returned

Country.

Allowable Values:

40 char max

The short English name. For example, "Spain".

The ISO maintains the full list of country codes. This list includes the item "United States of America (the)," but "United States of America" is acceptable.

fulfillment.shipping.return_address.first_name

string
Conditionally returned

First name.

Allowable Values:

40 char max

fulfillment.shipping.return_address.last_name

string
Conditionally returned

Last name.

Allowable Values:

40 char max

fulfillment.shipping.return_address.middle_name

string
Conditionally returned

Middle name.

Allowable Values:

40 char max

fulfillment.shipping.return_address.phone

string
Conditionally returned

Telephone number.

Allowable Values:

20 char max

fulfillment.shipping.return_address.postal_code

string
Conditionally returned

Postal code.

Allowable Values:

10 char max

fulfillment.shipping.return_address.state

string
Conditionally returned

State.

Allowable Values:

32 char max

fulfillment.shipping.return_address.zip

string
Conditionally returned

United States ZIP code.

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

The last four digits of the card PAN.

Allowable Values:

4 chars

pan

string
Returned

The 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 card (known as the "source" card).

Allowable Values:

Existing card token

state

string
Returned

Indicates the state of the card.

Allowable Values:

ACTIVE, SUSPENDED, TERMINATED, UNACTIVATED

token

string
Returned

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

  • state.activated: Card was activated

  • state.reinstated: Card was reinstated from a suspended state

  • state.suspended: Card was suspended

  • state.terminated: Card was terminated

  • state.limited: Card was limited

  • 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.reordered: Card was reordered from the card fulfillment provider

  • fulfillment.shipped: Card was shipped by the card fulfillment provider.

  • fulfillment.delivered: Card was delivered by the card fulfillment provider.

Allowable Values:

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

user

object
Conditionally returned

Associates customer-injected metadata with the cardholder.

Allowable Values:

Existing cardholder.metadata object

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

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

Valid validations.user object

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
Join our developer newsletter