> ## Documentation Index
> Fetch the complete documentation index at: https://www.marqeta.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Card Transitions
> Use the cards transitions endpoint to set the state of an existing card.
export const EndpointCard = ({method = "API", title, children, href, arrow = true}) => {
const METHOD_STYLES = {
GET: {
bg: "mint-bg-green-400/20 dark:mint-bg-green-400/20",
text: "mint-text-green-700 dark:mint-text-green-400",
border: "mint-border-green-300 dark:mint-border-green-700"
},
POST: {
bg: "mint-bg-blue-400/20 dark:mint-bg-blue-400/20",
text: "mint-text-blue-700 dark:mint-text-blue-400"
},
PUT: {
bg: "mint-bg-yellow-400/20 dark:mint-bg-yellow-400/20",
text: "mint-text-yellow-700 dark:mint-text-yellow-400"
},
PATCH: {
bg: "mint-bg-orange-400/20 dark:mint-bg-orange-400/20",
text: "mint-text-orange-700 dark:mint-text-orange-400"
},
DELETE: {
bg: "mint-bg-red-400/20 dark:mint-bg-red-400/20",
text: "mint-text-red-700 dark:mint-text-red-400"
},
API: {
bg: "mint-bg-black",
text: "mint-text-white"
}
};
const MethodBadge = ({method}) => {
const style = METHOD_STYLES[method?.toUpperCase()] ?? METHOD_STYLES.GET;
return
{method?.toUpperCase()}
;
};
const content =
{}
{}
{title}
{children &&
{children}
}
Create card transition
**Action:** `POST`\
**Endpoint:** `/cardtransitions`
{/* */}
Creates a card state transition to set the state of an existing card.
If your system uses IVR, you can send a `POST` request to `/cards/getbypan` to retrieve a card token, which you can then use in your `POST` request to `/cardtransitions`.
It may not be possible to move a card from one user to another once the card has been activated.
Request body
| Fields | Description |
| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| card\_token
string
Required | Identifies the card whose state will transition.
**Allowable Values:**
1–36 chars
Existing `card` token.
Send a `GET` request to `/cards/user/{token}` to retrieve card tokens for a specific user. |
| channel
string
Required | The mechanism by which the transition was initiated.
- **ADMIN** - Indicates that the card transition was initiated through the Marqeta Dashboard.
- **API** - Indicates that the card transition was initiated by you through the Core API. Use this value when creating a card transition with an API `POST` request.
- **FRAUD** - Indicates that either Marqeta or the card network has determined that the card is fraudulent.
- **IVR** - Indicates that the card transition was initiated through your Interactive Voice Response system.
- **SYSTEM** - Indicates that the card transition was initiated by Marqeta. For example, Marqeta suspended the card due to excessive failed personal identification number (PIN) entries.
**Allowable Values:**
`API`, `IVR`, `FRAUD`, `ADMIN`, `SYSTEM` |
| reason
string
Optional | Additional information about the state change.
**Allowable Values:**
255 char max |
| reason\_code
string
Optional | Standard code describing the reason for the transition.
**NOTE:** This field is required if your program uses v2 of the `user_card_state_version`, which is a program-specific configuration value that is managed by Marqeta and cannot be accessed via the API. To learn more about the `user_card_state_version` program configuration, contact your Marqeta representative.
- **00:** Object activated for the first time
- **01:** Requested by you
- **02:** Inactivity over time
- **03:** This address cannot accept mail or the addressee is unknown
- **04:** Negative account balance
- **05:** Account under review
- **06:** Suspicious activity was identified
- **07:** Activity outside the program parameters was identified
- **08:** Confirmed fraud was identified
- **09:** Matched with an Office of Foreign Assets Control list
- **10:** Card was reported lost
- **11:** Card information was cloned
- **12:** Account or card information was compromised
- **13:** Temporary status change while on hold/leave
- **14:** Initiated by Marqeta
- **15:** Initiated by issuer
- **16:** Card expired
- **17:** Failed KYC
- **18:** Changed to `ACTIVE` because information was properly validated
- **19:** Changed to `ACTIVE` because account activity was properly validated
- **20:** Change occurred prior to the normalization of reason codes
- **21:** Initiated by a third party, often a digital wallet provider
- **22:** PIN retry limit reached
- **23:** Card was reported stolen
- **24:** Address issue
- **25:** Name issue
- **26:** SSN issue
- **27:** DOB issue
- **28:** Email issue
- **29:** Phone issue
- **30:** Account/fulfillment mismatch
- **31:** Other reason
- **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 JSON lines wrap theme={null}
{
"token": "activate_05",
"state": "ACTIVE",
"reason": "I want to use this card, so activate it.",
"reason_code": "00",
"channel": "API",
"card_token": "my_user_01_card_01",
"validations": {
"user": {
"birth_date": "1990-01-31T00:00:00Z"
}
}
}
```
Response body
| Fields | Description |
| ----------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| barcode
string
Returned | The barcode printed on the card, expressed as digits.
**Allowable Values:**
10-20 chars |
| bulk\_issuance\_token
string
Conditionally returned | The unique identifier of the bulk card order.
**Allowable Values:**
1-36 chars |
| card
object
Conditionally returned | Associates customer-injected metadata with the card.
**Allowable Values:**
`metadata` |
| card.**metadata**
object
Conditionally returned | Associates customer-injected metadata with the card.
**Allowable Values:**
You can define the names and values of up to 20 fields in the format `"my_name_1": "my_value_1"`. |
| card\_product\_token
string
Returned | Unique identifier of the card product.
**Allowable Values:**
36 char max |
| card\_token
string
Returned | Unique identifier of the card.
**Allowable Values:**
1–36 chars |
| channel
string
Returned | The mechanism by which the transition was initiated.
- **ADMIN** - Indicates that the card transition was initiated through the Marqeta Dashboard.
- **API** - Indicates that the card transition was initiated by you through the Core API. Use this value when creating a card transition with an API `POST` request.
- **FRAUD** - Indicates that either Marqeta or the card network has determined that the card is fraudulent.
- **IVR** - Indicates that the card transition was initiated through your Interactive Voice Response system.
- **SYSTEM** - Indicates that the card transition was initiated by Marqeta. For example, Marqeta suspended the card due to excessive failed personal identification number (PIN) entries.
**Allowable Values:**
`API`, `IVR`, `FRAUD`, `ADMIN`, `SYSTEM` |
| created\_time
datetime
Conditionally returned | Date and time when the resource was created, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| created\_timestamp
datetime
Conditionally returned | Date and time when the resource was created. Expressed in UTC, with millisecond precision.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ss:SSSZ |
| expedite
boolean
Conditionally returned | A value of `true` indicates that you requested expedited processing of the card from your card fulfillment provider.
**Allowable Values:**
`true`, `false` |
| expiration
string
Returned | Expiration date in `MMyy` format.
**Allowable Values:**
Format: MMyy |
| expiration\_time
string
Returned | Expiration date and time in UTC format.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| fulfillment
object
Conditionally returned | Specifies certain physical characteristics of a card, as well as shipment information.
**Allowable Values:**
`card_fulfillment_reason`, `card_personalization`, `shipping` |
| fulfillment.**card\_fulfillment\_reason**
string
Conditionally returned | Reason for card fulfillment.
**Allowable Values:**
`NEW`, `LOST_STOLEN`, `EXPIRED` |
| fulfillment.**card\_personalization**
object
Returned | Specifies personalized attributes to be added to the card.
**Allowable Values:**
`carrier`, `images`, `perso_type`, `text` |
| fulfillment.card\_personalization.**carrier**
object
Conditionally returned | Specifies attributes of the card carrier.
**Allowable Values:**
`logo_file`, `logo_thumbnail_file`, `message_file`, `message_line`, `template_id` |
| fulfillment.card\_personalization.carrier.**logo\_file**
string
Conditionally returned | Specifies an image to display on the card carrier.
**Allowable Values:**
Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
| fulfillment.card\_personalization.carrier.**logo\_thumbnail\_file**
string
Conditionally returned | Specifies a thumbnail-sized rendering of the image specified in the `logo_file` field.
**Allowable Values:**
Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
| fulfillment.card\_personalization.carrier.**message\_file**
string
Conditionally returned | Specifies a text file containing a custom message to print on the card carrier.
**Allowable Values:**
Contains the name of the text file and must match the name of the file you send to your fulfillment provider. |
| fulfillment.card\_personalization.carrier.**message\_line**
string
Conditionally returned | Specifies a custom message that appears on the card carrier.
**Allowable Values:**
60 char max |
| fulfillment.card\_personalization.carrier.**message\_line\_2**
string
Conditionally returned | Specifies the second line of a custom message that appears on the card carrier.
**Allowable Values:**
60 char max |
| fulfillment.card\_personalization.carrier.**template\_id**
string
Conditionally returned | Specifies the card carrier template to use.
**Allowable Values:**
Card carrier template ID |
| fulfillment.card\_personalization.**images**
object
Conditionally returned | Specifies personalized images that appear on the card.
**Allowable Values:**
`card`, `carrier`, `carrier_return_window`, `signature` |
| fulfillment.card\_personalization.images.**card**
object
Conditionally returned | Specifies personalized images that appear on the card.
**Allowable Values:**
`name`, `thermal_color` |
| fulfillment.card\_personalization.images.card.**name**
string
Conditionally returned | Specifies a PNG image to display on the card.
**Allowable Values:**
Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
| fulfillment.card\_personalization.images.card.**thermal\_color**
string
Conditionally returned | Specifies the color of the image displayed on the card.
**Allowable Values:**
Contains the name of the color and must match one of the provider’s predefined colors. |
| fulfillment.card\_personalization.images.**carrier**
object
Conditionally returned | Specifies personalized images that appear on the card carrier.
**Allowable Values:**
`message_1`, `name` |
| fulfillment.card\_personalization.images.carrier.**message\_1**
string
Conditionally returned | Specifies a custom message that appears on the card carrier.
**Allowable Values:**
60 char max |
| fulfillment.card\_personalization.images.carrier.**name**
string
Conditionally returned | Specifies a PNG image to display on the card carrier.
**Allowable Values:**
Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
| fulfillment.card\_personalization.images.**carrier\_return\_window**
object
Conditionally returned | Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders.
**Allowable Values:**
`name` |
| fulfillment.card\_personalization.images.carrier\_return\_window.**name**
string
Conditionally returned | Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders.
**Allowable Values:**
Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
| fulfillment.card\_personalization.images.**signature**
object
Conditionally returned | Specifies a PNG image of the cardholder’s signature.
**Allowable Values:**
`name` |
| fulfillment.card\_personalization.images.signature.**name**
string
Conditionally returned | Specifies a PNG image of the cardholder’s signature.
**Allowable Values:**
Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
| fulfillment.card\_personalization.**perso\_type**
string
Conditionally returned | Specifies the type of card personalization.
**Allowable Values:**
`EMBOSS`, `LASER`, `FLAT` |
| fulfillment.card\_personalization.**text**
object
Returned | Specifies personalized text that appears on the card.
**Allowable Values:**
`name_line_1`, `name_line_2`, `name_line_3` |
| fulfillment.card\_personalization.text.**name\_line\_1**
object
Returned | Specifies the first line of personalized text that appears on the card.
**Allowable Values:**
`name_line_1.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 JSON expandable lines wrap theme={null}
{
"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](/core-api/field-filtering/) and [pagination](/core-api/sorting-and-pagination/).
URL path parameters
| Fields | Description |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| token
string
Required | Unique identifier of the card.
**Allowable Values:**
Existing card token |
URL query parameters
| Fields | Description |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| count
integer
Optional | Number of card transitions to retrieve.
**Allowable Values:**
1-10
**Default value:**
5 |
| start\_index
integer
Optional | Sort order index of the first resource in the returned array.
**Allowable Values:**
Any integer
**Default value:**
0 |
| fields
string
Optional | Comma-delimited list of fields to return (`field_1,field_2`, and so on). Leave blank to return all fields.
**Allowable Values:**
Comma-delimited list of fields, or blank |
| sort\_by
string
Optional | Field on which to sort. Use any field in the resource model, or one of the system fields `lastModifiedTime` or `createdTime`. Prefix the field name with a hyphen (`-`) to sort in descending order. Omit the hyphen to sort in ascending order.
**Allowable Values:**
`createdTime`, `lastModifiedTime`, or any field in the resource model
**Default value:**
`-createdTime` |
Response body
| Fields | Description |
| ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| count
integer
Conditionally returned | Number of resources to retrieve.
This field is returned if there are resources in your returned array.
**Allowable Values:**
1-10 |
| data
array of objects
Conditionally returned | Array of card transition objects.
Objects are returned as appropriate to your query.
**Allowable Values:**
Valid array of one or more card transition objects |
| data\[].**barcode**
string
Returned | The barcode printed on the card, expressed as digits.
**Allowable Values:**
10-20 chars |
| data\[].**bulk\_issuance\_token**
string
Conditionally returned | The unique identifier of the bulk card order.
**Allowable Values:**
1-36 chars |
| data\[].**card**
object
Conditionally returned | Associates customer-injected metadata with the card.
**Allowable Values:**
`metadata` |
| data\[].card.**metadata**
object
Conditionally returned | Associates customer-injected metadata with the card.
**Allowable Values:**
You can define the names and values of up to 20 fields in the format `"my_name_1": "my_value_1"`. |
| data\[].**card\_product\_token**
string
Returned | Unique identifier of the card product.
**Allowable Values:**
36 char max |
| data\[].**card\_token**
string
Returned | Unique identifier of the card.
**Allowable Values:**
1–36 chars |
| data\[].**channel**
string
Returned | The mechanism by which the transition was initiated.
- **ADMIN** - Indicates that the card transition was initiated through the Marqeta Dashboard.
- **API** - Indicates that the card transition was initiated by you through the Core API. Use this value when creating a card transition with an API `POST` request.
- **FRAUD** - Indicates that either Marqeta or the card network has determined that the card is fraudulent.
- **IVR** - Indicates that the card transition was initiated through your Interactive Voice Response system.
- **SYSTEM** - Indicates that the card transition was initiated by Marqeta. For example, Marqeta suspended the card due to excessive failed personal identification number (PIN) entries.
**Allowable Values:**
`API`, `IVR`, `FRAUD`, `ADMIN`, `SYSTEM` |
| data\[].**created\_time**
datetime
Conditionally returned | Date and time when the resource was created, in UTC.
**Allowable Values:**
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 JSON expandable lines wrap theme={null}
{
"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](/core-api/field-filtering/).
URL path parameters
| Fields | Description |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| token
string
Required | Unique identifier of the card transition. Send a `GET` request to `/cardtransitions/card/{token}` to retrieve card transition tokens for a specific card.
**Allowable Values:**
Existing card transition token |
URL query parameters
| Fields | Description |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| fields
string
Optional | Comma-delimited list of fields to return (`field_1,field_2`, and so on). Leave blank to return all fields.
**Allowable Values:**
Comma-delimited list of fields, or blank |
Response body
| Fields | Description |
| ----------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| barcode
string
Returned | The barcode printed on the card, expressed as digits.
**Allowable Values:**
10-20 chars |
| bulk\_issuance\_token
string
Conditionally returned | The unique identifier of the bulk card order.
**Allowable Values:**
1-36 chars |
| card
object
Conditionally returned | Associates customer-injected metadata with the card.
**Allowable Values:**
`metadata` |
| card.**metadata**
object
Conditionally returned | Associates customer-injected metadata with the card.
**Allowable Values:**
You can define the names and values of up to 20 fields in the format `"my_name_1": "my_value_1"`. |
| card\_product\_token
string
Returned | Unique identifier of the card product.
**Allowable Values:**
36 char max |
| card\_token
string
Returned | Unique identifier of the card.
**Allowable Values:**
1–36 chars |
| channel
string
Returned | The mechanism by which the transition was initiated.
- **ADMIN** - Indicates that the card transition was initiated through the Marqeta Dashboard.
- **API** - Indicates that the card transition was initiated by you through the Core API. Use this value when creating a card transition with an API `POST` request.
- **FRAUD** - Indicates that either Marqeta or the card network has determined that the card is fraudulent.
- **IVR** - Indicates that the card transition was initiated through your Interactive Voice Response system.
- **SYSTEM** - Indicates that the card transition was initiated by Marqeta. For example, Marqeta suspended the card due to excessive failed personal identification number (PIN) entries.
**Allowable Values:**
`API`, `IVR`, `FRAUD`, `ADMIN`, `SYSTEM` |
| created\_time
datetime
Conditionally returned | Date and time when the resource was created, in UTC.
**Allowable Values:**
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 JSON expandable lines wrap theme={null}
{
"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"
}
}
}
```