> ## 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.
# Cards
> Use the cards endpoint to create and manage resources that represent physical and virtual payment cards.
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
**Action:** `POST`\
**Endpoint:** `/cards`
{/* */}
Creates a card.
Create the user and card product before you create the card. You create a card using the `user_token` of the user who will own the card and the `card_product_token` of the card product that will control the card.
**Tip**\
By default, newly created cards are inactive and must be explicitly activated (see [Create Card Transition](/core-api/card-transitions/#post_cardtransitions) for information on activating cards). To create cards that are activated upon issue, configure your card product’s `config.card_life_cycle.activate_upon_issue` field (see [Card Products](/core-api/card-products/)).
Send a `POST` request to `/pins/controltoken` to set the card’s personal identification number (PIN) if your program requires PIN numbers (for example, for Europay Mastercard and Visa cards); this action updates the `pin_is_set` field to `true`. See [Create or Update PIN](/core-api/pins/#put_pins) for details.
You can use optional query parameters to show the primary account number (PAN) and card verification value (CVV2) number in the response. If `show_pan` and `show_cvv_number` are set to `true`, the fulfillment state of the card is `DIGITALLY_PRESENTED` instead of the typical initial state of `ISSUED`. This fulfillment state does not affect the delivery of physical cards.
This endpoint requires PCI DSS compliance if `show_pan` and `show_cvv_number` are set to `true`. You must comply with PCI DSS data security requirements if you store, transmit, or process sensitive card data.
URL query parameters
| Fields | Description |
| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| show\_cvv\_number
boolean
Optional | Set to `true` to show the CVV2 number in the response.
**Allowable Values:**
`true`, `false` |
| show\_pan
boolean
Optional | Set to `true` to show the full primary account number (PAN) in the response.
**Allowable Values:**
`true`, `false` |
Request body
| Fields | Description |
| --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| activation\_actions
object
Optional | Defines actions to execute when the card is activated. The fields in this object are mutually exclusive.
**Allowable Values:**
`swap_digital_wallet_tokens_from_card_token`, `terminate_reissued_source_card` |
| activation\_actions.**swap\_digital\_wallet\_tokens\_from\_card\_token**
string
Optional | Moves all digital wallet tokens from the specified card to the new card.
Not relevant when `reissue_pan_from_card_token` is set.
Send a `GET` request to `/cards/user/{token}` to retrieve card tokens for a particular user.
**Allowable Values:**
1–36 chars
Existing card token |
| activation\_actions.**terminate\_reissued\_source\_card**
boolean
Optional | If you are reissuing a card, the source card is terminated by default. To prevent the source card from being terminated, set this field to `false`.
Only relevant when `reissue_pan_from_card_token` is set.
**Allowable Values:**
`true`, `false`
**Default value:**
`true` |
| bulk\_issuance\_token
string
Optional | Associates the card with the specified bulk card order. This field cannot be updated.
**Allowable Values:**
36 char max |
| card\_product\_token
string
Required | Unique identifier of the card product.
**Allowable Values:**
1–36 chars
Existing card product token.
Send a `GET` request to `/cardproducts` to retrieve card product tokens. |
| expedite
boolean
Optional | Set to `true` to request expedited processing of the card by your card fulfillment provider.
This expedited service is available for cards fulfilled by Perfect Plastic Printing, IDEMIA, and Arroweye Solutions.
**NOTE:** Contact your Marqeta representative for information regarding the cost of expedited service.
**Allowable Values:**
`true`, `false`
**Default value:**
`false` |
| expiration\_offset
object
Optional | Specifies the length of time after the date of issue for which the cards are valid.
**Allowable Values:**
`unit`, `value` |
| expiration\_offset.**unit**
string
Optional | Specifies the units for the `value` field in this object.
**Allowable Values:**
`YEARS`, `MONTHS`, `DAYS`, `HOURS`, `MINUTES`, `SECONDS`
**Default value:**
`YEARS` |
| expiration\_offset.**value**
integer
Optional | Specifies the number of time units (as defined by the `unit` field in this object) for which the cards are valid. In other words, cards expire `value` x `unit` after the date of issue.
This number is rounded as follows:
- **YEARS** – Rounds up to the last second of the last day of the month of expiration. For example, if the issue date is 1 Jan 2021 and `value = 1`, the cards expire on the last day of Jan 2022.
- **MONTHS** – Rounds up to the last second of the last day of the month of expiration. For example, if the issue date is 1 May 2022 and `value = 1`, the cards expire on the last day of June 2022.
- **DAYS** – Rounds up to the last second of the day of expiration.
- **HOURS**, **MINUTES**, **SECONDS** – No rounding.
**Allowable Values:**
Any positive integer
**Default value:**
4 |
| fulfillment
object
Optional | 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
Optional | Reason for card fulfillment.
**Allowable Values:**
`NEW`, `LOST_STOLEN`, `EXPIRED` |
| fulfillment.**card\_personalization**
object
Required | Specifies personalized attributes to be added to the card.
**Allowable Values:**
`carrier`, `images`, `perso_type`, `text` |
| fulfillment.card\_personalization.**carrier**
object
Optional | 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
Optional | 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
Optional | 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
Optional | 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
Optional | Specifies a custom message that appears on the card carrier.
**Allowable Values:**
60 char max |
| fulfillment.card\_personalization.carrier.**message\_line\_2**
string
Optional | 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
Optional | Specifies the card carrier template to use.
**Allowable Values:**
Card carrier template ID |
| fulfillment.card\_personalization.**images**
object
Optional | Specifies personalized images that appear on the card.
**Allowable Values:**
`card`, `carrier`, `carrier_return_window`, `signature` |
| fulfillment.card\_personalization.images.**card**
object
Optional | Specifies personalized images that appear on the card.
**Allowable Values:**
`name`, `thermal_color` |
| fulfillment.card\_personalization.images.card.**name**
string
Optional | 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
Optional | 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
Optional | Specifies personalized images that appear on the card carrier.
**Allowable Values:**
`message_1`, `name` |
| fulfillment.card\_personalization.images.carrier.**message\_1**
string
Optional | Specifies a custom message that appears on the card carrier.
**Allowable Values:**
60 char max |
| fulfillment.card\_personalization.images.carrier.**name**
string
Optional | 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
Optional | 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
Optional | 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
Optional | Specifies a PNG image of the cardholder’s signature.
**Allowable Values:**
`name` |
| fulfillment.card\_personalization.images.signature.**name**
string
Optional | 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
Optional | Specifies the type of card personalization.
**Allowable Values:**
`EMBOSS`, `LASER`, `FLAT` |
| fulfillment.card\_personalization.**text**
object
Required | 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
Required | 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
Optional | Line of personalized text printed on the card.
**Allowable Values:**
21 char max |
| fulfillment.card\_personalization.text.**name\_line\_2**
object
Optional | 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
Optional | Line of personalized text printed on the card.
**Allowable Values:**
21 char max |
| fulfillment.card\_personalization.text.**name\_line\_3**
object
Optional | 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
Optional | Line of personalized text printed on the card.
**Allowable Values:**
21 char max |
| fulfillment.**shipping**
object
Optional | Specifies shipping details for the order.
**Allowable Values:**
`care_of_line`, `method`, `recipient_address`, `return_address` |
| fulfillment.shipping.**care\_of\_line**
string
Optional | 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
Optional | 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
Optional | 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
Optional | 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
Optional | 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
Optional | City of the address.
**Allowable Values:**
40 char max |
| fulfillment.shipping.recipient\_address.**country**
string
Optional | 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
Optional | First name of the addressee.
**Allowable Values:**
40 char max |
| fulfillment.shipping.recipient\_address.**last\_name**
string
Optional | Last name of the addressee.
**Allowable Values:**
40 char max |
| fulfillment.shipping.recipient\_address.**middle\_name**
string
Optional | Middle name of the addressee.
**Allowable Values:**
40 char max |
| fulfillment.shipping.recipient\_address.**phone**
string
Optional | Telephone number of the addressee.
**Allowable Values:**
20 char max |
| fulfillment.shipping.recipient\_address.**postal\_code**
string
Optional | Postal code of the address.
**Allowable Values:**
10 char max |
| fulfillment.shipping.recipient\_address.**state**
string
Optional | State of the address.
**Allowable Values:**
32 char max |
| fulfillment.shipping.recipient\_address.**zip**
string
Optional | United States ZIP code of the address.
**Allowable Values:**
10 char max |
| fulfillment.shipping.**return\_address**
object
Optional | 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
Optional | 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
Optional | 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
Optional | City of the address.
**Allowable Values:**
40 char max |
| fulfillment.shipping.return\_address.**country**
string
Optional | 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
Optional | First name of the addressee.
**Allowable Values:**
40 char max |
| fulfillment.shipping.return\_address.**last\_name**
string
Optional | Last name of the addressee.
**Allowable Values:**
40 char max |
| fulfillment.shipping.return\_address.**middle\_name**
string
Optional | Middle name of the addressee.
**Allowable Values:**
40 char max |
| fulfillment.shipping.return\_address.**phone**
string
Optional | Telephone number of the addressee.
**Allowable Values:**
20 char max |
| fulfillment.shipping.return\_address.**postal\_code**
string
Optional | Postal code of the address.
**Allowable Values:**
10 char max |
| fulfillment.shipping.return\_address.**state**
string
Optional | State of the address.
**Allowable Values:**
32 char max |
| fulfillment.shipping.return\_address.**zip**
string
Optional | United States ZIP code of the address.
**Allowable Values:**
10 char max |
| generate\_new\_pan
boolean
Optional | Set to `true` to generate a new PAN when reissuing a card via the `reissue_pan_from_card_token` field.
This field can only be used within the `reissue_pan_from_card_token` re-issuance flow.
**Allowable Values:**
`true`, `false`
**Default value:**
`false` |
| metadata
object
Optional | Associates customer-provided 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"`. |
| reissue\_pan\_from\_card\_token
string
Optional | Reissues the specified card (known as the "source" card).
This field reissues a card by copying the primary account number (PAN) and personal identification number (PIN) from the specified source card to the newly created card. The reissued card has the same PAN and PIN as the source card but a new expiration date and CVV2 number.
If you would like to reissue a card with a new PAN, set `generate_new_pan` to `true`.
Send a `GET` request to `/cards/user/{token}` to retrieve card tokens for a particular user.
**NOTE:** By default, the source card is automatically terminated when the reissued card is activated. However, if your program is configured for multiple active cards, you can prevent the source card from being automatically terminated by setting the `activation_actions.terminate_reissued_source_card` field to `false`.
**Allowable Values:**
36 char max
Existing card token |
| new\_pan\_from\_card\_token
string
Optional | Reissues the specified card (known as the "source" card) with a new primary account number (PAN).
This field reissues a card with a new PAN from the specified source card. The source card is automatically terminated when the card is reissued with the new PAN. Use this field when reissuing a lost or stolen card.
Send a `GET` request to `/cards/user/{token}` to retrieve card tokens for a particular user.
**Allowable Values:**
36 char max
Existing card token |
| token
string
Optional | Unique identifier of the card.
If you do not include a token, the system will generate one automatically. Other API calls will require this token, so we recommend creating a token that is easy to remember rather than letting the system generate one. This value cannot be updated.
**Allowable Values:**
1–36 chars |
| translate\_pin\_from\_card\_token
string
Optional | Copies the PIN from the specified card to the newly created card.
Both cards must belong to the same user. Populating this field will raise an error if `reissue_pan_from_card_token` is also set.
To copy a PIN when reissuing a card, use `copy_pin_from_source_card` instead.
Send a `GET` request to `/cards/user/{token}` to retrieve card tokens for a particular user.
**Allowable Values:**
36 char max
Existing card token |
| copy\_pin\_from\_source\_card
boolean
Optional | Copies the PIN from the source card to the newly reissued card.
If the source card does not have a PIN, the request is processed and the new card is created without a PIN and the `pin_is_set` field is set to `false`.
The reissued card is created without a PIN, regardless whether the source card has one, if `copy_pin_from_source_card` is set to `false` in the card reissue request. This field can only be used with `reissue_pan_from_card_token` or `new_pan_from_card_token` fields. An error is raised if the `translate_pin_from_card_token` field is used in the request.
This field is not returned in the response.
**Allowable Values:**
`true`, `false`
**Default value:**
`true` |
| user\_token
string
Required | Unique identifier of the authorized user of the card.
**Allowable Values:**
1–36 chars
Existing user token
Send a `GET` request to `/users` to retrieve user tokens. |
Sample request body
```json JSON expandable lines wrap theme={null}
{
"token": "my_test_card_01",
"user_token": "my_user_01",
"fulfillment": {
"card_personalization": {
"text": {
"name_line_1": {
"value": "Jane Doe"
},
"name_line_2": {
"value": "My card personalization line 2"
}
},
"images": {
"card": {
"name": "my_card_logo.png",
"thermal_color": "Black"
},
"signature": {
"name": "my_signature.png"
},
"carrier_return_window": {
"name": "my_return_address_image.png"
}
}
}
},
"card_product_token": "my_cardproduct_01",
"metadata": {
"my_name_1": "my_value_1",
"my_name_2": "my_value_2"
}
}
```
Response body
| Fields | Description |
| ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| activation\_actions
object
Conditionally returned | Defines actions to execute when the card is activated. The fields in this object are mutually exclusive.
**Allowable Values:**
`swap_digital_wallet_tokens_from_card_token`, `terminate_reissued_source_card` |
| activation\_actions.**swap\_digital\_wallet\_tokens\_from\_card\_token**
string
Conditionally returned | Moves all digital wallet tokens from the specified card to the new card.
Not relevant when `reissue_pan_from_card_token` is set.
Send a `GET` request to `/cards/user/{token}` to retrieve card tokens for a particular user.
**Allowable Values:**
1–36 chars
Existing card token |
| activation\_actions.**terminate\_reissued\_source\_card**
boolean
Conditionally returned | If you are reissuing a card, the source card is terminated by default. To prevent the source card from being terminated, set this field to `false`.
Only relevant when `reissue_pan_from_card_token` is set.
**Allowable Values:**
`true`, `false`
**Default value:**
`true` |
| barcode
string
Returned | Barcode printed on the card, expressed as numerals.
**Allowable Values:**
10-20 chars |
| bulk\_issuance\_token
string
Conditionally returned | Unique identifier of the bulk card order.
**Allowable Values:**
1-36 chars |
| card\_product\_token
string
Returned | Unique identifier of the card product.
**Allowable Values:**
1-36 chars |
| chip\_cvv\_number
string
Conditionally returned | Three-digit card verification value (ICVV) stored on the chip of the card.
**Allowable Values:**
3 chars |
| contactless\_exemption\_counter
integer
Conditionally returned | Running count of the contactless transactions successfully completed since the last strong customer authentication (SCA) challenge was issued. You can limit the number of contactless transactions that can be performed without issuing an SCA challenge at the card product level.
For more information about strong customer authentication, see Card Products.
**Allowable Values:**
Any integer |
| contactless\_exemption\_total\_amount
decimal
Conditionally returned | Running total of the money spent in contactless transactions successfully completed since the last strong customer authentication (SCA) challenge was issued. You can limit the total amount that can be spent in contactless transactions without issuing an SCA challenge at the card product level.
For more information about strong customer authentication, see Card Products.
**Allowable Values:**
Any integer |
| contactless\_exemption\_transaction\_currency
string
Conditionally returned | Indicates the currency type of the transaction.
**Allowable Values:**
Valid three-character ISO 4217 currency code |
| created\_time
datetime
Returned | Date and time when the resource was created, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| cvv\_number
string
Conditionally returned | Three-digit card verification value (CVV2 or CVC2) printed on the card.
**Allowable Values:**
3 chars |
| 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
datetime
Returned | Expiration date and time, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| fulfillment
object
Conditionally returned | Determines physical characteristics of a card and shipment information.
**Allowable Values:**
`card_fulfillment_reason`, `card_personalization`, `shipping` |
| fulfillment.**card\_fulfillment\_reason**
string
Conditionally returned | Descriptive reason for the 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.
This object is returned if it exists in the resource.
**Allowable Values:**
`care_of_line`, `method`, `recipient_address`, `return_address` |
| fulfillment.shipping.**care\_of\_line**
string
Conditionally returned | Specifies the value of the care of (C/O) line on the mailing carrier.
This field is returned if it exists in the resource.
**Allowable Values:**
255 char max |
| fulfillment.shipping.**method**
string
Conditionally returned | Specifies the shipping service.
This field is returned if it exists in the resource.
**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` |
| fulfillment.shipping.**recipient\_address**
object
Conditionally returned | Address to which the order will be shipped.
This field is returned if it exists in the resource.
**Allowable Values:**
Existing `recipient_address` object |
| fulfillment.shipping.recipient\_address.**address1**
string
Conditionally returned | Number and street of the address.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.recipient\_address.**country**
string
Conditionally returned | Country of the address.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.recipient\_address.**last\_name**
string
Conditionally returned | Last name of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.recipient\_address.**middle\_name**
string
Conditionally returned | Middle name of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.recipient\_address.**phone**
string
Conditionally returned | Telephone number of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
20 char max |
| fulfillment.shipping.recipient\_address.**postal\_code**
string
Conditionally returned | Postal code of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
10 char max |
| fulfillment.shipping.recipient\_address.**state**
string
Conditionally returned | State or province of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
32 char max |
| fulfillment.shipping.recipient\_address.**zip**
string
Conditionally returned | United States ZIP code of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
10 char max |
| fulfillment.shipping.**return\_address**
object
Conditionally returned | Address to which the order will be returned if shipping fails.
This object is returned if it exists in the resource.
**Allowable Values:**
Existing `return_address` object |
| fulfillment.shipping.return\_address.**address1**
string
Conditionally returned | Number and street of the address.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.return\_address.**country**
string
Conditionally returned | Country of the address.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.return\_address.**last\_name**
string
Conditionally returned | Last name of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.return\_address.**middle\_name**
string
Conditionally returned | Middle name of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.return\_address.**phone**
string
Conditionally returned | Telephone number of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
20 char max |
| fulfillment.shipping.return\_address.**postal\_code**
string
Conditionally returned | Postal code of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
10 char max |
| fulfillment.shipping.return\_address.**state**
string
Conditionally returned | State or province of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
32 char max |
| fulfillment.shipping.return\_address.**zip**
string
Conditionally returned | United States ZIP code of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
10 char max |
| fulfillment\_status
string
Returned | Card fulfillment status:
- **ISSUED:** Initial state of all newly created/issued cards.
- **ORDERED:** Card ordered through the card fulfillment provider.
- **REORDERED:** Card reordered through the card fulfillment provider.
- **REJECTED:** Card rejected by the card fulfillment provider.
- **SHIPPED:** Card shipped by the 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`, `REORDERED`, `REJECTED`, `SHIPPED`, `DELIVERED`, `DIGITALLY_PRESENTED` |
| instrument\_type
string
Conditionally returned | Instrument type of the card:
- **PHYSICAL\_MSR:** A physical card with a magnetic stripe. This is the default physical card type.
- **PHYSICAL\_ICC:** A physical card with an integrated circuit, or "chip."
- **PHYSICAL\_CONTACTLESS:** A physical card that uses radio frequency identification (RFID) or near-field communication (NFC) to enable payment over a secure radio interface.
- **PHYSICAL\_COMBO:** A physical card with a chip that also supports contactless payments.
- **VIRTUAL\_PAN:** A virtual card with a primary account number (PAN).
**Allowable Values:**
`PHYSICAL_MSR`, `PHYSICAL_ICC`, `PHYSICAL_CONTACTLESS`, `PHYSICAL_COMBO`, `VIRTUAL_PAN` |
| last\_four
string
Returned | Last four digits of the card primary account number (PAN).
**Allowable Values:**
4 chars |
| last\_modified\_time
datetime
Returned | Date and time when the resource was last modified, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| metadata
object
Conditionally returned | Associates customer-provided metadata with the card.
**Allowable Values:**
Contains the names and values of up to 20 fields in the format `"my_name_1": "my_value_1"` |
| 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 |
| reissue\_pan\_from\_card\_token
string
Conditionally returned | Reissues the specified card (known as the "source" card).
**Allowable Values:**
Existing card token |
| new\_pan\_from\_card\_token
string
Conditionally returned | Reissues the specified card (known as the "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`, `UNSUPPORTED`, `UNACTIVATED`, `LIMITED` |
| state\_reason
string
Returned | Descriptive reason for why the card is in its current state. For example, "Card activated by cardholder".
**Allowable Values:**
255 char max |
| token
string
Returned | Unique identifier of the card.
**Allowable Values:**
Existing card token |
| translate\_pin\_from\_card\_token
string
Conditionally returned | Copies the personal identification number (PIN) from the specified source card to the newly created card.
**Allowable Values:**
Existing card token |
| user\_token
string
Returned | Unique identifier of the cardholder.
**Allowable Values:**
Existing user token |
Sample response body
```json JSON expandable lines wrap theme={null}
{
"created_time": "2022-02-26T20:40:04Z",
"last_modified_time": "2022-02-26T20:40:04Z",
"token": "my_test_card_01",
"user_token": "my_user_01",
"card_product_token": "my_cardproduct_01",
"last_four": "6270",
"pan": "1111111824986720",
"expiration": "0331",
"expiration_time": "2027-03-31T23:59:59Z",
"barcode": "51554698491331520446",
"pin_is_set": false,
"state": "ACTIVE",
"state_reason": "New card activated",
"fulfillment_status": "ISSUED",
"fulfillment": {
"card_personalization": {
"text": {
"name_line_1": {
"value": "Jane Doe"
},
"name_line_2": {
"value": "My card personalization line 2"
}
},
"images": {
"card": {
"name": "my_card_logo.png",
"thermal_color": "Black"
},
"signature": {
"name": "my_signature.png"
},
"carrier_return_window": {
"name": "my_return_address_image.png"
}
}
}
},
"instrument_type": "PHYSICAL_MSR",
"expedite": false,
"metadata": {
"my_name_1": "my_value_1",
"my_name_2": "my_value_2"
}
}
```
List cards by last 4 digits of PAN
**Action:** `GET`\
**Endpoint:** `/cards`
{/* */}
Retrieves an array of cards whose primary account numbers (PANs) end in the four digits specified by the `last_four` query parameter.
This endpoint supports [field filtering](/core-api/field-filtering/), [object expansion](/core-api/object-expansion/), [sorting, and pagination](/core-api/sorting-and-pagination/).
URL query parameters
| Fields | Description |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| count
integer
Optional | Number of resources 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 |
| last\_four
string
Required | Last four digits of the primary account number (PAN) of the card you want to locate.
**Allowable Values:**
4 chars |
| 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 | 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:**
`-lastModifiedTime` |
Response body
| Fields | Description |
| ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| count
integer
Conditionally returned | The number of resources retrieved.
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 objects.
Objects are returned as appropriate to your query.
**Allowable Values:**
Valid array of one or more card objects |
| data\[].**activation\_actions**
object
Conditionally returned | Defines actions to execute when the card is activated. The fields in this object are mutually exclusive.
**Allowable Values:**
`swap_digital_wallet_tokens_from_card_token`, `terminate_reissued_source_card` |
| data\[].activation\_actions.**swap\_digital\_wallet\_tokens\_from\_card\_token**
string
Conditionally returned | Moves all digital wallet tokens from the specified card to the new card.
Not relevant when `reissue_pan_from_card_token` is set.
Send a `GET` request to `/cards/user/{token}` to retrieve card tokens for a particular user.
**Allowable Values:**
1–36 chars
Existing card token |
| data\[].activation\_actions.**terminate\_reissued\_source\_card**
boolean
Conditionally returned | If you are reissuing a card, the source card is terminated by default. To prevent the source card from being terminated, set this field to `false`.
Only relevant when `reissue_pan_from_card_token` is set.
**Allowable Values:**
`true`, `false`
**Default value:**
`true` |
| data\[].**barcode**
string
Returned | Barcode printed on the card, expressed as numerals.
**Allowable Values:**
10-20 chars |
| data\[].**bulk\_issuance\_token**
string
Conditionally returned | Unique identifier of the bulk card order.
**Allowable Values:**
1-36 chars |
| data\[].**card\_product\_token**
string
Returned | Unique identifier of the card product.
**Allowable Values:**
1-36 chars |
| data\[].**chip\_cvv\_number**
string
Conditionally returned | Three-digit card verification value (ICVV) stored on the chip of the card.
**Allowable Values:**
3 chars |
| data\[].**contactless\_exemption\_counter**
integer
Conditionally returned | Running count of the contactless transactions successfully completed since the last strong customer authentication (SCA) challenge was issued. You can limit the number of contactless transactions that can be performed without issuing an SCA challenge at the card product level.
For more information about strong customer authentication, see Card Products.
**Allowable Values:**
Any integer |
| data\[].**contactless\_exemption\_total\_amount**
decimal
Conditionally returned | Running total of the money spent in contactless transactions successfully completed since the last strong customer authentication (SCA) challenge was issued. You can limit the total amount that can be spent in contactless transactions without issuing an SCA challenge at the card product level.
For more information about strong customer authentication, see Card Products.
**Allowable Values:**
Any integer |
| data\[].**contactless\_exemption\_transaction\_currency**
string
Conditionally returned | Indicates the currency type of the transaction.
**Allowable Values:**
Valid three-character ISO 4217 currency code |
| data\[].**created\_time**
datetime
Returned | Date and time when the resource was created, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| data\[].**cvv\_number**
string
Conditionally returned | Three-digit card verification value (CVV2 or CVC2) printed on the card.
**Allowable Values:**
3 chars |
| 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**
datetime
Returned | Expiration date and time, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| data\[].**fulfillment**
object
Conditionally returned | Determines physical characteristics of a card and shipment information.
**Allowable Values:**
`card_fulfillment_reason`, `card_personalization`, `shipping` |
| data\[].fulfillment.**card\_fulfillment\_reason**
string
Conditionally returned | Descriptive reason for the 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.
This object is returned if it exists in the resource.
**Allowable Values:**
`care_of_line`, `method`, `recipient_address`, `return_address` |
| data\[].fulfillment.shipping.**care\_of\_line**
string
Conditionally returned | Specifies the value of the care of (C/O) line on the mailing carrier.
This field is returned if it exists in the resource.
**Allowable Values:**
255 char max |
| data\[].fulfillment.shipping.**method**
string
Conditionally returned | Specifies the shipping service.
This field is returned if it exists in the resource.
**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` |
| data\[].fulfillment.shipping.**recipient\_address**
object
Conditionally returned | Address to which the order will be shipped.
This field is returned if it exists in the resource.
**Allowable Values:**
Existing `recipient_address` object |
| data\[].fulfillment.shipping.recipient\_address.**address1**
string
Conditionally returned | Number and street of the address.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| data\[].fulfillment.shipping.recipient\_address.**country**
string
Conditionally returned | Country of the address.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| data\[].fulfillment.shipping.recipient\_address.**last\_name**
string
Conditionally returned | Last name of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| data\[].fulfillment.shipping.recipient\_address.**middle\_name**
string
Conditionally returned | Middle name of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| data\[].fulfillment.shipping.recipient\_address.**phone**
string
Conditionally returned | Telephone number of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
20 char max |
| data\[].fulfillment.shipping.recipient\_address.**postal\_code**
string
Conditionally returned | Postal code of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
10 char max |
| data\[].fulfillment.shipping.recipient\_address.**state**
string
Conditionally returned | State or province of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
32 char max |
| data\[].fulfillment.shipping.recipient\_address.**zip**
string
Conditionally returned | United States ZIP code of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
10 char max |
| data\[].fulfillment.shipping.**return\_address**
object
Conditionally returned | Address to which the order will be returned if shipping fails.
This object is returned if it exists in the resource.
**Allowable Values:**
Existing `return_address` object |
| data\[].fulfillment.shipping.return\_address.**address1**
string
Conditionally returned | Number and street of the address.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| data\[].fulfillment.shipping.return\_address.**country**
string
Conditionally returned | Country of the address.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| data\[].fulfillment.shipping.return\_address.**last\_name**
string
Conditionally returned | Last name of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| data\[].fulfillment.shipping.return\_address.**middle\_name**
string
Conditionally returned | Middle name of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| data\[].fulfillment.shipping.return\_address.**phone**
string
Conditionally returned | Telephone number of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
20 char max |
| data\[].fulfillment.shipping.return\_address.**postal\_code**
string
Conditionally returned | Postal code of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
10 char max |
| data\[].fulfillment.shipping.return\_address.**state**
string
Conditionally returned | State or province of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
32 char max |
| data\[].fulfillment.shipping.return\_address.**zip**
string
Conditionally returned | United States ZIP code of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
10 char max |
| data\[].**fulfillment\_status**
string
Returned | Card fulfillment status:
- **ISSUED:** Initial state of all newly created/issued cards.
- **ORDERED:** Card ordered through the card fulfillment provider.
- **REORDERED:** Card reordered through the card fulfillment provider.
- **REJECTED:** Card rejected by the card fulfillment provider.
- **SHIPPED:** Card shipped by the 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`, `REORDERED`, `REJECTED`, `SHIPPED`, `DELIVERED`, `DIGITALLY_PRESENTED` |
| data\[].**instrument\_type**
string
Conditionally returned | Instrument type of the card:
- **PHYSICAL\_MSR:** A physical card with a magnetic stripe. This is the default physical card type.
- **PHYSICAL\_ICC:** A physical card with an integrated circuit, or "chip."
- **PHYSICAL\_CONTACTLESS:** A physical card that uses radio frequency identification (RFID) or near-field communication (NFC) to enable payment over a secure radio interface.
- **PHYSICAL\_COMBO:** A physical card with a chip that also supports contactless payments.
- **VIRTUAL\_PAN:** A virtual card with a primary account number (PAN).
**Allowable Values:**
`PHYSICAL_MSR`, `PHYSICAL_ICC`, `PHYSICAL_CONTACTLESS`, `PHYSICAL_COMBO`, `VIRTUAL_PAN` |
| data\[].**last\_four**
string
Returned | Last four digits of the card primary account number (PAN).
**Allowable Values:**
4 chars |
| data\[].**last\_modified\_time**
datetime
Returned | Date and time when the resource was last modified, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| data\[].**metadata**
object
Conditionally returned | Associates customer-provided metadata with the card.
**Allowable Values:**
Contains the names and values of up to 20 fields in the format `"my_name_1": "my_value_1"` |
| 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\[].**reissue\_pan\_from\_card\_token**
string
Conditionally returned | Reissues the specified card (known as the "source" card).
**Allowable Values:**
Existing card token |
| data\[].**new\_pan\_from\_card\_token**
string
Conditionally returned | Reissues the specified card (known as the "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`, `UNSUPPORTED`, `UNACTIVATED`, `LIMITED` |
| data\[].**state\_reason**
string
Returned | Descriptive reason for why the card is in its current state. For example, "Card activated by cardholder".
**Allowable Values:**
255 char max |
| data\[].**token**
string
Returned | Unique identifier of the card.
**Allowable Values:**
Existing card token |
| data\[].**translate\_pin\_from\_card\_token**
string
Conditionally returned | Copies the personal identification number (PIN) from the specified source card to the newly created card.
**Allowable Values:**
Existing card token |
| data\[].**user\_token**
string
Returned | Unique identifier of the cardholder.
**Allowable Values:**
Existing user token |
| 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": 1,
"start_index": 0,
"end_index": 0,
"is_more": false,
"data": [
{
"created_time": "2022-02-08T18:31:23Z",
"last_modified_time": "2022-02-14T19:32:38Z",
"token": "my_user_01_card_02",
"user_token": "my_user_01",
"card_product_token": "my_cardproduct_01",
"last_four": "1865",
"pan": "1111111824981865",
"expiration": "1225",
"expiration_time": "2027-12-31T23:59:59Z",
"barcode": "25815105237561780909",
"pin_is_set": false,
"state": "UNACTIVATED",
"state_reason": "New card",
"expedite": false,
"fulfillment_status": "DIGITALLY_PRESENTED",
"fulfillment": {
"shipping": {
"method": "FEDEX_REGULAR",
"care_of_line": "my_care_of_value"
},
"card_personalization": {
"text": {
"name_line_1": {
"value": "My card personalization line 1"
},
"name_line_2": {
"value": "My card personalization line 2"
}
},
"images": {
"card": {
"name": "my_card_logo.png",
"thermal_color": "Black"
},
"signature": {
"name": "my_signature.png"
},
"carrier_return_window": {
"name": "my_return_address_image.png"
}
}
}
},
"instrument_type": "PHYSICAL_MSR"
}
]
}
```
Retrieve card by barcode
**Action:** `GET`\
**Endpoint:** `/cards/barcode/{barcode}`
{/* */}
Retrieves a card by its barcode.
This endpoint supports [field filtering](/core-api/field-filtering/) and [object expansion](/core-api/object-expansion/).
URL path parameters
| Fields | Description |
| --------------------------------------------- | ---------------------------------------------------------------------------------------- |
| barcode
string
Required | Barcode of the card to retrieve.
**Allowable Values:**
10-20 chars |
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 |
| ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| activation\_actions
object
Conditionally returned | Defines actions to execute when the card is activated. The fields in this object are mutually exclusive.
**Allowable Values:**
`swap_digital_wallet_tokens_from_card_token`, `terminate_reissued_source_card` |
| activation\_actions.**swap\_digital\_wallet\_tokens\_from\_card\_token**
string
Conditionally returned | Moves all digital wallet tokens from the specified card to the new card.
Not relevant when `reissue_pan_from_card_token` is set.
Send a `GET` request to `/cards/user/{token}` to retrieve card tokens for a particular user.
**Allowable Values:**
1–36 chars
Existing card token |
| activation\_actions.**terminate\_reissued\_source\_card**
boolean
Conditionally returned | If you are reissuing a card, the source card is terminated by default. To prevent the source card from being terminated, set this field to `false`.
Only relevant when `reissue_pan_from_card_token` is set.
**Allowable Values:**
`true`, `false`
**Default value:**
`true` |
| barcode
string
Returned | Barcode printed on the card, expressed as numerals.
**Allowable Values:**
10-20 chars |
| bulk\_issuance\_token
string
Conditionally returned | Unique identifier of the bulk card order.
**Allowable Values:**
1-36 chars |
| card\_product\_token
string
Returned | Unique identifier of the card product.
**Allowable Values:**
1-36 chars |
| chip\_cvv\_number
string
Conditionally returned | Three-digit card verification value (ICVV) stored on the chip of the card.
**Allowable Values:**
3 chars |
| contactless\_exemption\_counter
integer
Conditionally returned | Running count of the contactless transactions successfully completed since the last strong customer authentication (SCA) challenge was issued. You can limit the number of contactless transactions that can be performed without issuing an SCA challenge at the card product level.
For more information about strong customer authentication, see Card Products.
**Allowable Values:**
Any integer |
| contactless\_exemption\_total\_amount
decimal
Conditionally returned | Running total of the money spent in contactless transactions successfully completed since the last strong customer authentication (SCA) challenge was issued. You can limit the total amount that can be spent in contactless transactions without issuing an SCA challenge at the card product level.
For more information about strong customer authentication, see Card Products.
**Allowable Values:**
Any integer |
| contactless\_exemption\_transaction\_currency
string
Conditionally returned | Indicates the currency type of the transaction.
**Allowable Values:**
Valid three-character ISO 4217 currency code |
| created\_time
datetime
Returned | Date and time when the resource was created, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| cvv\_number
string
Conditionally returned | Three-digit card verification value (CVV2 or CVC2) printed on the card.
**Allowable Values:**
3 chars |
| 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
datetime
Returned | Expiration date and time, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| fulfillment
object
Conditionally returned | Determines physical characteristics of a card and shipment information.
**Allowable Values:**
`card_fulfillment_reason`, `card_personalization`, `shipping` |
| fulfillment.**card\_fulfillment\_reason**
string
Conditionally returned | Descriptive reason for the 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.
This object is returned if it exists in the resource.
**Allowable Values:**
`care_of_line`, `method`, `recipient_address`, `return_address` |
| fulfillment.shipping.**care\_of\_line**
string
Conditionally returned | Specifies the value of the care of (C/O) line on the mailing carrier.
This field is returned if it exists in the resource.
**Allowable Values:**
255 char max |
| fulfillment.shipping.**method**
string
Conditionally returned | Specifies the shipping service.
This field is returned if it exists in the resource.
**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` |
| fulfillment.shipping.**recipient\_address**
object
Conditionally returned | Address to which the order will be shipped.
This field is returned if it exists in the resource.
**Allowable Values:**
Existing `recipient_address` object |
| fulfillment.shipping.recipient\_address.**address1**
string
Conditionally returned | Number and street of the address.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.recipient\_address.**country**
string
Conditionally returned | Country of the address.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.recipient\_address.**last\_name**
string
Conditionally returned | Last name of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.recipient\_address.**middle\_name**
string
Conditionally returned | Middle name of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.recipient\_address.**phone**
string
Conditionally returned | Telephone number of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
20 char max |
| fulfillment.shipping.recipient\_address.**postal\_code**
string
Conditionally returned | Postal code of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
10 char max |
| fulfillment.shipping.recipient\_address.**state**
string
Conditionally returned | State or province of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
32 char max |
| fulfillment.shipping.recipient\_address.**zip**
string
Conditionally returned | United States ZIP code of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
10 char max |
| fulfillment.shipping.**return\_address**
object
Conditionally returned | Address to which the order will be returned if shipping fails.
This object is returned if it exists in the resource.
**Allowable Values:**
Existing `return_address` object |
| fulfillment.shipping.return\_address.**address1**
string
Conditionally returned | Number and street of the address.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.return\_address.**country**
string
Conditionally returned | Country of the address.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.return\_address.**last\_name**
string
Conditionally returned | Last name of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.return\_address.**middle\_name**
string
Conditionally returned | Middle name of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.return\_address.**phone**
string
Conditionally returned | Telephone number of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
20 char max |
| fulfillment.shipping.return\_address.**postal\_code**
string
Conditionally returned | Postal code of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
10 char max |
| fulfillment.shipping.return\_address.**state**
string
Conditionally returned | State or province of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
32 char max |
| fulfillment.shipping.return\_address.**zip**
string
Conditionally returned | United States ZIP code of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
10 char max |
| fulfillment\_status
string
Returned | Card fulfillment status:
- **ISSUED:** Initial state of all newly created/issued cards.
- **ORDERED:** Card ordered through the card fulfillment provider.
- **REORDERED:** Card reordered through the card fulfillment provider.
- **REJECTED:** Card rejected by the card fulfillment provider.
- **SHIPPED:** Card shipped by the 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`, `REORDERED`, `REJECTED`, `SHIPPED`, `DELIVERED`, `DIGITALLY_PRESENTED` |
| instrument\_type
string
Conditionally returned | Instrument type of the card:
- **PHYSICAL\_MSR:** A physical card with a magnetic stripe. This is the default physical card type.
- **PHYSICAL\_ICC:** A physical card with an integrated circuit, or "chip."
- **PHYSICAL\_CONTACTLESS:** A physical card that uses radio frequency identification (RFID) or near-field communication (NFC) to enable payment over a secure radio interface.
- **PHYSICAL\_COMBO:** A physical card with a chip that also supports contactless payments.
- **VIRTUAL\_PAN:** A virtual card with a primary account number (PAN).
**Allowable Values:**
`PHYSICAL_MSR`, `PHYSICAL_ICC`, `PHYSICAL_CONTACTLESS`, `PHYSICAL_COMBO`, `VIRTUAL_PAN` |
| last\_four
string
Returned | Last four digits of the card primary account number (PAN).
**Allowable Values:**
4 chars |
| last\_modified\_time
datetime
Returned | Date and time when the resource was last modified, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| metadata
object
Conditionally returned | Associates customer-provided metadata with the card.
**Allowable Values:**
Contains the names and values of up to 20 fields in the format `"my_name_1": "my_value_1"` |
| 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 |
| reissue\_pan\_from\_card\_token
string
Conditionally returned | Reissues the specified card (known as the "source" card).
**Allowable Values:**
Existing card token |
| new\_pan\_from\_card\_token
string
Conditionally returned | Reissues the specified card (known as the "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`, `UNSUPPORTED`, `UNACTIVATED`, `LIMITED` |
| state\_reason
string
Returned | Descriptive reason for why the card is in its current state. For example, "Card activated by cardholder".
**Allowable Values:**
255 char max |
| token
string
Returned | Unique identifier of the card.
**Allowable Values:**
Existing card token |
| translate\_pin\_from\_card\_token
string
Conditionally returned | Copies the personal identification number (PIN) from the specified source card to the newly created card.
**Allowable Values:**
Existing card token |
| user\_token
string
Returned | Unique identifier of the cardholder.
**Allowable Values:**
Existing user token |
Sample response body
```json JSON lines wrap theme={null}
{
"token": "my_card",
"pan": "5454545454545454",
"expiration": "0216",
"barcode": "780672318863",
"state": "ACTIVE",
"state_reason": "New card activated",
"user_token": "my_user_01",
"card_product_token": "my_cardproduct_01",
"last_four": "5454",
"expiration_time": "2027-02-28T23:59:59Z",
"pin_is_set": false,
"expedite": false,
"fulfillment_status": "SHIPPED",
"instrument_type": "PHYSICAL_MSR",
"created_time": "2022-02-28T18:31:23Z",
"last_modified_time": "2022-02-28T18:41:00Z"
}
```
Retrieve card by PAN
**Action:** `POST`\
**Endpoint:** `/cards/getbypan`
{/* */}
Retrieves the `user_token` and `card_token` for a primary account number (PAN). In the case of a reissued card, where multiple cards share the same PAN, the information for the most recently issued card is returned.
This request is useful in IVR scenarios where a user has telephoned and identifies the card by the PAN. The retrieval of these tokens is implemented as a `POST` request because supplying the PAN in the request body is more secure than supplying it in the URL (as would be required with a `GET`).
**Warning**\
Sending a request to this endpoint requires PCI DSS compliance. You must comply with PCI DSS data security requirements if you want to store, transmit, or process sensitive card data such as the cardholder’s primary account number (PAN), personal identification number (PIN), and card expiration date.
Request body
| Fields | Description |
| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| cvv\_number
string
Optional | Three-digit card verification value (CVV2) included on the back of the card.
This value cannot be updated.
**Allowable Values:**
3 char max |
| expiration
string
Optional | Card expiration date.
**Allowable Values:**
Format: MMyy |
| pan
string
Required | Primary account number (PAN) of the card whose information you want to retrieve.
Send a `GET` request to `/cards/{token}/showpan` to retrieve the PAN for a specific card.
**Allowable Values:**
16 char max |
Sample request body
```json JSON lines wrap theme={null}
{
"pan": "5454545454545454"
}
```
Response body
| Fields | Description |
| ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| card\_token
string
Returned | Unique identifier of the card.
**Allowable Values:**
Existing card token |
| created\_time
datetime
Returned | Date and time when the resource was created, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| last\_modified\_time
datetime
Returned | Date and time when the resource was last modified, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| user\_token
string
Returned | Unique identifier of the cardholder.
**Allowable Values:**
Existing user token |
Sample response body
```json JSON lines wrap theme={null}
{
"user_token": "my_user",
"card_token": "my_card1",
"created_time": "2022-02-26T20:03:15Z",
"last_modified_time": "2022-02-26T20:05:20Z"
}
```
List cards for user
**Action:** `GET`\
**Endpoint:** `/cards/user/{token}`
{/* */}
Retrieves a list of the cards associated with a specific user.
This endpoint supports [field filtering,](/core-api/field-filtering/) [pagination](/core-api/sorting-and-pagination/), and [object expansion](/core-api/object-expansion/).
URL path parameters
| Fields | Description |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| token
string
Required | Unique identifier of the user whose cards you want to list. Send a `GET` request to `/users` to retrieve user tokens.
**Allowable Values:**
Existing user token |
URL query parameters
| Fields | Description |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| count
integer
Optional | Number of resources 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 | 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:**
`-lastModifiedTime` |
Response body
| Fields | Description |
| ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| count
integer
Conditionally returned | The number of resources retrieved.
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 objects.
Objects are returned as appropriate to your query.
**Allowable Values:**
Valid array of one or more card objects |
| data\[].**activation\_actions**
object
Conditionally returned | Defines actions to execute when the card is activated. The fields in this object are mutually exclusive.
**Allowable Values:**
`swap_digital_wallet_tokens_from_card_token`, `terminate_reissued_source_card` |
| data\[].activation\_actions.**swap\_digital\_wallet\_tokens\_from\_card\_token**
string
Conditionally returned | Moves all digital wallet tokens from the specified card to the new card.
Not relevant when `reissue_pan_from_card_token` is set.
Send a `GET` request to `/cards/user/{token}` to retrieve card tokens for a particular user.
**Allowable Values:**
1–36 chars
Existing card token |
| data\[].activation\_actions.**terminate\_reissued\_source\_card**
boolean
Conditionally returned | If you are reissuing a card, the source card is terminated by default. To prevent the source card from being terminated, set this field to `false`.
Only relevant when `reissue_pan_from_card_token` is set.
**Allowable Values:**
`true`, `false`
**Default value:**
`true` |
| data\[].**barcode**
string
Returned | Barcode printed on the card, expressed as numerals.
**Allowable Values:**
10-20 chars |
| data\[].**bulk\_issuance\_token**
string
Conditionally returned | Unique identifier of the bulk card order.
**Allowable Values:**
1-36 chars |
| data\[].**card\_product\_token**
string
Returned | Unique identifier of the card product.
**Allowable Values:**
1-36 chars |
| data\[].**chip\_cvv\_number**
string
Conditionally returned | Three-digit card verification value (ICVV) stored on the chip of the card.
**Allowable Values:**
3 chars |
| data\[].**contactless\_exemption\_counter**
integer
Conditionally returned | Running count of the contactless transactions successfully completed since the last strong customer authentication (SCA) challenge was issued. You can limit the number of contactless transactions that can be performed without issuing an SCA challenge at the card product level.
For more information about strong customer authentication, see Card Products.
**Allowable Values:**
Any integer |
| data\[].**contactless\_exemption\_total\_amount**
decimal
Conditionally returned | Running total of the money spent in contactless transactions successfully completed since the last strong customer authentication (SCA) challenge was issued. You can limit the total amount that can be spent in contactless transactions without issuing an SCA challenge at the card product level.
For more information about strong customer authentication, see Card Products.
**Allowable Values:**
Any integer |
| data\[].**contactless\_exemption\_transaction\_currency**
string
Conditionally returned | Indicates the currency type of the transaction.
**Allowable Values:**
Valid three-character ISO 4217 currency code |
| data\[].**created\_time**
datetime
Returned | Date and time when the resource was created, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| data\[].**cvv\_number**
string
Conditionally returned | Three-digit card verification value (CVV2 or CVC2) printed on the card.
**Allowable Values:**
3 chars |
| 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**
datetime
Returned | Expiration date and time, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| data\[].**fulfillment**
object
Conditionally returned | Determines physical characteristics of a card and shipment information.
**Allowable Values:**
`card_fulfillment_reason`, `card_personalization`, `shipping` |
| data\[].fulfillment.**card\_fulfillment\_reason**
string
Conditionally returned | Descriptive reason for the 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.
This object is returned if it exists in the resource.
**Allowable Values:**
`care_of_line`, `method`, `recipient_address`, `return_address` |
| data\[].fulfillment.shipping.**care\_of\_line**
string
Conditionally returned | Specifies the value of the care of (C/O) line on the mailing carrier.
This field is returned if it exists in the resource.
**Allowable Values:**
255 char max |
| data\[].fulfillment.shipping.**method**
string
Conditionally returned | Specifies the shipping service.
This field is returned if it exists in the resource.
**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` |
| data\[].fulfillment.shipping.**recipient\_address**
object
Conditionally returned | Address to which the order will be shipped.
This field is returned if it exists in the resource.
**Allowable Values:**
Existing `recipient_address` object |
| data\[].fulfillment.shipping.recipient\_address.**address1**
string
Conditionally returned | Number and street of the address.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| data\[].fulfillment.shipping.recipient\_address.**country**
string
Conditionally returned | Country of the address.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| data\[].fulfillment.shipping.recipient\_address.**last\_name**
string
Conditionally returned | Last name of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| data\[].fulfillment.shipping.recipient\_address.**middle\_name**
string
Conditionally returned | Middle name of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| data\[].fulfillment.shipping.recipient\_address.**phone**
string
Conditionally returned | Telephone number of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
20 char max |
| data\[].fulfillment.shipping.recipient\_address.**postal\_code**
string
Conditionally returned | Postal code of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
10 char max |
| data\[].fulfillment.shipping.recipient\_address.**state**
string
Conditionally returned | State or province of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
32 char max |
| data\[].fulfillment.shipping.recipient\_address.**zip**
string
Conditionally returned | United States ZIP code of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
10 char max |
| data\[].fulfillment.shipping.**return\_address**
object
Conditionally returned | Address to which the order will be returned if shipping fails.
This object is returned if it exists in the resource.
**Allowable Values:**
Existing `return_address` object |
| data\[].fulfillment.shipping.return\_address.**address1**
string
Conditionally returned | Number and street of the address.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| data\[].fulfillment.shipping.return\_address.**country**
string
Conditionally returned | Country of the address.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| data\[].fulfillment.shipping.return\_address.**last\_name**
string
Conditionally returned | Last name of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| data\[].fulfillment.shipping.return\_address.**middle\_name**
string
Conditionally returned | Middle name of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| data\[].fulfillment.shipping.return\_address.**phone**
string
Conditionally returned | Telephone number of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
20 char max |
| data\[].fulfillment.shipping.return\_address.**postal\_code**
string
Conditionally returned | Postal code of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
10 char max |
| data\[].fulfillment.shipping.return\_address.**state**
string
Conditionally returned | State or province of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
32 char max |
| data\[].fulfillment.shipping.return\_address.**zip**
string
Conditionally returned | United States ZIP code of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
10 char max |
| data\[].**fulfillment\_status**
string
Returned | Card fulfillment status:
- **ISSUED:** Initial state of all newly created/issued cards.
- **ORDERED:** Card ordered through the card fulfillment provider.
- **REORDERED:** Card reordered through the card fulfillment provider.
- **REJECTED:** Card rejected by the card fulfillment provider.
- **SHIPPED:** Card shipped by the 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`, `REORDERED`, `REJECTED`, `SHIPPED`, `DELIVERED`, `DIGITALLY_PRESENTED` |
| data\[].**instrument\_type**
string
Conditionally returned | Instrument type of the card:
- **PHYSICAL\_MSR:** A physical card with a magnetic stripe. This is the default physical card type.
- **PHYSICAL\_ICC:** A physical card with an integrated circuit, or "chip."
- **PHYSICAL\_CONTACTLESS:** A physical card that uses radio frequency identification (RFID) or near-field communication (NFC) to enable payment over a secure radio interface.
- **PHYSICAL\_COMBO:** A physical card with a chip that also supports contactless payments.
- **VIRTUAL\_PAN:** A virtual card with a primary account number (PAN).
**Allowable Values:**
`PHYSICAL_MSR`, `PHYSICAL_ICC`, `PHYSICAL_CONTACTLESS`, `PHYSICAL_COMBO`, `VIRTUAL_PAN` |
| data\[].**last\_four**
string
Returned | Last four digits of the card primary account number (PAN).
**Allowable Values:**
4 chars |
| data\[].**last\_modified\_time**
datetime
Returned | Date and time when the resource was last modified, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| data\[].**metadata**
object
Conditionally returned | Associates customer-provided metadata with the card.
**Allowable Values:**
Contains the names and values of up to 20 fields in the format `"my_name_1": "my_value_1"` |
| 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\[].**reissue\_pan\_from\_card\_token**
string
Conditionally returned | Reissues the specified card (known as the "source" card).
**Allowable Values:**
Existing card token |
| data\[].**new\_pan\_from\_card\_token**
string
Conditionally returned | Reissues the specified card (known as the "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`, `UNSUPPORTED`, `UNACTIVATED`, `LIMITED` |
| data\[].**state\_reason**
string
Returned | Descriptive reason for why the card is in its current state. For example, "Card activated by cardholder".
**Allowable Values:**
255 char max |
| data\[].**token**
string
Returned | Unique identifier of the card.
**Allowable Values:**
Existing card token |
| data\[].**translate\_pin\_from\_card\_token**
string
Conditionally returned | Copies the personal identification number (PIN) from the specified source card to the newly created card.
**Allowable Values:**
Existing card token |
| data\[].**user\_token**
string
Returned | Unique identifier of the cardholder.
**Allowable Values:**
Existing user token |
| 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": 3,
"start_index": 0,
"end_index": 2,
"is_more": false,
"data": [
{
"created_time": "2022-02-24T21:23:31Z",
"last_modified_time": "2022-02-26T19:55:09Z",
"token": "my_user_01_card_01",
"user_token": "my_user_01",
"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,
"state": "SUSPENDED",
"state_reason": "I do not want to use this card, so suspend it.",
"expedite": false,
"fulfillment_status": "ISSUED",
"instrument_type": "PHYSICAL_MSR"
},
{
"created_time": "2021-12-28T18:31:23Z",
"last_modified_time": "2021-12-28T18:36:23Z",
"token": "my_user_01_card_02",
"user_token": "my_user_01",
"card_product_token": "my_cardproduct_01",
"last_four": "1865",
"pan": "1111111824981865",
"expiration": "1220",
"expiration_time": "2026-12-31T23:59:59Z",
"barcode": "25815105237561780909",
"pin_is_set": false,
"state": "UNACTIVATED",
"state_reason": "New card",
"expedite": false,
"fulfillment_status": "ISSUED",
"fulfillment": {
"shipping": {
"method": "FEDEX_REGULAR",
"care_of_line": "my_care_of_value"
},
"card_personalization": {
"text": {
"name_line_1": {
"value": "My card personalization line 1"
},
"name_line_2": {
"value": "My card personalization line 2"
}
},
"images": {
"card": {
"name": "my_card_logo.png",
"thermal_color": "Black"
},
"signature": {
"name": "my_signature.png"
},
"carrier_return_window": {
"name": "my_return_address_image.png"
}
}
}
},
"instrument_type": "PHYSICAL_MSR"
},
{
"created_time": "2021-11-03T21:55:08Z",
"last_modified_time": "2021-11-03T21:55:08Z",
"token": "my_user-01-child_01_card_01",
"user_token": "my_user-01-child_01",
"card_product_token": "my_cardproduct_01",
"last_four": "2810",
"pan": "1111115454542810",
"expiration": "1126",
"expiration_time": "2026-11-30T23:59:59Z",
"barcode": "63143403984499099324",
"pin_is_set": false,
"state": "UNACTIVATED",
"state_reason": "New card",
"expedite": false,
"fulfillment_status": "ISSUED",
"instrument_type": "PHYSICAL_MSR"
}
]
}
```
Retrieve card
**Action:** `GET`\
**Endpoint:** `/cards/{token}`
{/* */}
Retrieves a specific card.
This endpoint supports [field filtering](/core-api/field-filtering/) and [object expansion](/core-api/object-expansion/).
URL path parameters
| Fields | Description |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| token
string
Required | Unique identifier of the card you want to retrieve.
**Allowable Values:**
Existing card 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 |
| expand
string
Optional | Embeds the associated object of the specified type into the response, for all `GET /cards` endpoints.
**Allowable Values:**
`user`, `cardproduct` |
Response body
| Fields | Description |
| ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| activation\_actions
object
Conditionally returned | Defines actions to execute when the card is activated. The fields in this object are mutually exclusive.
**Allowable Values:**
`swap_digital_wallet_tokens_from_card_token`, `terminate_reissued_source_card` |
| activation\_actions.**swap\_digital\_wallet\_tokens\_from\_card\_token**
string
Conditionally returned | Moves all digital wallet tokens from the specified card to the new card.
Not relevant when `reissue_pan_from_card_token` is set.
Send a `GET` request to `/cards/user/{token}` to retrieve card tokens for a particular user.
**Allowable Values:**
1–36 chars
Existing card token |
| activation\_actions.**terminate\_reissued\_source\_card**
boolean
Conditionally returned | If you are reissuing a card, the source card is terminated by default. To prevent the source card from being terminated, set this field to `false`.
Only relevant when `reissue_pan_from_card_token` is set.
**Allowable Values:**
`true`, `false`
**Default value:**
`true` |
| barcode
string
Returned | Barcode printed on the card, expressed as numerals.
**Allowable Values:**
10-20 chars |
| bulk\_issuance\_token
string
Conditionally returned | Unique identifier of the bulk card order.
**Allowable Values:**
1-36 chars |
| card\_product\_token
string
Returned | Unique identifier of the card product.
**Allowable Values:**
1-36 chars |
| chip\_cvv\_number
string
Conditionally returned | Three-digit card verification value (ICVV) stored on the chip of the card.
**Allowable Values:**
3 chars |
| contactless\_exemption\_counter
integer
Conditionally returned | Running count of the contactless transactions successfully completed since the last strong customer authentication (SCA) challenge was issued. You can limit the number of contactless transactions that can be performed without issuing an SCA challenge at the card product level.
For more information about strong customer authentication, see Card Products.
**Allowable Values:**
Any integer |
| contactless\_exemption\_total\_amount
decimal
Conditionally returned | Running total of the money spent in contactless transactions successfully completed since the last strong customer authentication (SCA) challenge was issued. You can limit the total amount that can be spent in contactless transactions without issuing an SCA challenge at the card product level.
For more information about strong customer authentication, see Card Products.
**Allowable Values:**
Any integer |
| contactless\_exemption\_transaction\_currency
string
Conditionally returned | Indicates the currency type of the transaction.
**Allowable Values:**
Valid three-character ISO 4217 currency code |
| created\_time
datetime
Returned | Date and time when the resource was created, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| cvv\_number
string
Conditionally returned | Three-digit card verification value (CVV2 or CVC2) printed on the card.
**Allowable Values:**
3 chars |
| 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
datetime
Returned | Expiration date and time, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| fulfillment
object
Conditionally returned | Determines physical characteristics of a card and shipment information.
**Allowable Values:**
`card_fulfillment_reason`, `card_personalization`, `shipping` |
| fulfillment.**card\_fulfillment\_reason**
string
Conditionally returned | Descriptive reason for the 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.
This object is returned if it exists in the resource.
**Allowable Values:**
`care_of_line`, `method`, `recipient_address`, `return_address` |
| fulfillment.shipping.**care\_of\_line**
string
Conditionally returned | Specifies the value of the care of (C/O) line on the mailing carrier.
This field is returned if it exists in the resource.
**Allowable Values:**
255 char max |
| fulfillment.shipping.**method**
string
Conditionally returned | Specifies the shipping service.
This field is returned if it exists in the resource.
**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` |
| fulfillment.shipping.**recipient\_address**
object
Conditionally returned | Address to which the order will be shipped.
This field is returned if it exists in the resource.
**Allowable Values:**
Existing `recipient_address` object |
| fulfillment.shipping.recipient\_address.**address1**
string
Conditionally returned | Number and street of the address.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.recipient\_address.**country**
string
Conditionally returned | Country of the address.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.recipient\_address.**last\_name**
string
Conditionally returned | Last name of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.recipient\_address.**middle\_name**
string
Conditionally returned | Middle name of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.recipient\_address.**phone**
string
Conditionally returned | Telephone number of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
20 char max |
| fulfillment.shipping.recipient\_address.**postal\_code**
string
Conditionally returned | Postal code of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
10 char max |
| fulfillment.shipping.recipient\_address.**state**
string
Conditionally returned | State or province of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
32 char max |
| fulfillment.shipping.recipient\_address.**zip**
string
Conditionally returned | United States ZIP code of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
10 char max |
| fulfillment.shipping.**return\_address**
object
Conditionally returned | Address to which the order will be returned if shipping fails.
This object is returned if it exists in the resource.
**Allowable Values:**
Existing `return_address` object |
| fulfillment.shipping.return\_address.**address1**
string
Conditionally returned | Number and street of the address.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.return\_address.**country**
string
Conditionally returned | Country of the address.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.return\_address.**last\_name**
string
Conditionally returned | Last name of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.return\_address.**middle\_name**
string
Conditionally returned | Middle name of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.return\_address.**phone**
string
Conditionally returned | Telephone number of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
20 char max |
| fulfillment.shipping.return\_address.**postal\_code**
string
Conditionally returned | Postal code of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
10 char max |
| fulfillment.shipping.return\_address.**state**
string
Conditionally returned | State or province of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
32 char max |
| fulfillment.shipping.return\_address.**zip**
string
Conditionally returned | United States ZIP code of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
10 char max |
| fulfillment\_status
string
Returned | Card fulfillment status:
- **ISSUED:** Initial state of all newly created/issued cards.
- **ORDERED:** Card ordered through the card fulfillment provider.
- **REORDERED:** Card reordered through the card fulfillment provider.
- **REJECTED:** Card rejected by the card fulfillment provider.
- **SHIPPED:** Card shipped by the 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`, `REORDERED`, `REJECTED`, `SHIPPED`, `DELIVERED`, `DIGITALLY_PRESENTED` |
| instrument\_type
string
Conditionally returned | Instrument type of the card:
- **PHYSICAL\_MSR:** A physical card with a magnetic stripe. This is the default physical card type.
- **PHYSICAL\_ICC:** A physical card with an integrated circuit, or "chip."
- **PHYSICAL\_CONTACTLESS:** A physical card that uses radio frequency identification (RFID) or near-field communication (NFC) to enable payment over a secure radio interface.
- **PHYSICAL\_COMBO:** A physical card with a chip that also supports contactless payments.
- **VIRTUAL\_PAN:** A virtual card with a primary account number (PAN).
**Allowable Values:**
`PHYSICAL_MSR`, `PHYSICAL_ICC`, `PHYSICAL_CONTACTLESS`, `PHYSICAL_COMBO`, `VIRTUAL_PAN` |
| last\_four
string
Returned | Last four digits of the card primary account number (PAN).
**Allowable Values:**
4 chars |
| last\_modified\_time
datetime
Returned | Date and time when the resource was last modified, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| metadata
object
Conditionally returned | Associates customer-provided metadata with the card.
**Allowable Values:**
Contains the names and values of up to 20 fields in the format `"my_name_1": "my_value_1"` |
| 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 |
| reissue\_pan\_from\_card\_token
string
Conditionally returned | Reissues the specified card (known as the "source" card).
**Allowable Values:**
Existing card token |
| new\_pan\_from\_card\_token
string
Conditionally returned | Reissues the specified card (known as the "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`, `UNSUPPORTED`, `UNACTIVATED`, `LIMITED` |
| state\_reason
string
Returned | Descriptive reason for why the card is in its current state. For example, "Card activated by cardholder".
**Allowable Values:**
255 char max |
| token
string
Returned | Unique identifier of the card.
**Allowable Values:**
Existing card token |
| translate\_pin\_from\_card\_token
string
Conditionally returned | Copies the personal identification number (PIN) from the specified source card to the newly created card.
**Allowable Values:**
Existing card token |
| user\_token
string
Returned | Unique identifier of the cardholder.
**Allowable Values:**
Existing user token |
Sample response body
```json JSON expandable lines wrap theme={null}
{
"created_time": "2022-02-14T18:48:10Z",
"last_modified_time": "2022-02-14T18:58:10Z",
"token": "mytestcard01",
"user_token": "my_user_01",
"card_product_token": "my_cardproduct_01",
"last_four": "8949",
"pan": "1111115454548949",
"expiration": "0221",
"expiration_time": "2027-02-28T23:59:59Z",
"barcode": "17469201908992951865",
"pin_is_set": false,
"state": "UNACTIVATED",
"state_reason": "New card",
"expedite": false,
"fulfillment_status": "ISSUED",
"fulfillment": {
"card_personalization": {
"text": {
"name_line_1": {
"value": "My card personalization line 1"
},
"name_line_2": {
"value": "My card personalization line 2"
}
},
"images": {
"card": {
"name": "my_card_logo.png",
"thermal_color": "Black"
},
"signature": {
"name": "my_signature.png"
},
"carrier_return_window": {
"name": "my_return_address_image.png"
}
}
}
},
"instrument_type": "PHYSICAL_MSR",
"metadata": {
"my_name_1": "my_value_1",
"my_name_2": "my_value_2"
}
}
```
Update card
**Action:** `PUT`\
**Endpoint:** `/cards/{token}`
{/* */}
Updates the details of an existing card.
URL path parameters
| Fields | Description |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| token
string
Required | Unique identifier of the card you want to update.
**Allowable Values:**
Existing card token |
Request body
| Fields | Description |
| --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| expedite
boolean
Optional | Set to `true` to request expedited processing of the card by your card fulfillment provider.
This expedited service is available for cards fulfilled by Perfect Plastic Printing, IDEMIA, and Arroweye Solutions.
**NOTE:** Contact your Marqeta representative for information regarding the cost of expedited service.
**Allowable Values:**
`true`, `false`
**Default value:**
`false` |
| fulfillment
object
Optional | 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
Optional | Reason for card fulfillment.
**Allowable Values:**
`NEW`, `LOST_STOLEN`, `EXPIRED` |
| fulfillment.**card\_personalization**
object
Required | Specifies personalized attributes to be added to the card.
**Allowable Values:**
`carrier`, `images`, `perso_type`, `text` |
| fulfillment.card\_personalization.**carrier**
object
Optional | 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
Optional | 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
Optional | 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
Optional | 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
Optional | Specifies a custom message that appears on the card carrier.
**Allowable Values:**
60 char max |
| fulfillment.card\_personalization.carrier.**message\_line\_2**
string
Optional | 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
Optional | Specifies the card carrier template to use.
**Allowable Values:**
Card carrier template ID |
| fulfillment.card\_personalization.**images**
object
Optional | Specifies personalized images that appear on the card.
**Allowable Values:**
`card`, `carrier`, `carrier_return_window`, `signature` |
| fulfillment.card\_personalization.images.**card**
object
Optional | Specifies personalized images that appear on the card.
**Allowable Values:**
`name`, `thermal_color` |
| fulfillment.card\_personalization.images.card.**name**
string
Optional | 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
Optional | 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
Optional | Specifies personalized images that appear on the card carrier.
**Allowable Values:**
`message_1`, `name` |
| fulfillment.card\_personalization.images.carrier.**message\_1**
string
Optional | Specifies a custom message that appears on the card carrier.
**Allowable Values:**
60 char max |
| fulfillment.card\_personalization.images.carrier.**name**
string
Optional | 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
Optional | 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
Optional | 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
Optional | Specifies a PNG image of the cardholder’s signature.
**Allowable Values:**
`name` |
| fulfillment.card\_personalization.images.signature.**name**
string
Optional | 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
Optional | Specifies the type of card personalization.
**Allowable Values:**
`EMBOSS`, `LASER`, `FLAT` |
| fulfillment.card\_personalization.**text**
object
Required | 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
Required | 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
Optional | Line of personalized text printed on the card.
**Allowable Values:**
21 char max |
| fulfillment.card\_personalization.text.**name\_line\_2**
object
Optional | 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
Optional | Line of personalized text printed on the card.
**Allowable Values:**
21 char max |
| fulfillment.card\_personalization.text.**name\_line\_3**
object
Optional | 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
Optional | Line of personalized text printed on the card.
**Allowable Values:**
21 char max |
| fulfillment.**shipping**
object
Optional | Specifies shipping details for the order.
**Allowable Values:**
`care_of_line`, `method`, `recipient_address`, `return_address` |
| fulfillment.shipping.**care\_of\_line**
string
Optional | 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
Optional | 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
Optional | 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
Optional | 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
Optional | 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
Optional | City of the address.
**Allowable Values:**
40 char max |
| fulfillment.shipping.recipient\_address.**country**
string
Optional | 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
Optional | First name of the addressee.
**Allowable Values:**
40 char max |
| fulfillment.shipping.recipient\_address.**last\_name**
string
Optional | Last name of the addressee.
**Allowable Values:**
40 char max |
| fulfillment.shipping.recipient\_address.**middle\_name**
string
Optional | Middle name of the addressee.
**Allowable Values:**
40 char max |
| fulfillment.shipping.recipient\_address.**phone**
string
Optional | Telephone number of the addressee.
**Allowable Values:**
20 char max |
| fulfillment.shipping.recipient\_address.**postal\_code**
string
Optional | Postal code of the address.
**Allowable Values:**
10 char max |
| fulfillment.shipping.recipient\_address.**state**
string
Optional | State of the address.
**Allowable Values:**
32 char max |
| fulfillment.shipping.recipient\_address.**zip**
string
Optional | United States ZIP code of the address.
**Allowable Values:**
10 char max |
| fulfillment.shipping.**return\_address**
object
Optional | 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
Optional | 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
Optional | 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
Optional | City of the address.
**Allowable Values:**
40 char max |
| fulfillment.shipping.return\_address.**country**
string
Optional | 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
Optional | First name of the addressee.
**Allowable Values:**
40 char max |
| fulfillment.shipping.return\_address.**last\_name**
string
Optional | Last name of the addressee.
**Allowable Values:**
40 char max |
| fulfillment.shipping.return\_address.**middle\_name**
string
Optional | Middle name of the addressee.
**Allowable Values:**
40 char max |
| fulfillment.shipping.return\_address.**phone**
string
Optional | Telephone number of the addressee.
**Allowable Values:**
20 char max |
| fulfillment.shipping.return\_address.**postal\_code**
string
Optional | Postal code of the address.
**Allowable Values:**
10 char max |
| fulfillment.shipping.return\_address.**state**
string
Optional | State of the address.
**Allowable Values:**
32 char max |
| fulfillment.shipping.return\_address.**zip**
string
Optional | United States ZIP code of the address.
**Allowable Values:**
10 char max |
| metadata
object
Optional | Associates customer-provided metadata with the card.
**Allowable Values:**
Contains the names and values of up to 20 fields in the format `"my_name_1": "my_value_1"` |
| token
string
Required | Unique identifier of the card you want to update.
**Allowable Values:**
1–36 chars
Existing card token
Send a `GET` request to `/cards` to retrieve card tokens. |
| user\_token
string
Optional | Specifies the user you want to associate with the card.
**Allowable Values:**
1–36 chars
Existing user token.
Send a `GET` request to `/users` to retrieve user tokens. |
Sample request body
```json JSON lines wrap theme={null}
{
"token": "my_card_token_03",
"user_token": "my_user_03"
}
```
Response body
| Fields | Description |
| ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| activation\_actions
object
Conditionally returned | Defines actions to execute when the card is activated. The fields in this object are mutually exclusive.
**Allowable Values:**
`swap_digital_wallet_tokens_from_card_token`, `terminate_reissued_source_card` |
| activation\_actions.**swap\_digital\_wallet\_tokens\_from\_card\_token**
string
Conditionally returned | Moves all digital wallet tokens from the specified card to the new card.
Not relevant when `reissue_pan_from_card_token` is set.
Send a `GET` request to `/cards/user/{token}` to retrieve card tokens for a particular user.
**Allowable Values:**
1–36 chars
Existing card token |
| activation\_actions.**terminate\_reissued\_source\_card**
boolean
Conditionally returned | If you are reissuing a card, the source card is terminated by default. To prevent the source card from being terminated, set this field to `false`.
Only relevant when `reissue_pan_from_card_token` is set.
**Allowable Values:**
`true`, `false`
**Default value:**
`true` |
| barcode
string
Returned | Barcode printed on the card, expressed as numerals.
**Allowable Values:**
10-20 chars |
| bulk\_issuance\_token
string
Conditionally returned | Unique identifier of the bulk card order.
**Allowable Values:**
1-36 chars |
| card\_product\_token
string
Returned | Unique identifier of the card product.
**Allowable Values:**
1-36 chars |
| chip\_cvv\_number
string
Conditionally returned | Three-digit card verification value (ICVV) stored on the chip of the card.
**Allowable Values:**
3 chars |
| contactless\_exemption\_counter
integer
Conditionally returned | Running count of the contactless transactions successfully completed since the last strong customer authentication (SCA) challenge was issued. You can limit the number of contactless transactions that can be performed without issuing an SCA challenge at the card product level.
For more information about strong customer authentication, see Card Products.
**Allowable Values:**
Any integer |
| contactless\_exemption\_total\_amount
decimal
Conditionally returned | Running total of the money spent in contactless transactions successfully completed since the last strong customer authentication (SCA) challenge was issued. You can limit the total amount that can be spent in contactless transactions without issuing an SCA challenge at the card product level.
For more information about strong customer authentication, see Card Products.
**Allowable Values:**
Any integer |
| contactless\_exemption\_transaction\_currency
string
Conditionally returned | Indicates the currency type of the transaction.
**Allowable Values:**
Valid three-character ISO 4217 currency code |
| created\_time
datetime
Returned | Date and time when the resource was created, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| cvv\_number
string
Conditionally returned | Three-digit card verification value (CVV2 or CVC2) printed on the card.
**Allowable Values:**
3 chars |
| 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
datetime
Returned | Expiration date and time, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| fulfillment
object
Conditionally returned | Determines physical characteristics of a card and shipment information.
**Allowable Values:**
`card_fulfillment_reason`, `card_personalization`, `shipping` |
| fulfillment.**card\_fulfillment\_reason**
string
Conditionally returned | Descriptive reason for the 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.
This object is returned if it exists in the resource.
**Allowable Values:**
`care_of_line`, `method`, `recipient_address`, `return_address` |
| fulfillment.shipping.**care\_of\_line**
string
Conditionally returned | Specifies the value of the care of (C/O) line on the mailing carrier.
This field is returned if it exists in the resource.
**Allowable Values:**
255 char max |
| fulfillment.shipping.**method**
string
Conditionally returned | Specifies the shipping service.
This field is returned if it exists in the resource.
**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` |
| fulfillment.shipping.**recipient\_address**
object
Conditionally returned | Address to which the order will be shipped.
This field is returned if it exists in the resource.
**Allowable Values:**
Existing `recipient_address` object |
| fulfillment.shipping.recipient\_address.**address1**
string
Conditionally returned | Number and street of the address.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.recipient\_address.**country**
string
Conditionally returned | Country of the address.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.recipient\_address.**last\_name**
string
Conditionally returned | Last name of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.recipient\_address.**middle\_name**
string
Conditionally returned | Middle name of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.recipient\_address.**phone**
string
Conditionally returned | Telephone number of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
20 char max |
| fulfillment.shipping.recipient\_address.**postal\_code**
string
Conditionally returned | Postal code of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
10 char max |
| fulfillment.shipping.recipient\_address.**state**
string
Conditionally returned | State or province of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
32 char max |
| fulfillment.shipping.recipient\_address.**zip**
string
Conditionally returned | United States ZIP code of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
10 char max |
| fulfillment.shipping.**return\_address**
object
Conditionally returned | Address to which the order will be returned if shipping fails.
This object is returned if it exists in the resource.
**Allowable Values:**
Existing `return_address` object |
| fulfillment.shipping.return\_address.**address1**
string
Conditionally returned | Number and street of the address.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.return\_address.**country**
string
Conditionally returned | Country of the address.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.return\_address.**last\_name**
string
Conditionally returned | Last name of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.return\_address.**middle\_name**
string
Conditionally returned | Middle name of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.return\_address.**phone**
string
Conditionally returned | Telephone number of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
20 char max |
| fulfillment.shipping.return\_address.**postal\_code**
string
Conditionally returned | Postal code of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
10 char max |
| fulfillment.shipping.return\_address.**state**
string
Conditionally returned | State or province of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
32 char max |
| fulfillment.shipping.return\_address.**zip**
string
Conditionally returned | United States ZIP code of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
10 char max |
| fulfillment\_status
string
Returned | Card fulfillment status:
- **ISSUED:** Initial state of all newly created/issued cards.
- **ORDERED:** Card ordered through the card fulfillment provider.
- **REORDERED:** Card reordered through the card fulfillment provider.
- **REJECTED:** Card rejected by the card fulfillment provider.
- **SHIPPED:** Card shipped by the 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`, `REORDERED`, `REJECTED`, `SHIPPED`, `DELIVERED`, `DIGITALLY_PRESENTED` |
| instrument\_type
string
Conditionally returned | Instrument type of the card:
- **PHYSICAL\_MSR:** A physical card with a magnetic stripe. This is the default physical card type.
- **PHYSICAL\_ICC:** A physical card with an integrated circuit, or "chip."
- **PHYSICAL\_CONTACTLESS:** A physical card that uses radio frequency identification (RFID) or near-field communication (NFC) to enable payment over a secure radio interface.
- **PHYSICAL\_COMBO:** A physical card with a chip that also supports contactless payments.
- **VIRTUAL\_PAN:** A virtual card with a primary account number (PAN).
**Allowable Values:**
`PHYSICAL_MSR`, `PHYSICAL_ICC`, `PHYSICAL_CONTACTLESS`, `PHYSICAL_COMBO`, `VIRTUAL_PAN` |
| last\_four
string
Returned | Last four digits of the card primary account number (PAN).
**Allowable Values:**
4 chars |
| last\_modified\_time
datetime
Returned | Date and time when the resource was last modified, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| metadata
object
Conditionally returned | Associates customer-provided metadata with the card.
**Allowable Values:**
Contains the names and values of up to 20 fields in the format `"my_name_1": "my_value_1"` |
| 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 |
| reissue\_pan\_from\_card\_token
string
Conditionally returned | Reissues the specified card (known as the "source" card).
**Allowable Values:**
Existing card token |
| new\_pan\_from\_card\_token
string
Conditionally returned | Reissues the specified card (known as the "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`, `UNSUPPORTED`, `UNACTIVATED`, `LIMITED` |
| state\_reason
string
Returned | Descriptive reason for why the card is in its current state. For example, "Card activated by cardholder".
**Allowable Values:**
255 char max |
| token
string
Returned | Unique identifier of the card.
**Allowable Values:**
Existing card token |
| translate\_pin\_from\_card\_token
string
Conditionally returned | Copies the personal identification number (PIN) from the specified source card to the newly created card.
**Allowable Values:**
Existing card token |
| user\_token
string
Returned | Unique identifier of the cardholder.
**Allowable Values:**
Existing user token |
Sample response body
```json JSON expandable lines wrap theme={null}
{
"created_time": "2022-02-14T18:48:10Z",
"last_modified_time": "2022-02-14T18:58:10Z",
"token": "mytestcard01",
"user_token": "my_user_01",
"card_product_token": "my_cardproduct_01",
"last_four": "8949",
"pan": "1111115454548949",
"expiration": "0221",
"expiration_time": "2027-02-28T23:59:59Z",
"barcode": "17469201908992951865",
"pin_is_set": false,
"state": "UNACTIVATED",
"state_reason": "New card",
"expedite": false,
"fulfillment_status": "ISSUED",
"fulfillment": {
"shipping": {
"method": "UPS_REGULAR",
"return_address": {
"address1": "123 Henry St",
"address2": "Suite 101",
"city": "Porterville",
"state": "CA",
"postal_code": "93257",
"country": "US",
"phone": "8315555555",
"first_name": "Saki",
"middle_name": "R",
"last_name": "Dogger"
},
"recipient_address": {
"address1": "1234 Grove St",
"city": "Berkeley",
"state": "CA",
"postal_code": "94702",
"country": "US",
"phone": "5105551212",
"first_name": "Jane",
"last_name": "Doe"
}
},
"card_personalization": {
"text": {
"name_line_1": {
"value": "My card personalization line 1"
},
"name_line_2": {
"value": "My card personalization line 2"
}
},
"images": {
"card": {
"name": "my_card_logo.png",
"thermal_color": "Black"
},
"signature": {
"name": "my_signature.png"
},
"carrier_return_window": {
"name": "my_return_address_image.png"
}
}
}
},
"instrument_type": "PHYSICAL_MSR",
"metadata": {
"my_name_1": "my_value_1"
}
}
```
Show card PAN
**Action:** `GET`\
**Endpoint:** `/cards/{token}/showpan`
{/* */}
Retrieves a primary account number (PAN). For security reasons, the PAN is not fully visible on the card resource returned by `GET` `/cards/{token}`.
This endpoint supports [field filtering](/core-api/field-filtering/) and [object expansion](/core-api/object-expansion/).
URL path parameters
| Fields | Description |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| token
string
Required | Unique identifier of the card whose primary account number (PAN) you want to retrieve. Send a `GET` request to `/cards` to retrieve card tokens.
**Allowable Values:**
Existing card 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 |
| show\_cvv\_number
boolean
Optional | Set to `true` to show the CVV2 number in the response.
**Allowable Values:**
`true`, `false` |
Response body
| Fields | Description |
| ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| activation\_actions
object
Conditionally returned | Defines actions to execute when the card is activated. The fields in this object are mutually exclusive.
**Allowable Values:**
`swap_digital_wallet_tokens_from_card_token`, `terminate_reissued_source_card` |
| activation\_actions.**swap\_digital\_wallet\_tokens\_from\_card\_token**
string
Conditionally returned | Moves all digital wallet tokens from the specified card to the new card.
Not relevant when `reissue_pan_from_card_token` is set.
Send a `GET` request to `/cards/user/{token}` to retrieve card tokens for a particular user.
**Allowable Values:**
1–36 chars
Existing card token |
| activation\_actions.**terminate\_reissued\_source\_card**
boolean
Conditionally returned | If you are reissuing a card, the source card is terminated by default. To prevent the source card from being terminated, set this field to `false`.
Only relevant when `reissue_pan_from_card_token` is set.
**Allowable Values:**
`true`, `false`
**Default value:**
`true` |
| barcode
string
Returned | Barcode printed on the card, expressed as numerals.
**Allowable Values:**
10-20 chars |
| bulk\_issuance\_token
string
Conditionally returned | Unique identifier of the bulk card order.
**Allowable Values:**
1-36 chars |
| card\_product\_token
string
Returned | Unique identifier of the card product.
**Allowable Values:**
1-36 chars |
| chip\_cvv\_number
string
Conditionally returned | Three-digit card verification value (ICVV) stored on the chip of the card.
**Allowable Values:**
3 chars |
| contactless\_exemption\_counter
integer
Conditionally returned | Running count of the contactless transactions successfully completed since the last strong customer authentication (SCA) challenge was issued. You can limit the number of contactless transactions that can be performed without issuing an SCA challenge at the card product level.
For more information about strong customer authentication, see Card Products.
**Allowable Values:**
Any integer |
| contactless\_exemption\_total\_amount
decimal
Conditionally returned | Running total of the money spent in contactless transactions successfully completed since the last strong customer authentication (SCA) challenge was issued. You can limit the total amount that can be spent in contactless transactions without issuing an SCA challenge at the card product level.
For more information about strong customer authentication, see Card Products.
**Allowable Values:**
Any integer |
| contactless\_exemption\_transaction\_currency
string
Conditionally returned | Indicates the currency type of the transaction.
**Allowable Values:**
Valid three-character ISO 4217 currency code |
| created\_time
datetime
Returned | Date and time when the resource was created, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| cvv\_number
string
Conditionally returned | Three-digit card verification value (CVV2 or CVC2) printed on the card.
**Allowable Values:**
3 chars |
| 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
datetime
Returned | Expiration date and time, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| fulfillment
object
Conditionally returned | Determines physical characteristics of a card and shipment information.
**Allowable Values:**
`card_fulfillment_reason`, `card_personalization`, `shipping` |
| fulfillment.**card\_fulfillment\_reason**
string
Conditionally returned | Descriptive reason for the 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.
This object is returned if it exists in the resource.
**Allowable Values:**
`care_of_line`, `method`, `recipient_address`, `return_address` |
| fulfillment.shipping.**care\_of\_line**
string
Conditionally returned | Specifies the value of the care of (C/O) line on the mailing carrier.
This field is returned if it exists in the resource.
**Allowable Values:**
255 char max |
| fulfillment.shipping.**method**
string
Conditionally returned | Specifies the shipping service.
This field is returned if it exists in the resource.
**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` |
| fulfillment.shipping.**recipient\_address**
object
Conditionally returned | Address to which the order will be shipped.
This field is returned if it exists in the resource.
**Allowable Values:**
Existing `recipient_address` object |
| fulfillment.shipping.recipient\_address.**address1**
string
Conditionally returned | Number and street of the address.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.recipient\_address.**country**
string
Conditionally returned | Country of the address.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.recipient\_address.**last\_name**
string
Conditionally returned | Last name of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.recipient\_address.**middle\_name**
string
Conditionally returned | Middle name of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.recipient\_address.**phone**
string
Conditionally returned | Telephone number of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
20 char max |
| fulfillment.shipping.recipient\_address.**postal\_code**
string
Conditionally returned | Postal code of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
10 char max |
| fulfillment.shipping.recipient\_address.**state**
string
Conditionally returned | State or province of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
32 char max |
| fulfillment.shipping.recipient\_address.**zip**
string
Conditionally returned | United States ZIP code of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
10 char max |
| fulfillment.shipping.**return\_address**
object
Conditionally returned | Address to which the order will be returned if shipping fails.
This object is returned if it exists in the resource.
**Allowable Values:**
Existing `return_address` object |
| fulfillment.shipping.return\_address.**address1**
string
Conditionally returned | Number and street of the address.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.return\_address.**country**
string
Conditionally returned | Country of the address.
This field is returned if it exists in the resource.
**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.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.return\_address.**last\_name**
string
Conditionally returned | Last name of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.return\_address.**middle\_name**
string
Conditionally returned | Middle name of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
40 char max |
| fulfillment.shipping.return\_address.**phone**
string
Conditionally returned | Telephone number of the addressee.
This field is returned if it exists in the resource.
**Allowable Values:**
20 char max |
| fulfillment.shipping.return\_address.**postal\_code**
string
Conditionally returned | Postal code of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
10 char max |
| fulfillment.shipping.return\_address.**state**
string
Conditionally returned | State or province of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
32 char max |
| fulfillment.shipping.return\_address.**zip**
string
Conditionally returned | United States ZIP code of the address.
This field is returned if it exists in the resource.
**Allowable Values:**
10 char max |
| fulfillment\_status
string
Returned | Card fulfillment status:
- **ISSUED:** Initial state of all newly created/issued cards.
- **ORDERED:** Card ordered through the card fulfillment provider.
- **REORDERED:** Card reordered through the card fulfillment provider.
- **REJECTED:** Card rejected by the card fulfillment provider.
- **SHIPPED:** Card shipped by the 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`, `REORDERED`, `REJECTED`, `SHIPPED`, `DELIVERED`, `DIGITALLY_PRESENTED` |
| instrument\_type
string
Conditionally returned | Instrument type of the card:
- **PHYSICAL\_MSR:** A physical card with a magnetic stripe. This is the default physical card type.
- **PHYSICAL\_ICC:** A physical card with an integrated circuit, or "chip."
- **PHYSICAL\_CONTACTLESS:** A physical card that uses radio frequency identification (RFID) or near-field communication (NFC) to enable payment over a secure radio interface.
- **PHYSICAL\_COMBO:** A physical card with a chip that also supports contactless payments.
- **VIRTUAL\_PAN:** A virtual card with a primary account number (PAN).
**Allowable Values:**
`PHYSICAL_MSR`, `PHYSICAL_ICC`, `PHYSICAL_CONTACTLESS`, `PHYSICAL_COMBO`, `VIRTUAL_PAN` |
| last\_four
string
Returned | Last four digits of the card primary account number (PAN).
**Allowable Values:**
4 chars |
| last\_modified\_time
datetime
Returned | Date and time when the resource was last modified, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| metadata
object
Conditionally returned | Associates customer-provided metadata with the card.
**Allowable Values:**
Contains the names and values of up to 20 fields in the format `"my_name_1": "my_value_1"` |
| 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 |
| reissue\_pan\_from\_card\_token
string
Conditionally returned | Reissues the specified card (known as the "source" card).
**Allowable Values:**
Existing card token |
| new\_pan\_from\_card\_token
string
Conditionally returned | Reissues the specified card (known as the "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`, `UNSUPPORTED`, `UNACTIVATED`, `LIMITED` |
| state\_reason
string
Returned | Descriptive reason for why the card is in its current state. For example, "Card activated by cardholder".
**Allowable Values:**
255 char max |
| token
string
Returned | Unique identifier of the card.
**Allowable Values:**
Existing card token |
| translate\_pin\_from\_card\_token
string
Conditionally returned | Copies the personal identification number (PIN) from the specified source card to the newly created card.
**Allowable Values:**
Existing card token |
| user\_token
string
Returned | Unique identifier of the cardholder.
**Allowable Values:**
Existing user token |
Sample response body
```json JSON expandable lines wrap theme={null}
{
"created_time": "2021-12-28T18:31:23Z",
"last_modified_time": "2022-02-14T19:32:38Z",
"token": "my_user_01_card_02",
"user_token": "my_user_01",
"card_product_token": "my_cardproduct_01",
"last_four": "1865",
"pan": "1111111824981865",
"expiration": "1220",
"expiration_time": "2026-12-31T23:59:59Z",
"cvv_number": "137",
"barcode": "25815105237561780909",
"pin_is_set": false,
"state": "UNACTIVATED",
"state_reason": "New card",
"expedite": false,
"fulfillment_status": "DIGITALLY_PRESENTED",
"fulfillment": {
"shipping": {
"method": "FEDEX_REGULAR",
"care_of_line": "my_care_of_value"
},
"card_personalization": {
"text": {
"name_line_1": {
"value": "My card personalization line 1"
},
"name_line_2": {
"value": "My card personalization line 2"
}
},
"images": {
"card": {
"name": "my_card_logo.png",
"thermal_color": "Black"
},
"signature": {
"name": "my_signature.png"
},
"carrier_return_window": {
"name": "my_return_address_image.png"
}
}
}
},
"instrument_type": "PHYSICAL_MSR"
}
```