Skip to main content
The card resource represents a payment card. Cards are derived from and controlled by the cardproduct resource. For more information on cards, see About Cards. Some attributes of the card resource can be defined in an associated bulkissuance or cardproduct resource. If you define one of these attributes in more than one object, the order of precedence at fulfillment time is as follows:
1
card
2
bulkissuance
3
cardproduct
Defining an attribute in an object with higher precedence overrides, but does not overwrite, the attribute in a lower-precedence object.

​
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 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).
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 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

FieldsDescription
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

FieldsDescription
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
{
  "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

FieldsDescription
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
{
  "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, object expansion, sorting, and pagination.

​
URL query parameters

FieldsDescription
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

FieldsDescription
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
{
  "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 and object expansion.

​
URL path parameters

FieldsDescription
barcode

string

Required		Barcode of the card to retrieve.

Allowable Values:

10-20 chars

​
URL query parameters

FieldsDescription
fields

string

Optional		Comma-delimited list of fields to return (field_1,field_2, and so on). Leave blank to return all fields.

Allowable Values:

Comma-delimited list of fields, or blank

​
Response body

FieldsDescription
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
{
  "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

FieldsDescription
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
{
  "pan": "5454545454545454"
}

​
Response body

FieldsDescription
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
{
  "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, pagination, and object expansion.

​
URL path parameters

FieldsDescription
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

FieldsDescription
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

FieldsDescription
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
{
  "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 and object expansion.

​
URL path parameters

FieldsDescription
token

string

Required		Unique identifier of the card you want to retrieve.

Allowable Values:

Existing card token

​
URL query parameters

FieldsDescription
fields

string

Optional		Comma-delimited list of fields to return (field_1,field_2, and so on). Leave blank to return all fields.

Allowable Values:

Comma-delimited list of fields, or blank
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

FieldsDescription
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
{
  "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

FieldsDescription
token

string

Required		Unique identifier of the card you want to update.

Allowable Values:

Existing card token

​
Request body

FieldsDescription
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
{
  "token": "my_card_token_03",
  "user_token": "my_user_03"
}

​
Response body

FieldsDescription
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
{
  "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 and object expansion.

​
URL path parameters

FieldsDescription
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

FieldsDescription
fields

string

Optional		Comma-delimited list of fields to return (field_1,field_2, and so on). Leave blank to return all fields.

Allowable Values:

Comma-delimited list of fields, or blank
show_cvv_number

boolean

Optional		Set to true to show the CVV2 number in the response.

Allowable Values:

true, false

​
Response body

FieldsDescription
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
{
  "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"
}

Related topics

Cards OverviewCard ProductsAbout CardsCard CountsCard Transitions