/
105 minute read
March 24, 2022

Cards

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:

  • card

  • bulkissuance

  • 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 PIN if your program requires PIN numbers (for example, for EMV 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 PAN and CVV2 number in the response. If show_pan and show_cvv_number are set to true, the fulfillment state of the card is DIGITALLY_PRESENTED instead of the typical initial state of ISSUED. This fulfillment state does not affect the delivery of physical cards.

This endpoint requires PCI DSS compliance if show_pan and show_cvv_number are set to true. You must comply with PCI DSS data security requirements if you store, transmit, or process sensitive card data.

URL query parameters
Fields Description

show_cvv_number

boolean
Optional

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

Allowable Values:

true, false

show_pan

boolean
Optional

Set to true to show the full PAN in the response.

Allowable Values:

true, false

Request body
Fields Description

activation_actions

object
Optional

Defines actions to execute when the card is activated. The fields in this object are mutually exclusive.

Allowable Values:

Existing activation_actions object

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.

Allowable Values:

1–36 chars

Existing card token.

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

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

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

If this field is not specified, the card uses the config.card_life_cycle.expiration_offset of the bulk card order or card product as appropriate.

Allowable Values:

Valid expiration_offset object

expiration_offset.unit

string
Optional

Specifies the units for the value field.

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) that this card is 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:

Existing fulfillment object

fulfillment.card_fulfillment_reason

string
Optional

The reason for card fulfillment.

Allowable Values:

NEW, LOST_STOLEN, EXPIRED

fulfillment.card_personalization

object
Required

Allows personalized attributes to be added to the card.

Allowable Values:

Valid card_personalization object

fulfillment.card_personalization.carrier

object
Optional

Specifies attributes of the card carrier.

Allowable Values:

Valid carrier object

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

string
Optional

Specifies the card carrier template to use.

Allowable Values:

A card carrier template ID

fulfillment.card_personalization.images

object
Optional

Specifies personalized images that appear on the card. Also specifies attributes of the card carrier, if your fulfillment provider is Perfect Plastic Printing or IDEMIA.

Allowable Values:

Valid images object

fulfillment.card_personalization.images.card

object
Optional

Specifies personalized images that appear on the card.

Allowable Values:

Valid images.card object

fulfillment.card_personalization.images.carrier

object
Optional

Specifies personalized images that appear on the card carrier.

Allowable Values:

Valid carrier object

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:

Valid carrier_return_window object

fulfillment.card_personalization.images.signature

object
Optional

Specifies a PNG image of the cardholder’s signature.

Allowable Values:

Valid signature object

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:

Valid text object

fulfillment.card_personalization.text.name_line_1

object
Required

First line of personalized text printed on the card.

Allowable Values:

name_line1.value

fulfillment.card_personalization.text.name_line_2

object
Optional

Second line of personalized text printed on the card.

Allowable Values:

name_line2.value

fulfillment.card_personalization.text.name_line_3

object
Optional

Third line of personalized text printed on the card.

Allowable Values:

name_line3.value

fulfillment.shipping

object
Optional

Specifies the shipping details for the card.

Allowable Values:

Valid shipping object

fulfillment.shipping.care_of_line

string
Optional

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

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

Allowable Values:

255 char max

fulfillment.shipping.method

string
Optional

Specifies the shipping service.

Allowable Values:

LOCAL_MAIL, GROUND, TWO_DAY, OVERNIGHT, INTERNATIONAL, FEDEX_EXPEDITED, FEDEX_REGULAR, UPS_EXPEDITED, UPS_REGULAR, USPS_EXPEDITED, USPS_REGULAR

Shipping options vary by card provider. For details on the specific shipping companies and services offered by your card provider, contact your Marqeta representative.

fulfillment.shipping.recipient_address

object
Optional

Address to which the card will be shipped.

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

Allowable Values:

Valid recipient_address object

fulfillment.shipping.recipient_address.address1

string
Optional

Number and street.

Allowable Values:

255 char max

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

fulfillment.shipping.recipient_address.address2

string
Optional

Additional address information.

Allowable Values:

255 char max

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

fulfillment.shipping.recipient_address.city

string
Optional

City.

Allowable Values:

40 char max

fulfillment.shipping.recipient_address.country

string
Optional

Country.

Allowable Values:

40 char max

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

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

fulfillment.shipping.recipient_address.first_name

string
Optional

First name.

Allowable Values:

40 char max

fulfillment.shipping.recipient_address.last_name

string
Optional

Last name.

Allowable Values:

40 char max

fulfillment.shipping.recipient_address.middle_name

string
Optional

Middle name.

Allowable Values:

40 char max

fulfillment.shipping.recipient_address.phone

string
Optional

Telephone number.

Allowable Values:

20 char max

fulfillment.shipping.recipient_address.postal_code

string
Optional

Postal code.

Allowable Values:

10 char max

fulfillment.shipping.recipient_address.state

string
Optional

State.

Allowable Values:

32 char max

fulfillment.shipping.recipient_address.zip

string
Optional

United States ZIP code.

Allowable Values:

10 char max

fulfillment.shipping.return_address

object
Optional

Address to which cards will be returned if shipping fails.

Allowable Values:

Valid return_address object

fulfillment.shipping.return_address.address1

string
Optional

Number and street.

Allowable Values:

255 char max

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

fulfillment.shipping.return_address.address2

string
Optional

Additional address information.

Allowable Values:

255 char max

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

fulfillment.shipping.return_address.city

string
Optional

City.

Allowable Values:

40 char max

fulfillment.shipping.return_address.country

string
Optional

Country.

Allowable Values:

40 char max

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

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

fulfillment.shipping.return_address.first_name

string
Optional

First name.

Allowable Values:

40 char max

fulfillment.shipping.return_address.last_name

string
Optional

Last name.

Allowable Values:

40 char max

fulfillment.shipping.return_address.middle_name

string
Optional

Middle name.

Allowable Values:

40 char max

fulfillment.shipping.return_address.phone

string
Optional

Telephone number.

Allowable Values:

20 char max

fulfillment.shipping.return_address.postal_code

string
Optional

Postal code.

Allowable Values:

10 char max

fulfillment.shipping.return_address.state

string
Optional

State.

Allowable Values:

32 char max

fulfillment.shipping.return_address.zip

string
Optional

United States ZIP code.

Allowable Values:

10 char max

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 PAN and 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.

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.

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

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.

Allowable Values:

36 char max

Existing card token

Send a GET request to /cards/user/{token} to retrieve card tokens for a particular user

token

string
Optional

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

Allowable Values:

36 char max

Existing card token

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

user_token

string
Required

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

Is this helpful?

Yes
No
Response body
Fields Description

activation_actions

object
Conditionally returned

Defines actions to execute when the card is activated. The fields in this object are mutually exclusive.

Allowable Values:

Existing activation_actions object

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.

Allowable Values:

1–36 chars

Existing card token.

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

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

The barcode printed on the card, expressed as numerals.

Allowable Values:

10-20 chars

bulk_issuance_token

string
Conditionally returned

The unique identifier of the bulk card order.

Allowable Values:

1-36 chars

card_product_token

string
Returned

The unique identifier of the card product.

Allowable Values:

1-36 chars

chip_cvv_number

string
Conditionally returned

The three-digit card verification value (ICVV) stored on the chip of the card.

Allowable Values:

3 chars

contactless_exemption_counter

integer
Conditionally returned

A running count of contactless transactions. You can limit the number of contactless transactions that can be performed without issuing a strong customer authentication (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

A running total of money spent in contactless transactions. You can limit the total amount that can be spent in contactless transactions without issuing a strong customer authentication (SCA) challenge at the card product level.

For more information about strong customer authentication, see Card Products.

Allowable Values:

Any integer

created_time

datetime
Returned

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

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

cvv_number

string
Conditionally returned

The 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

The expiration date in MMyy format.

Allowable Values:

Format: MMyy

expiration_time

datetime
Returned

The expiration date and time in UTC format.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

fulfillment

object
Conditionally returned

Determines physical characteristics of a card and shipment information.

Allowable Values:

Existing fulfillment object

fulfillment.card_fulfillment_reason

string
Conditionally returned

A descriptive reason for the card fulfillment.

Allowable Values:

NEW, LOST_STOLEN, EXPIRED

fulfillment.card_personalization

object
Returned

Allows personalized attributes to be added to the card.

Allowable Values:

Valid card_personalization object

fulfillment.card_personalization.carrier

object
Conditionally returned

Specifies attributes of the card carrier.

Allowable Values:

Valid carrier object

fulfillment.card_personalization.carrier.logo_file

string
Conditionally returned

Specifies an image to display on the card carrier.

Allowable Values:

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

fulfillment.card_personalization.carrier.logo_thumbnail_file

string
Conditionally returned

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

Allowable Values:

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

fulfillment.card_personalization.carrier.message_file

string
Conditionally returned

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

Allowable Values:

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

fulfillment.card_personalization.carrier.message_line

string
Conditionally returned

Specifies a custom message that appears on the card carrier.

Allowable Values:

60 char max

fulfillment.card_personalization.carrier.template_id

string
Conditionally returned

Specifies the card carrier template to use.

Allowable Values:

A card carrier template ID

fulfillment.card_personalization.images

object
Conditionally returned

Specifies personalized images that appear on the card. Also specifies attributes of the card carrier, if your fulfillment provider is Perfect Plastic Printing or IDEMIA.

Allowable Values:

Valid images object

fulfillment.card_personalization.images.card

object
Conditionally returned

Specifies personalized images that appear on the card.

Allowable Values:

Valid images.card object

fulfillment.card_personalization.images.carrier

object
Conditionally returned

Specifies personalized images that appear on the card carrier.

Allowable Values:

Valid carrier object

fulfillment.card_personalization.images.carrier_return_window

object
Conditionally returned

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

Allowable Values:

Valid carrier_return_window object

fulfillment.card_personalization.images.signature

object
Conditionally returned

Specifies a PNG image of the cardholder’s signature.

Allowable Values:

Valid signature object

fulfillment.card_personalization.perso_type

string
Conditionally returned

Specifies the type of card personalization.

Allowable Values:

EMBOSS, LASER, FLAT

fulfillment.card_personalization.text

object
Returned

Specifies personalized text that appears on the card.

Allowable Values:

Valid text object

fulfillment.card_personalization.text.name_line_1

object
Returned

First line of personalized text printed on the card.

Allowable Values:

name_line1.value

fulfillment.card_personalization.text.name_line_2

object
Conditionally returned

Second line of personalized text printed on the card.

Allowable Values:

name_line2.value

fulfillment.card_personalization.text.name_line_3

object
Conditionally returned

Third line of personalized text printed on the card.

Allowable Values:

name_line3.value

fulfillment.shipping

object
Conditionally returned

Specifies shipping details for the card.

Allowable Values:

Existing shipping object

fulfillment.shipping.care_of_line

string
Conditionally returned

The specified value of the C/O (care of) line on the mailing carrier.

Allowable Values:

255 char max

fulfillment.shipping.method

string
Conditionally returned

Specifies the shipping service.

Allowable Values:

FEDEX_EXPEDITED, FEDEX_REGULAR, UPS_EXPEDITED, UPS_REGULAR, USPS_EXPEDITED, USPS_REGULAR

fulfillment.shipping.recipient_address

object
Conditionally returned

Specifies a fulfillment shipping or return address.

Allowable Values:

Valid fulfillment_address_response object

fulfillment.shipping.recipient_address.address1

string
Conditionally returned

Number and street.

Allowable Values:

255 char max

fulfillment.shipping.recipient_address.address2

string
Conditionally returned

Additional address information.

Allowable Values:

255 char max

fulfillment.shipping.recipient_address.city

string
Conditionally returned

City.

Allowable Values:

40 char max

fulfillment.shipping.recipient_address.country

string
Conditionally returned

Country.

Allowable Values:

40 char max

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

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

fulfillment.shipping.recipient_address.first_name

string
Conditionally returned

First name.

Allowable Values:

40 char max

fulfillment.shipping.recipient_address.last_name

string
Conditionally returned

Last name.

Allowable Values:

40 char max

fulfillment.shipping.recipient_address.middle_name

string
Conditionally returned

Middle name.

Allowable Values:

40 char max

fulfillment.shipping.recipient_address.phone

string
Conditionally returned

Telephone number.

Allowable Values:

20 char max

fulfillment.shipping.recipient_address.postal_code

string
Conditionally returned

Postal code.

Allowable Values:

10 char max

fulfillment.shipping.recipient_address.state

string
Conditionally returned

State.

Allowable Values:

32 char max

fulfillment.shipping.recipient_address.zip

string
Conditionally returned

United States ZIP code.

Allowable Values:

10 char max

fulfillment.shipping.return_address

object
Conditionally returned

Specifies a fulfillment shipping or return address.

Allowable Values:

Valid fulfillment_address_response object

fulfillment.shipping.return_address.address1

string
Conditionally returned

Number and street.

Allowable Values:

255 char max

fulfillment.shipping.return_address.address2

string
Conditionally returned

Additional address information.

Allowable Values:

255 char max

fulfillment.shipping.return_address.city

string
Conditionally returned

City.

Allowable Values:

40 char max

fulfillment.shipping.return_address.country

string
Conditionally returned

Country.

Allowable Values:

40 char max

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

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

fulfillment.shipping.return_address.first_name

string
Conditionally returned

First name.

Allowable Values:

40 char max

fulfillment.shipping.return_address.last_name

string
Conditionally returned

Last name.

Allowable Values:

40 char max

fulfillment.shipping.return_address.middle_name

string
Conditionally returned

Middle name.

Allowable Values:

40 char max

fulfillment.shipping.return_address.phone

string
Conditionally returned

Telephone number.

Allowable Values:

20 char max

fulfillment.shipping.return_address.postal_code

string
Conditionally returned

Postal code.

Allowable Values:

10 char max

fulfillment.shipping.return_address.state

string
Conditionally returned

State.

Allowable Values:

32 char max

fulfillment.shipping.return_address.zip

string
Conditionally returned

United States ZIP code.

Allowable Values:

10 char max

fulfillment_status

string
Returned

The 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

The 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 PAN.

Allowable Values:

PHYSICAL_MSR, PHYSICAL_ICC, PHYSICAL_CONTACTLESS, PHYSICAL_COMBO, VIRTUAL_PAN

last_four

string
Returned

The last four digits of the card PAN.

Allowable Values:

4 chars

last_modified_time

datetime
Returned

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

Allowable Values:

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

The primary account number (PAN) of the card.

Allowable Values:

16 char max

pin_is_set

boolean
Returned

Specifies if the personal identification number (PIN) has been set for the card.

Allowable Values:

4 chars

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

A descriptive reason for the state of the card.

Allowable Values:

255 char max

token

string
Returned

The unique identifier of the card.

Allowable Values:

Existing card token

translate_pin_from_card_token

string
Conditionally returned

Copies the PIN from the specified source card to the newly created card.

Allowable Values:

Existing card token

user_token

string
Returned

The unique identifier of the cardholder.

Allowable Values:

Existing user token

Sample response body
JSON
Copied

Is this helpful?

Yes
No

List cards by last 4 digits of PAN

Action: GET
Endpoint: /cards

Retrieves an array of cards whose PANs end in the four digits specified by the last_four query parameter.

URL query parameters
Fields Description

count

integer
Optional

The number of resources to retrieve.

Allowable Values:

1-10

start_index

integer
Optional

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

Allowable Values:

Any integer

last_four

string
Required

The last four digits of the 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:

lastModifiedTime, createdTime, or any field in the resource model

Response body
Fields Description

count

integer
Conditionally returned

The number of resources retrieved.

Allowable Values:

1-10

data

array of objects
Conditionally returned

An array of card objects.

Allowable Values:

Valid cards array

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:

Existing activation_actions object

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.

Allowable Values:

1–36 chars

Existing card token.

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

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

The barcode printed on the card, expressed as numerals.

Allowable Values:

10-20 chars

data[].bulk_issuance_token

string
Conditionally returned

The unique identifier of the bulk card order.

Allowable Values:

1-36 chars

data[].card_product_token

string
Returned

The unique identifier of the card product.

Allowable Values:

1-36 chars

data[].chip_cvv_number

string
Conditionally returned

The three-digit card verification value (ICVV) stored on the chip of the card.

Allowable Values:

3 chars

data[].contactless_exemption_counter

integer
Conditionally returned

A running count of contactless transactions. You can limit the number of contactless transactions that can be performed without issuing a strong customer authentication (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

A running total of money spent in contactless transactions. You can limit the total amount that can be spent in contactless transactions without issuing a strong customer authentication (SCA) challenge at the card product level.

For more information about strong customer authentication, see Card Products.

Allowable Values:

Any integer

data[].created_time

datetime
Returned

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

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

data[].cvv_number

string
Conditionally returned

The 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

The expiration date in MMyy format.

Allowable Values:

Format: MMyy

data[].expiration_time

datetime
Returned

The expiration date and time in UTC format.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

data[].fulfillment

object
Conditionally returned

Determines physical characteristics of a card and shipment information.

Allowable Values:

Existing fulfillment object

data[].fulfillment.card_fulfillment_reason

string
Conditionally returned

A descriptive reason for the card fulfillment.

Allowable Values:

NEW, LOST_STOLEN, EXPIRED

data[].fulfillment.card_personalization

object
Returned

Allows personalized attributes to be added to the card.

Allowable Values:

Valid card_personalization object

data[].fulfillment.card_personalization.carrier

object
Conditionally returned

Specifies attributes of the card carrier.

Allowable Values:

Valid carrier object

data[].fulfillment.card_personalization.carrier.logo_file

string
Conditionally returned

Specifies an image to display on the card carrier.

Allowable Values:

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

data[].fulfillment.card_personalization.carrier.logo_thumbnail_file

string
Conditionally returned

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

Allowable Values:

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

data[].fulfillment.card_personalization.carrier.message_file

string
Conditionally returned

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

Allowable Values:

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

data[].fulfillment.card_personalization.carrier.message_line

string
Conditionally returned

Specifies a custom message that appears on the card carrier.

Allowable Values:

60 char max

data[].fulfillment.card_personalization.carrier.template_id

string
Conditionally returned

Specifies the card carrier template to use.

Allowable Values:

A card carrier template ID

data[].fulfillment.card_personalization.images

object
Conditionally returned

Specifies personalized images that appear on the card. Also specifies attributes of the card carrier, if your fulfillment provider is Perfect Plastic Printing or IDEMIA.

Allowable Values:

Valid images object

data[].fulfillment.card_personalization.images.card

object
Conditionally returned

Specifies personalized images that appear on the card.

Allowable Values:

Valid images.card object

data[].fulfillment.card_personalization.images.carrier

object
Conditionally returned

Specifies personalized images that appear on the card carrier.

Allowable Values:

Valid carrier object

data[].fulfillment.card_personalization.images.carrier_return_window

object
Conditionally returned

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

Allowable Values:

Valid carrier_return_window object

data[].fulfillment.card_personalization.images.signature

object
Conditionally returned

Specifies a PNG image of the cardholder’s signature.

Allowable Values:

Valid signature object

data[].fulfillment.card_personalization.perso_type

string
Conditionally returned

Specifies the type of card personalization.

Allowable Values:

EMBOSS, LASER, FLAT

data[].fulfillment.card_personalization.text

object
Returned

Specifies personalized text that appears on the card.

Allowable Values:

Valid text object

data[].fulfillment.card_personalization.text.name_line_1

object
Returned

First line of personalized text printed on the card.

Allowable Values:

name_line1.value

data[].fulfillment.card_personalization.text.name_line_2

object
Conditionally returned

Second line of personalized text printed on the card.

Allowable Values:

name_line2.value

data[].fulfillment.card_personalization.text.name_line_3

object
Conditionally returned

Third line of personalized text printed on the card.

Allowable Values:

name_line3.value

data[].fulfillment.shipping

object
Conditionally returned

Specifies shipping details for the card.

Allowable Values:

Existing shipping object

data[].fulfillment.shipping.care_of_line

string
Conditionally returned

The specified value of the C/O (care of) line on the mailing carrier.

Allowable Values:

255 char max

data[].fulfillment.shipping.method

string
Conditionally returned

Specifies the shipping service.

Allowable Values:

FEDEX_EXPEDITED, FEDEX_REGULAR, UPS_EXPEDITED, UPS_REGULAR, USPS_EXPEDITED, USPS_REGULAR

data[].fulfillment.shipping.recipient_address

object
Conditionally returned

Specifies a fulfillment shipping or return address.

Allowable Values:

Valid fulfillment_address_response object

data[].fulfillment.shipping.recipient_address.address1

string
Conditionally returned

Number and street.

Allowable Values:

255 char max

data[].fulfillment.shipping.recipient_address.address2

string
Conditionally returned

Additional address information.

Allowable Values:

255 char max

data[].fulfillment.shipping.recipient_address.city

string
Conditionally returned

City.

Allowable Values:

40 char max

data[].fulfillment.shipping.recipient_address.country

string
Conditionally returned

Country.

Allowable Values:

40 char max

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

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

data[].fulfillment.shipping.recipient_address.first_name

string
Conditionally returned

First name.

Allowable Values:

40 char max

data[].fulfillment.shipping.recipient_address.last_name

string
Conditionally returned

Last name.

Allowable Values:

40 char max

data[].fulfillment.shipping.recipient_address.middle_name

string
Conditionally returned

Middle name.

Allowable Values:

40 char max

data[].fulfillment.shipping.recipient_address.phone

string
Conditionally returned

Telephone number.

Allowable Values:

20 char max

data[].fulfillment.shipping.recipient_address.postal_code

string
Conditionally returned

Postal code.

Allowable Values:

10 char max

data[].fulfillment.shipping.recipient_address.state

string
Conditionally returned

State.

Allowable Values:

32 char max

data[].fulfillment.shipping.recipient_address.zip

string
Conditionally returned

United States ZIP code.

Allowable Values:

10 char max

data[].fulfillment.shipping.return_address

object
Conditionally returned

Specifies a fulfillment shipping or return address.

Allowable Values:

Valid fulfillment_address_response object

data[].fulfillment.shipping.return_address.address1

string
Conditionally returned

Number and street.

Allowable Values:

255 char max

data[].fulfillment.shipping.return_address.address2

string
Conditionally returned

Additional address information.

Allowable Values:

255 char max

data[].fulfillment.shipping.return_address.city

string
Conditionally returned

City.

Allowable Values:

40 char max

data[].fulfillment.shipping.return_address.country

string
Conditionally returned

Country.

Allowable Values:

40 char max

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

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

data[].fulfillment.shipping.return_address.first_name

string
Conditionally returned

First name.

Allowable Values:

40 char max

data[].fulfillment.shipping.return_address.last_name

string
Conditionally returned

Last name.

Allowable Values:

40 char max

data[].fulfillment.shipping.return_address.middle_name

string
Conditionally returned

Middle name.

Allowable Values:

40 char max

data[].fulfillment.shipping.return_address.phone

string
Conditionally returned

Telephone number.

Allowable Values:

20 char max

data[].fulfillment.shipping.return_address.postal_code

string
Conditionally returned

Postal code.

Allowable Values:

10 char max

data[].fulfillment.shipping.return_address.state

string
Conditionally returned

State.

Allowable Values:

32 char max

data[].fulfillment.shipping.return_address.zip

string
Conditionally returned

United States ZIP code.

Allowable Values:

10 char max

data[].fulfillment_status

string
Returned

The 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

The 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 PAN.

Allowable Values:

PHYSICAL_MSR, PHYSICAL_ICC, PHYSICAL_CONTACTLESS, PHYSICAL_COMBO, VIRTUAL_PAN

data[].last_four

string
Returned

The last four digits of the card PAN.

Allowable Values:

4 chars

data[].last_modified_time

datetime
Returned

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

Allowable Values:

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

The primary account number (PAN) of the card.

Allowable Values:

16 char max

data[].pin_is_set

boolean
Returned

Specifies if the personal identification number (PIN) has been set for the card.

Allowable Values:

4 chars

data[].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

A descriptive reason for the state of the card.

Allowable Values:

255 char max

data[].token

string
Returned

The unique identifier of the card.

Allowable Values:

Existing card token

data[].translate_pin_from_card_token

string
Conditionally returned

Copies the PIN from the specified source card to the newly created card.

Allowable Values:

Existing card token

data[].user_token

string
Returned

The unique identifier of the cardholder.

Allowable Values:

Existing user token

end_index

integer
Conditionally returned

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

Allowable Values:

Any integer

is_more

boolean
Conditionally returned

A value of true indicates that more unreturned resources exist.

Allowable Values:

true, false

start_index

integer
Conditionally returned

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

Allowable Values:

Any integer

Sample response body
JSON
Copied

Is this helpful?

Yes
No

Retrieve card 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
Fields Description

barcode

string
Required

The barcode of the card to retrieve.

Allowable Values:

10-20 chars

URL query parameters
Fields Description

fields

string
Optional

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

Allowable Values:

Comma-delimited list of fields, or blank

Response body
Fields Description

activation_actions

object
Conditionally returned

Defines actions to execute when the card is activated. The fields in this object are mutually exclusive.

Allowable Values:

Existing activation_actions object

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.

Allowable Values:

1–36 chars

Existing card token.

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

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

The barcode printed on the card, expressed as numerals.

Allowable Values:

10-20 chars

bulk_issuance_token

string
Conditionally returned

The unique identifier of the bulk card order.

Allowable Values:

1-36 chars

card_product_token

string
Returned

The unique identifier of the card product.

Allowable Values:

1-36 chars

chip_cvv_number

string
Conditionally returned

The three-digit card verification value (ICVV) stored on the chip of the card.

Allowable Values:

3 chars

contactless_exemption_counter

integer
Conditionally returned

A running count of contactless transactions. You can limit the number of contactless transactions that can be performed without issuing a strong customer authentication (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

A running total of money spent in contactless transactions. You can limit the total amount that can be spent in contactless transactions without issuing a strong customer authentication (SCA) challenge at the card product level.

For more information about strong customer authentication, see Card Products.

Allowable Values:

Any integer

created_time

datetime
Returned

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

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

cvv_number

string
Conditionally returned

The 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

The expiration date in MMyy format.

Allowable Values:

Format: MMyy

expiration_time

datetime
Returned

The expiration date and time in UTC format.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

fulfillment

object
Conditionally returned

Determines physical characteristics of a card and shipment information.

Allowable Values:

Existing fulfillment object

fulfillment.card_fulfillment_reason

string
Conditionally returned

A descriptive reason for the card fulfillment.

Allowable Values:

NEW, LOST_STOLEN, EXPIRED

fulfillment.card_personalization

object
Returned

Allows personalized attributes to be added to the card.

Allowable Values:

Valid card_personalization object

fulfillment.card_personalization.carrier

object
Conditionally returned

Specifies attributes of the card carrier.

Allowable Values:

Valid carrier object

fulfillment.card_personalization.carrier.logo_file

string
Conditionally returned

Specifies an image to display on the card carrier.

Allowable Values:

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

fulfillment.card_personalization.carrier.logo_thumbnail_file

string
Conditionally returned

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

Allowable Values:

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

fulfillment.card_personalization.carrier.message_file

string
Conditionally returned

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

Allowable Values:

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

fulfillment.card_personalization.carrier.message_line

string
Conditionally returned

Specifies a custom message that appears on the card carrier.

Allowable Values:

60 char max

fulfillment.card_personalization.carrier.template_id

string
Conditionally returned

Specifies the card carrier template to use.

Allowable Values:

A card carrier template ID

fulfillment.card_personalization.images

object
Conditionally returned

Specifies personalized images that appear on the card. Also specifies attributes of the card carrier, if your fulfillment provider is Perfect Plastic Printing or IDEMIA.

Allowable Values:

Valid images object

fulfillment.card_personalization.images.card

object
Conditionally returned

Specifies personalized images that appear on the card.

Allowable Values:

Valid images.card object

fulfillment.card_personalization.images.carrier

object
Conditionally returned

Specifies personalized images that appear on the card carrier.

Allowable Values:

Valid carrier object

fulfillment.card_personalization.images.carrier_return_window

object
Conditionally returned

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

Allowable Values:

Valid carrier_return_window object

fulfillment.card_personalization.images.signature

object
Conditionally returned

Specifies a PNG image of the cardholder’s signature.

Allowable Values:

Valid signature object

fulfillment.card_personalization.perso_type

string
Conditionally returned

Specifies the type of card personalization.

Allowable Values:

EMBOSS, LASER, FLAT

fulfillment.card_personalization.text

object
Returned

Specifies personalized text that appears on the card.

Allowable Values:

Valid text object

fulfillment.card_personalization.text.name_line_1

object
Returned

First line of personalized text printed on the card.

Allowable Values:

name_line1.value

fulfillment.card_personalization.text.name_line_2

object
Conditionally returned

Second line of personalized text printed on the card.

Allowable Values:

name_line2.value

fulfillment.card_personalization.text.name_line_3

object
Conditionally returned

Third line of personalized text printed on the card.

Allowable Values:

name_line3.value

fulfillment.shipping

object
Conditionally returned

Specifies shipping details for the card.

Allowable Values:

Existing shipping object

fulfillment.shipping.care_of_line

string
Conditionally returned

The specified value of the C/O (care of) line on the mailing carrier.

Allowable Values:

255 char max

fulfillment.shipping.method

string
Conditionally returned

Specifies the shipping service.

Allowable Values:

FEDEX_EXPEDITED, FEDEX_REGULAR, UPS_EXPEDITED, UPS_REGULAR, USPS_EXPEDITED, USPS_REGULAR

fulfillment.shipping.recipient_address

object
Conditionally returned

Specifies a fulfillment shipping or return address.

Allowable Values:

Valid fulfillment_address_response object

fulfillment.shipping.recipient_address.address1

string
Conditionally returned

Number and street.

Allowable Values:

255 char max

fulfillment.shipping.recipient_address.address2

string
Conditionally returned

Additional address information.

Allowable Values:

255 char max

fulfillment.shipping.recipient_address.city

string
Conditionally returned

City.

Allowable Values:

40 char max

fulfillment.shipping.recipient_address.country

string
Conditionally returned

Country.

Allowable Values:

40 char max

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

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

fulfillment.shipping.recipient_address.first_name

string
Conditionally returned

First name.

Allowable Values:

40 char max

fulfillment.shipping.recipient_address.last_name

string
Conditionally returned

Last name.

Allowable Values:

40 char max

fulfillment.shipping.recipient_address.middle_name

string
Conditionally returned

Middle name.

Allowable Values:

40 char max

fulfillment.shipping.recipient_address.phone

string
Conditionally returned

Telephone number.

Allowable Values:

20 char max

fulfillment.shipping.recipient_address.postal_code

string
Conditionally returned

Postal code.

Allowable Values:

10 char max

fulfillment.shipping.recipient_address.state

string
Conditionally returned

State.

Allowable Values:

32 char max

fulfillment.shipping.recipient_address.zip

string
Conditionally returned

United States ZIP code.

Allowable Values:

10 char max

fulfillment.shipping.return_address

object
Conditionally returned

Specifies a fulfillment shipping or return address.

Allowable Values:

Valid fulfillment_address_response object

fulfillment.shipping.return_address.address1

string
Conditionally returned

Number and street.

Allowable Values:

255 char max

fulfillment.shipping.return_address.address2

string
Conditionally returned

Additional address information.

Allowable Values:

255 char max

fulfillment.shipping.return_address.city

string
Conditionally returned

City.

Allowable Values:

40 char max

fulfillment.shipping.return_address.country

string
Conditionally returned

Country.

Allowable Values:

40 char max

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

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

fulfillment.shipping.return_address.first_name

string
Conditionally returned

First name.

Allowable Values:

40 char max

fulfillment.shipping.return_address.last_name

string
Conditionally returned

Last name.

Allowable Values:

40 char max

fulfillment.shipping.return_address.middle_name

string
Conditionally returned

Middle name.

Allowable Values:

40 char max

fulfillment.shipping.return_address.phone

string
Conditionally returned

Telephone number.

Allowable Values:

20 char max

fulfillment.shipping.return_address.postal_code

string
Conditionally returned

Postal code.

Allowable Values:

10 char max

fulfillment.shipping.return_address.state

string
Conditionally returned

State.

Allowable Values:

32 char max

fulfillment.shipping.return_address.zip

string
Conditionally returned

United States ZIP code.

Allowable Values:

10 char max

fulfillment_status

string
Returned

The 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

The 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 PAN.

Allowable Values:

PHYSICAL_MSR, PHYSICAL_ICC, PHYSICAL_CONTACTLESS, PHYSICAL_COMBO, VIRTUAL_PAN

last_four

string
Returned

The last four digits of the card PAN.

Allowable Values:

4 chars

last_modified_time

datetime
Returned

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

Allowable Values:

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

The primary account number (PAN) of the card.

Allowable Values:

16 char max

pin_is_set

boolean
Returned

Specifies if the personal identification number (PIN) has been set for the card.

Allowable Values:

4 chars

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

A descriptive reason for the state of the card.

Allowable Values:

255 char max

token

string
Returned

The unique identifier of the card.

Allowable Values:

Existing card token

translate_pin_from_card_token

string
Conditionally returned

Copies the PIN from the specified source card to the newly created card.

Allowable Values:

Existing card token

user_token

string
Returned

The unique identifier of the cardholder.

Allowable Values:

Existing user token

Sample response body
JSON
Copied

Is this helpful?

Yes
No

Retrieve card by PAN

Action: POST
Endpoint: /cards/getbypan

Retrieves the user_token and card_token for a PAN (card number). In the case of a reissued card, where multiple cards share the same PAN, the information for the most recently issued card is returned.

This request is useful in IVR scenarios where a user has telephoned and identifies the card by the PAN. The retrieval of these tokens is implemented as a POST request because supplying the PAN in the request body is more secure than supplying it in the URL (as would be required with a GET).

Warning
Sending a request to this endpoint requires PCI DSS compliance. You must comply with PCI DSS data security requirements if you want to store, transmit, or process sensitive card data such as the cardholder’s primary account number (PAN), personal identification number (PIN), and card expiration date.
Request body
Fields Description

cvv_number

string
Optional

The 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

The PAN of the card whose information you want to retrieve.

Allowable Values:

16 char max

Send a GET request to /cards/{token}/showpan to retrieve the PAN for a specific card.

Sample request body
JSON
Copied

Is this helpful?

Yes
No
Response body
Fields Description

card_token

string
Returned

The unique identifier of the card.

Allowable Values:

Existing card token

created_time

datetime
Returned

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

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

last_modified_time

datetime
Returned

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

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

user_token

string
Returned

The unique identifier of the cardholder.

Allowable Values:

Existing user token

Sample response body
JSON
Copied

Is this helpful?

Yes
No

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

token

string
Required

The unique identifier of the user whose cards you want to list. Send a GET request to /users to retrieve user tokens.

Allowable Values:

Existing user token

URL query parameters
Fields Description

count

integer
Optional

The number of resources to retrieve.

Allowable Values:

1-10

start_index

integer
Optional

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

Allowable Values:

Any integer

fields

string
Optional

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

Allowable Values:

Comma-delimited list of fields, or blank

sort_by

string
Optional

Use any field in the resource model, or one of the system fields lastModifiedTime or createdTime. Prefix the field name with a hyphen (-) to sort in descending order. Omit the hyphen to sort in ascending order.

Allowable Values:

lastModifiedTime, createdTime, or any field in the resource model

Response body
Fields Description

count

integer
Conditionally returned

The number of resources retrieved.

Allowable Values:

1-10

data

array of objects
Conditionally returned

An array of card objects.

Allowable Values:

Valid cards array

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:

Existing activation_actions object

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.

Allowable Values:

1–36 chars

Existing card token.

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

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

The barcode printed on the card, expressed as numerals.

Allowable Values:

10-20 chars

data[].bulk_issuance_token

string
Conditionally returned

The unique identifier of the bulk card order.

Allowable Values:

1-36 chars

data[].card_product_token

string
Returned

The unique identifier of the card product.

Allowable Values:

1-36 chars

data[].chip_cvv_number

string
Conditionally returned

The three-digit card verification value (ICVV) stored on the chip of the card.

Allowable Values:

3 chars

data[].contactless_exemption_counter

integer
Conditionally returned

A running count of contactless transactions. You can limit the number of contactless transactions that can be performed without issuing a strong customer authentication (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

A running total of money spent in contactless transactions. You can limit the total amount that can be spent in contactless transactions without issuing a strong customer authentication (SCA) challenge at the card product level.

For more information about strong customer authentication, see Card Products.

Allowable Values:

Any integer

data[].created_time

datetime
Returned

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

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

data[].cvv_number

string
Conditionally returned

The 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

The expiration date in MMyy format.

Allowable Values:

Format: MMyy

data[].expiration_time

datetime
Returned

The expiration date and time in UTC format.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

data[].fulfillment

object
Conditionally returned

Determines physical characteristics of a card and shipment information.

Allowable Values:

Existing fulfillment object

data[].fulfillment.card_fulfillment_reason

string
Conditionally returned

A descriptive reason for the card fulfillment.

Allowable Values:

NEW, LOST_STOLEN, EXPIRED

data[].fulfillment.card_personalization

object
Returned

Allows personalized attributes to be added to the card.

Allowable Values:

Valid card_personalization object

data[].fulfillment.card_personalization.carrier

object
Conditionally returned

Specifies attributes of the card carrier.

Allowable Values:

Valid carrier object

data[].fulfillment.card_personalization.carrier.logo_file

string
Conditionally returned

Specifies an image to display on the card carrier.

Allowable Values:

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

data[].fulfillment.card_personalization.carrier.logo_thumbnail_file

string
Conditionally returned

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

Allowable Values:

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

data[].fulfillment.card_personalization.carrier.message_file

string
Conditionally returned

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

Allowable Values:

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

data[].fulfillment.card_personalization.carrier.message_line

string
Conditionally returned

Specifies a custom message that appears on the card carrier.

Allowable Values:

60 char max

data[].fulfillment.card_personalization.carrier.template_id

string
Conditionally returned

Specifies the card carrier template to use.

Allowable Values:

A card carrier template ID

data[].fulfillment.card_personalization.images

object
Conditionally returned

Specifies personalized images that appear on the card. Also specifies attributes of the card carrier, if your fulfillment provider is Perfect Plastic Printing or IDEMIA.

Allowable Values:

Valid images object

data[].fulfillment.card_personalization.images.card

object
Conditionally returned

Specifies personalized images that appear on the card.

Allowable Values:

Valid images.card object

data[].fulfillment.card_personalization.images.carrier

object
Conditionally returned

Specifies personalized images that appear on the card carrier.

Allowable Values:

Valid carrier object

data[].fulfillment.card_personalization.images.carrier_return_window

object
Conditionally returned

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

Allowable Values:

Valid carrier_return_window object

data[].fulfillment.card_personalization.images.signature

object
Conditionally returned

Specifies a PNG image of the cardholder’s signature.

Allowable Values:

Valid signature object

data[].fulfillment.card_personalization.perso_type

string
Conditionally returned

Specifies the type of card personalization.

Allowable Values:

EMBOSS, LASER, FLAT

data[].fulfillment.card_personalization.text

object
Returned

Specifies personalized text that appears on the card.

Allowable Values:

Valid text object

data[].fulfillment.card_personalization.text.name_line_1

object
Returned

First line of personalized text printed on the card.

Allowable Values:

name_line1.value

data[].fulfillment.card_personalization.text.name_line_2

object
Conditionally returned

Second line of personalized text printed on the card.

Allowable Values:

name_line2.value

data[].fulfillment.card_personalization.text.name_line_3

object
Conditionally returned

Third line of personalized text printed on the card.

Allowable Values:

name_line3.value

data[].fulfillment.shipping

object
Conditionally returned

Specifies shipping details for the card.

Allowable Values:

Existing shipping object

data[].fulfillment.shipping.care_of_line

string
Conditionally returned

The specified value of the C/O (care of) line on the mailing carrier.

Allowable Values:

255 char max

data[].fulfillment.shipping.method

string
Conditionally returned

Specifies the shipping service.

Allowable Values:

FEDEX_EXPEDITED, FEDEX_REGULAR, UPS_EXPEDITED, UPS_REGULAR, USPS_EXPEDITED, USPS_REGULAR

data[].fulfillment.shipping.recipient_address

object
Conditionally returned

Specifies a fulfillment shipping or return address.

Allowable Values:

Valid fulfillment_address_response object

data[].fulfillment.shipping.recipient_address.address1

string
Conditionally returned

Number and street.

Allowable Values:

255 char max

data[].fulfillment.shipping.recipient_address.address2

string
Conditionally returned

Additional address information.

Allowable Values:

255 char max

data[].fulfillment.shipping.recipient_address.city

string
Conditionally returned

City.

Allowable Values:

40 char max

data[].fulfillment.shipping.recipient_address.country

string
Conditionally returned

Country.

Allowable Values:

40 char max

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

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

data[].fulfillment.shipping.recipient_address.first_name

string
Conditionally returned

First name.

Allowable Values:

40 char max

data[].fulfillment.shipping.recipient_address.last_name

string
Conditionally returned

Last name.

Allowable Values:

40 char max

data[].fulfillment.shipping.recipient_address.middle_name

string
Conditionally returned

Middle name.

Allowable Values:

40 char max

data[].fulfillment.shipping.recipient_address.phone

string
Conditionally returned

Telephone number.

Allowable Values:

20 char max

data[].fulfillment.shipping.recipient_address.postal_code

string
Conditionally returned

Postal code.

Allowable Values:

10 char max

data[].fulfillment.shipping.recipient_address.state

string
Conditionally returned

State.

Allowable Values:

32 char max

data[].fulfillment.shipping.recipient_address.zip

string
Conditionally returned

United States ZIP code.

Allowable Values:

10 char max

data[].fulfillment.shipping.return_address

object
Conditionally returned

Specifies a fulfillment shipping or return address.

Allowable Values:

Valid fulfillment_address_response object

data[].fulfillment.shipping.return_address.address1

string
Conditionally returned

Number and street.

Allowable Values:

255 char max

data[].fulfillment.shipping.return_address.address2

string
Conditionally returned

Additional address information.

Allowable Values:

255 char max

data[].fulfillment.shipping.return_address.city

string
Conditionally returned

City.

Allowable Values:

40 char max

data[].fulfillment.shipping.return_address.country

string
Conditionally returned

Country.

Allowable Values:

40 char max

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

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

data[].fulfillment.shipping.return_address.first_name

string
Conditionally returned

First name.

Allowable Values:

40 char max

data[].fulfillment.shipping.return_address.last_name

string
Conditionally returned

Last name.

Allowable Values:

40 char max

data[].fulfillment.shipping.return_address.middle_name

string
Conditionally returned

Middle name.

Allowable Values:

40 char max

data[].fulfillment.shipping.return_address.phone

string
Conditionally returned

Telephone number.

Allowable Values:

20 char max

data[].fulfillment.shipping.return_address.postal_code

string
Conditionally returned

Postal code.

Allowable Values:

10 char max

data[].fulfillment.shipping.return_address.state

string
Conditionally returned

State.

Allowable Values:

32 char max

data[].fulfillment.shipping.return_address.zip

string
Conditionally returned

United States ZIP code.

Allowable Values:

10 char max

data[].fulfillment_status

string
Returned

The 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

The 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 PAN.

Allowable Values:

PHYSICAL_MSR, PHYSICAL_ICC, PHYSICAL_CONTACTLESS, PHYSICAL_COMBO, VIRTUAL_PAN

data[].last_four

string
Returned

The last four digits of the card PAN.

Allowable Values:

4 chars

data[].last_modified_time

datetime
Returned

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

Allowable Values:

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

The primary account number (PAN) of the card.

Allowable Values:

16 char max

data[].pin_is_set

boolean
Returned

Specifies if the personal identification number (PIN) has been set for the card.

Allowable Values:

4 chars

data[].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

A descriptive reason for the state of the card.

Allowable Values:

255 char max

data[].token

string
Returned

The unique identifier of the card.

Allowable Values:

Existing card token

data[].translate_pin_from_card_token

string
Conditionally returned

Copies the PIN from the specified source card to the newly created card.

Allowable Values:

Existing card token

data[].user_token

string
Returned

The unique identifier of the cardholder.

Allowable Values:

Existing user token

end_index

integer
Conditionally returned

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

Allowable Values:

Any integer

is_more

boolean
Conditionally returned

A value of true indicates that more unreturned resources exist.

Allowable Values:

true, false

start_index

integer
Conditionally returned

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

Allowable Values:

Any integer

Sample response body
JSON
Copied

Is this helpful?

Yes
No

Retrieve card

Action: GET
Endpoint: /cards/{token}

Retrieves a specific card.

This endpoint supports field filtering and object expansion.

URL path parameters
Fields Description

token

string
Required

The unique identifier of the card you want to retrieve.

Allowable Values:

Existing card token

URL query parameters
Fields Description

fields

string
Optional

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

Allowable Values:

Comma-delimited list of fields, or blank

expand

string
Optional

Embeds the associated object of the specified type into the response, for all GET /cards endpoints.

Allowable Values:

user, cardproduct

Response body
Fields Description

activation_actions

object
Conditionally returned

Defines actions to execute when the card is activated. The fields in this object are mutually exclusive.

Allowable Values:

Existing activation_actions object

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.

Allowable Values:

1–36 chars

Existing card token.

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

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

The barcode printed on the card, expressed as numerals.

Allowable Values:

10-20 chars

bulk_issuance_token

string
Conditionally returned

The unique identifier of the bulk card order.

Allowable Values:

1-36 chars

card_product_token

string
Returned

The unique identifier of the card product.

Allowable Values:

1-36 chars

chip_cvv_number

string
Conditionally returned

The three-digit card verification value (ICVV) stored on the chip of the card.

Allowable Values:

3 chars

contactless_exemption_counter

integer
Conditionally returned

A running count of contactless transactions. You can limit the number of contactless transactions that can be performed without issuing a strong customer authentication (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

A running total of money spent in contactless transactions. You can limit the total amount that can be spent in contactless transactions without issuing a strong customer authentication (SCA) challenge at the card product level.

For more information about strong customer authentication, see Card Products.

Allowable Values:

Any integer

created_time

datetime
Returned

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

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

cvv_number

string
Conditionally returned

The 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

The expiration date in MMyy format.

Allowable Values:

Format: MMyy

expiration_time

datetime
Returned

The expiration date and time in UTC format.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

fulfillment

object
Conditionally returned

Determines physical characteristics of a card and shipment information.

Allowable Values:

Existing fulfillment object

fulfillment.card_fulfillment_reason

string
Conditionally returned

A descriptive reason for the card fulfillment.

Allowable Values:

NEW, LOST_STOLEN, EXPIRED

fulfillment.card_personalization

object
Returned

Allows personalized attributes to be added to the card.

Allowable Values:

Valid card_personalization object

fulfillment.card_personalization.carrier

object
Conditionally returned

Specifies attributes of the card carrier.

Allowable Values:

Valid carrier object

fulfillment.card_personalization.carrier.logo_file

string
Conditionally returned

Specifies an image to display on the card carrier.

Allowable Values:

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

fulfillment.card_personalization.carrier.logo_thumbnail_file

string
Conditionally returned

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

Allowable Values:

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

fulfillment.card_personalization.carrier.message_file

string
Conditionally returned

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

Allowable Values:

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

fulfillment.card_personalization.carrier.message_line

string
Conditionally returned

Specifies a custom message that appears on the card carrier.

Allowable Values:

60 char max

fulfillment.card_personalization.carrier.template_id

string
Conditionally returned

Specifies the card carrier template to use.

Allowable Values:

A card carrier template ID

fulfillment.card_personalization.images

object
Conditionally returned

Specifies personalized images that appear on the card. Also specifies attributes of the card carrier, if your fulfillment provider is Perfect Plastic Printing or IDEMIA.

Allowable Values:

Valid images object

fulfillment.card_personalization.images.card

object
Conditionally returned

Specifies personalized images that appear on the card.

Allowable Values:

Valid images.card object

fulfillment.card_personalization.images.carrier

object
Conditionally returned

Specifies personalized images that appear on the card carrier.

Allowable Values:

Valid carrier object

fulfillment.card_personalization.images.carrier_return_window

object
Conditionally returned

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

Allowable Values:

Valid carrier_return_window object

fulfillment.card_personalization.images.signature

object
Conditionally returned

Specifies a PNG image of the cardholder’s signature.

Allowable Values:

Valid signature object

fulfillment.card_personalization.perso_type

string
Conditionally returned

Specifies the type of card personalization.

Allowable Values:

EMBOSS, LASER, FLAT

fulfillment.card_personalization.text

object
Returned

Specifies personalized text that appears on the card.

Allowable Values:

Valid text object

fulfillment.card_personalization.text.name_line_1

object
Returned

First line of personalized text printed on the card.

Allowable Values:

name_line1.value

fulfillment.card_personalization.text.name_line_2

object
Conditionally returned

Second line of personalized text printed on the card.

Allowable Values:

name_line2.value

fulfillment.card_personalization.text.name_line_3

object
Conditionally returned

Third line of personalized text printed on the card.

Allowable Values:

name_line3.value

fulfillment.shipping

object
Conditionally returned

Specifies shipping details for the card.

Allowable Values:

Existing shipping object

fulfillment.shipping.care_of_line

string
Conditionally returned

The specified value of the C/O (care of) line on the mailing carrier.

Allowable Values:

255 char max

fulfillment.shipping.method

string
Conditionally returned

Specifies the shipping service.

Allowable Values:

FEDEX_EXPEDITED, FEDEX_REGULAR, UPS_EXPEDITED, UPS_REGULAR, USPS_EXPEDITED, USPS_REGULAR

fulfillment.shipping.recipient_address

object
Conditionally returned

Specifies a fulfillment shipping or return address.

Allowable Values:

Valid fulfillment_address_response object

fulfillment.shipping.recipient_address.address1

string
Conditionally returned

Number and street.

Allowable Values:

255 char max

fulfillment.shipping.recipient_address.address2

string
Conditionally returned

Additional address information.

Allowable Values:

255 char max

fulfillment.shipping.recipient_address.city

string
Conditionally returned

City.

Allowable Values:

40 char max

fulfillment.shipping.recipient_address.country

string
Conditionally returned

Country.

Allowable Values:

40 char max

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

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

fulfillment.shipping.recipient_address.first_name

string
Conditionally returned

First name.

Allowable Values:

40 char max

fulfillment.shipping.recipient_address.last_name

string
Conditionally returned

Last name.

Allowable Values:

40 char max

fulfillment.shipping.recipient_address.middle_name

string
Conditionally returned

Middle name.

Allowable Values:

40 char max

fulfillment.shipping.recipient_address.phone

string
Conditionally returned

Telephone number.

Allowable Values:

20 char max

fulfillment.shipping.recipient_address.postal_code

string
Conditionally returned

Postal code.

Allowable Values:

10 char max

fulfillment.shipping.recipient_address.state

string
Conditionally returned

State.

Allowable Values:

32 char max

fulfillment.shipping.recipient_address.zip

string
Conditionally returned

United States ZIP code.

Allowable Values:

10 char max

fulfillment.shipping.return_address

object
Conditionally returned

Specifies a fulfillment shipping or return address.

Allowable Values:

Valid fulfillment_address_response object

fulfillment.shipping.return_address.address1

string
Conditionally returned

Number and street.

Allowable Values:

255 char max

fulfillment.shipping.return_address.address2

string
Conditionally returned

Additional address information.

Allowable Values:

255 char max

fulfillment.shipping.return_address.city

string
Conditionally returned

City.

Allowable Values:

40 char max

fulfillment.shipping.return_address.country

string
Conditionally returned

Country.

Allowable Values:

40 char max

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

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

fulfillment.shipping.return_address.first_name

string
Conditionally returned

First name.

Allowable Values:

40 char max

fulfillment.shipping.return_address.last_name

string
Conditionally returned

Last name.

Allowable Values:

40 char max

fulfillment.shipping.return_address.middle_name

string
Conditionally returned

Middle name.

Allowable Values:

40 char max

fulfillment.shipping.return_address.phone

string
Conditionally returned

Telephone number.

Allowable Values:

20 char max

fulfillment.shipping.return_address.postal_code

string
Conditionally returned

Postal code.

Allowable Values:

10 char max

fulfillment.shipping.return_address.state

string
Conditionally returned

State.

Allowable Values:

32 char max

fulfillment.shipping.return_address.zip

string
Conditionally returned

United States ZIP code.

Allowable Values:

10 char max

fulfillment_status

string
Returned

The 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

The 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 PAN.

Allowable Values:

PHYSICAL_MSR, PHYSICAL_ICC, PHYSICAL_CONTACTLESS, PHYSICAL_COMBO, VIRTUAL_PAN

last_four

string
Returned

The last four digits of the card PAN.

Allowable Values:

4 chars

last_modified_time

datetime
Returned

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

Allowable Values:

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

The primary account number (PAN) of the card.

Allowable Values:

16 char max

pin_is_set

boolean
Returned

Specifies if the personal identification number (PIN) has been set for the card.

Allowable Values:

4 chars

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

A descriptive reason for the state of the card.

Allowable Values:

255 char max

token

string
Returned

The unique identifier of the card.

Allowable Values:

Existing card token

translate_pin_from_card_token

string
Conditionally returned

Copies the PIN from the specified source card to the newly created card.

Allowable Values:

Existing card token

user_token

string
Returned

The unique identifier of the cardholder.

Allowable Values:

Existing user token

Sample response body
JSON
Copied

Is this helpful?

Yes
No

Update card

Action: PUT
Endpoint: /cards/{token}

Updates the details of an existing card.

URL path parameters
Fields Description

token

string
Required

The unique identifier of the card you want to update.

Allowable Values:

Existing card token

Request body
Fields Description

expedite

boolean
Optional

Set to true to request expedited processing of the card by your card fulfillment provider.

This expedited service is available for cards fulfilled by Perfect Plastic Printing, IDEMIA, and Arroweye Solutions.

NOTE: Contact your Marqeta representative for information regarding the cost of expedited service.

Allowable Values:

true, false

Default value:
false

fulfillment

object
Optional

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

Allowable Values:

Existing fulfillment object

fulfillment.card_fulfillment_reason

string
Optional

The reason for card fulfillment.

Allowable Values:

NEW, LOST_STOLEN, EXPIRED

fulfillment.card_personalization

object
Required

Allows personalized attributes to be added to the card.

Allowable Values:

Valid card_personalization object

fulfillment.card_personalization.carrier

object
Optional

Specifies attributes of the card carrier.

Allowable Values:

Valid carrier object

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

string
Optional

Specifies the card carrier template to use.

Allowable Values:

A card carrier template ID

fulfillment.card_personalization.images

object
Optional

Specifies personalized images that appear on the card. Also specifies attributes of the card carrier, if your fulfillment provider is Perfect Plastic Printing or IDEMIA.

Allowable Values:

Valid images object

fulfillment.card_personalization.images.card

object
Optional

Specifies personalized images that appear on the card.

Allowable Values:

Valid images.card object

fulfillment.card_personalization.images.carrier

object
Optional

Specifies personalized images that appear on the card carrier.

Allowable Values:

Valid carrier object

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:

Valid carrier_return_window object

fulfillment.card_personalization.images.signature

object
Optional

Specifies a PNG image of the cardholder’s signature.

Allowable Values:

Valid signature object

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:

Valid text object

fulfillment.card_personalization.text.name_line_1

object
Required

First line of personalized text printed on the card.

Allowable Values:

name_line1.value

fulfillment.card_personalization.text.name_line_2

object
Optional

Second line of personalized text printed on the card.

Allowable Values:

name_line2.value

fulfillment.card_personalization.text.name_line_3

object
Optional

Third line of personalized text printed on the card.

Allowable Values:

name_line3.value

fulfillment.shipping

object
Optional

Specifies the shipping details for the card.

Allowable Values:

Valid shipping object

fulfillment.shipping.care_of_line

string
Optional

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

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

Allowable Values:

255 char max

fulfillment.shipping.method

string
Optional

Specifies the shipping service.

Allowable Values:

LOCAL_MAIL, GROUND, TWO_DAY, OVERNIGHT, INTERNATIONAL, FEDEX_EXPEDITED, FEDEX_REGULAR, UPS_EXPEDITED, UPS_REGULAR, USPS_EXPEDITED, USPS_REGULAR

Shipping options vary by card provider. For details on the specific shipping companies and services offered by your card provider, contact your Marqeta representative.

fulfillment.shipping.recipient_address

object
Optional

Address to which the card will be shipped.

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

Allowable Values:

Valid recipient_address object

fulfillment.shipping.recipient_address.address1

string
Optional

Number and street.

Allowable Values:

255 char max

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

fulfillment.shipping.recipient_address.address2

string
Optional

Additional address information.

Allowable Values:

255 char max

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

fulfillment.shipping.recipient_address.city

string
Optional

City.

Allowable Values:

40 char max

fulfillment.shipping.recipient_address.country

string
Optional

Country.

Allowable Values:

40 char max

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

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

fulfillment.shipping.recipient_address.first_name

string
Optional

First name.

Allowable Values:

40 char max

fulfillment.shipping.recipient_address.last_name

string
Optional

Last name.

Allowable Values:

40 char max

fulfillment.shipping.recipient_address.middle_name

string
Optional

Middle name.

Allowable Values:

40 char max

fulfillment.shipping.recipient_address.phone

string
Optional

Telephone number.

Allowable Values:

20 char max

fulfillment.shipping.recipient_address.postal_code

string
Optional

Postal code.

Allowable Values:

10 char max

fulfillment.shipping.recipient_address.state

string
Optional

State.

Allowable Values:

32 char max

fulfillment.shipping.recipient_address.zip

string
Optional

United States ZIP code.

Allowable Values:

10 char max

fulfillment.shipping.return_address

object
Optional

Address to which cards will be returned if shipping fails.

Allowable Values:

Valid return_address object

fulfillment.shipping.return_address.address1

string
Optional

Number and street.

Allowable Values:

255 char max

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

fulfillment.shipping.return_address.address2

string
Optional

Additional address information.

Allowable Values:

255 char max

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

fulfillment.shipping.return_address.city

string
Optional

City.

Allowable Values:

40 char max

fulfillment.shipping.return_address.country

string
Optional

Country.

Allowable Values:

40 char max

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

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

fulfillment.shipping.return_address.first_name

string
Optional

First name.

Allowable Values:

40 char max

fulfillment.shipping.return_address.last_name

string
Optional

Last name.

Allowable Values:

40 char max

fulfillment.shipping.return_address.middle_name

string
Optional

Middle name.

Allowable Values:

40 char max

fulfillment.shipping.return_address.phone

string
Optional

Telephone number.

Allowable Values:

20 char max

fulfillment.shipping.return_address.postal_code

string
Optional

Postal code.

Allowable Values:

10 char max

fulfillment.shipping.return_address.state

string
Optional

State.

Allowable Values:

32 char max

fulfillment.shipping.return_address.zip

string
Optional

United States ZIP code.

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

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

Is this helpful?

Yes
No
Response body
Fields Description

activation_actions

object
Conditionally returned

Defines actions to execute when the card is activated. The fields in this object are mutually exclusive.

Allowable Values:

Existing activation_actions object

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.

Allowable Values:

1–36 chars

Existing card token.

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

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

The barcode printed on the card, expressed as numerals.

Allowable Values:

10-20 chars

bulk_issuance_token

string
Conditionally returned

The unique identifier of the bulk card order.

Allowable Values:

1-36 chars

card_product_token

string
Returned

The unique identifier of the card product.

Allowable Values:

1-36 chars

chip_cvv_number

string
Conditionally returned

The three-digit card verification value (ICVV) stored on the chip of the card.

Allowable Values:

3 chars

contactless_exemption_counter

integer
Conditionally returned

A running count of contactless transactions. You can limit the number of contactless transactions that can be performed without issuing a strong customer authentication (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

A running total of money spent in contactless transactions. You can limit the total amount that can be spent in contactless transactions without issuing a strong customer authentication (SCA) challenge at the card product level.

For more information about strong customer authentication, see Card Products.

Allowable Values:

Any integer

created_time

datetime
Returned

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

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

cvv_number

string
Conditionally returned

The 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

The expiration date in MMyy format.

Allowable Values:

Format: MMyy

expiration_time

datetime
Returned

The expiration date and time in UTC format.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

fulfillment

object
Conditionally returned

Determines physical characteristics of a card and shipment information.

Allowable Values:

Existing fulfillment object

fulfillment.card_fulfillment_reason

string
Conditionally returned

A descriptive reason for the card fulfillment.

Allowable Values:

NEW, LOST_STOLEN, EXPIRED

fulfillment.card_personalization

object
Returned

Allows personalized attributes to be added to the card.

Allowable Values:

Valid card_personalization object

fulfillment.card_personalization.carrier

object
Conditionally returned

Specifies attributes of the card carrier.

Allowable Values:

Valid carrier object

fulfillment.card_personalization.carrier.logo_file

string
Conditionally returned

Specifies an image to display on the card carrier.

Allowable Values:

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

fulfillment.card_personalization.carrier.logo_thumbnail_file

string
Conditionally returned

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

Allowable Values:

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

fulfillment.card_personalization.carrier.message_file

string
Conditionally returned

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

Allowable Values:

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

fulfillment.card_personalization.carrier.message_line

string
Conditionally returned

Specifies a custom message that appears on the card carrier.

Allowable Values:

60 char max

fulfillment.card_personalization.carrier.template_id

string
Conditionally returned

Specifies the card carrier template to use.

Allowable Values:

A card carrier template ID

fulfillment.card_personalization.images

object
Conditionally returned

Specifies personalized images that appear on the card. Also specifies attributes of the card carrier, if your fulfillment provider is Perfect Plastic Printing or IDEMIA.

Allowable Values:

Valid images object

fulfillment.card_personalization.images.card

object
Conditionally returned

Specifies personalized images that appear on the card.

Allowable Values:

Valid images.card object

fulfillment.card_personalization.images.carrier

object
Conditionally returned

Specifies personalized images that appear on the card carrier.

Allowable Values:

Valid carrier object

fulfillment.card_personalization.images.carrier_return_window

object
Conditionally returned

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

Allowable Values:

Valid carrier_return_window object

fulfillment.card_personalization.images.signature

object
Conditionally returned

Specifies a PNG image of the cardholder’s signature.

Allowable Values:

Valid signature object

fulfillment.card_personalization.perso_type

string
Conditionally returned

Specifies the type of card personalization.

Allowable Values:

EMBOSS, LASER, FLAT

fulfillment.card_personalization.text

object
Returned

Specifies personalized text that appears on the card.

Allowable Values:

Valid text object

fulfillment.card_personalization.text.name_line_1

object
Returned

First line of personalized text printed on the card.

Allowable Values:

name_line1.value

fulfillment.card_personalization.text.name_line_2

object
Conditionally returned

Second line of personalized text printed on the card.

Allowable Values:

name_line2.value

fulfillment.card_personalization.text.name_line_3

object
Conditionally returned

Third line of personalized text printed on the card.

Allowable Values:

name_line3.value

fulfillment.shipping

object
Conditionally returned

Specifies shipping details for the card.

Allowable Values:

Existing shipping object

fulfillment.shipping.care_of_line

string
Conditionally returned

The specified value of the C/O (care of) line on the mailing carrier.

Allowable Values:

255 char max

fulfillment.shipping.method

string
Conditionally returned

Specifies the shipping service.

Allowable Values:

FEDEX_EXPEDITED, FEDEX_REGULAR, UPS_EXPEDITED, UPS_REGULAR, USPS_EXPEDITED, USPS_REGULAR

fulfillment.shipping.recipient_address

object
Conditionally returned

Specifies a fulfillment shipping or return address.

Allowable Values:

Valid fulfillment_address_response object

fulfillment.shipping.recipient_address.address1

string
Conditionally returned

Number and street.

Allowable Values:

255 char max

fulfillment.shipping.recipient_address.address2

string
Conditionally returned

Additional address information.

Allowable Values:

255 char max

fulfillment.shipping.recipient_address.city

string
Conditionally returned

City.

Allowable Values:

40 char max

fulfillment.shipping.recipient_address.country

string
Conditionally returned

Country.

Allowable Values:

40 char max

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

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

fulfillment.shipping.recipient_address.first_name

string
Conditionally returned

First name.

Allowable Values:

40 char max

fulfillment.shipping.recipient_address.last_name

string
Conditionally returned

Last name.

Allowable Values:

40 char max

fulfillment.shipping.recipient_address.middle_name

string
Conditionally returned

Middle name.

Allowable Values:

40 char max

fulfillment.shipping.recipient_address.phone

string
Conditionally returned

Telephone number.

Allowable Values:

20 char max

fulfillment.shipping.recipient_address.postal_code

string
Conditionally returned

Postal code.

Allowable Values:

10 char max

fulfillment.shipping.recipient_address.state

string
Conditionally returned

State.

Allowable Values:

32 char max

fulfillment.shipping.recipient_address.zip

string
Conditionally returned

United States ZIP code.

Allowable Values:

10 char max

fulfillment.shipping.return_address

object
Conditionally returned

Specifies a fulfillment shipping or return address.

Allowable Values:

Valid fulfillment_address_response object

fulfillment.shipping.return_address.address1

string
Conditionally returned

Number and street.

Allowable Values:

255 char max

fulfillment.shipping.return_address.address2

string
Conditionally returned

Additional address information.

Allowable Values:

255 char max

fulfillment.shipping.return_address.city

string
Conditionally returned

City.

Allowable Values:

40 char max

fulfillment.shipping.return_address.country

string
Conditionally returned

Country.

Allowable Values:

40 char max

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

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

fulfillment.shipping.return_address.first_name

string
Conditionally returned

First name.

Allowable Values:

40 char max

fulfillment.shipping.return_address.last_name

string
Conditionally returned

Last name.

Allowable Values:

40 char max

fulfillment.shipping.return_address.middle_name

string
Conditionally returned

Middle name.

Allowable Values:

40 char max

fulfillment.shipping.return_address.phone

string
Conditionally returned

Telephone number.

Allowable Values:

20 char max

fulfillment.shipping.return_address.postal_code

string
Conditionally returned

Postal code.

Allowable Values:

10 char max

fulfillment.shipping.return_address.state

string
Conditionally returned

State.

Allowable Values:

32 char max

fulfillment.shipping.return_address.zip

string
Conditionally returned

United States ZIP code.

Allowable Values:

10 char max

fulfillment_status

string
Returned

The 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

The 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 PAN.

Allowable Values:

PHYSICAL_MSR, PHYSICAL_ICC, PHYSICAL_CONTACTLESS, PHYSICAL_COMBO, VIRTUAL_PAN

last_four

string
Returned

The last four digits of the card PAN.

Allowable Values:

4 chars

last_modified_time

datetime
Returned

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

Allowable Values:

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

The primary account number (PAN) of the card.

Allowable Values:

16 char max

pin_is_set

boolean
Returned

Specifies if the personal identification number (PIN) has been set for the card.

Allowable Values:

4 chars

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

A descriptive reason for the state of the card.

Allowable Values:

255 char max

token

string
Returned

The unique identifier of the card.

Allowable Values:

Existing card token

translate_pin_from_card_token

string
Conditionally returned

Copies the PIN from the specified source card to the newly created card.

Allowable Values:

Existing card token

user_token

string
Returned

The unique identifier of the cardholder.

Allowable Values:

Existing user token

Sample response body
JSON
Copied

Is this helpful?

Yes
No

Show card PAN

Action: GET
Endpoint: /cards/{token}/showpan

Retrieves a PAN (card number). 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
Fields Description

token

string
Required

The unique identifier of the card whose PAN you want to retrieve. Send a GET request to /cards to retrieve card tokens.

Allowable Values:

Existing card token

URL query parameters
Fields Description

fields

string
Optional

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

Allowable Values:

Comma-delimited list of fields, or blank

show_cvv_number

boolean
Optional

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

Allowable Values:

true, false

Response body
Fields Description

activation_actions

object
Conditionally returned

Defines actions to execute when the card is activated. The fields in this object are mutually exclusive.

Allowable Values:

Existing activation_actions object

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.

Allowable Values:

1–36 chars

Existing card token.

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

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