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
Copy section link
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’sconfig.card_life_cycle.activate_upon_issue field (see Card Products).
Send a POST request to /pins/controltoken to set the card’s personal identification number (PIN) if your program requires PIN numbers (for example, for Europay Mastercard and Visa cards); this action updates the pin_is_set field to true.
See Create or Update PIN for details.
You can use optional query parameters to show the primary account number (PAN) and card verification value (CVV2) number in the response.
If show_pan and show_cvv_number are set to true, the fulfillment state of the card is DIGITALLY_PRESENTED instead of the typical initial state of ISSUED.
This fulfillment state does not affect the delivery of physical cards.
This endpoint requires PCI DSS compliance if show_pan and show_cvv_number are set to true.
You must comply with PCI DSS data security requirements if you store, transmit, or process sensitive card data.
URL query parameters
Copy section link
| Fields | Description |
|---|---|
show_cvv_number
boolean
|
Set to Allowable Values:
|
show_pan
boolean
|
Set to Allowable Values:
|
Request body
Copy section link
| Fields | Description |
|---|---|
activation_actions
object
|
Defines actions to execute when the card is activated. The fields in this object are mutually exclusive. Allowable Values:
|
activation_actions.swap_digital_wallet_tokens_from_card_token
string
|
Moves all digital wallet tokens from the specified card to the new card. Not relevant when Send a Allowable Values: 1–36 chars Existing card token |
activation_actions.terminate_reissued_source_card
boolean
|
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 Only relevant when Allowable Values:
Default value: |
bulk_issuance_token
string
|
Associates the card with the specified bulk card order. This field cannot be updated. Allowable Values: 36 char max |
card_product_token
string
|
Unique identifier of the card product. Allowable Values: 1–36 chars Existing card product token. Send a |
expedite
boolean
|
Set to 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:
Default value: |
expiration_offset
object
|
Specifies the length of time after the date of issue for which the cards are valid. Allowable Values:
|
expiration_offset.unit
string
|
Specifies the units for the Allowable Values:
Default value: |
expiration_offset.value
integer
|
Specifies the number of time units (as defined by the This number is rounded as follows:
Allowable Values: Any positive integer Default value: |
fulfillment
object
|
Specifies certain physical characteristics of a card, as well as shipment information. Allowable Values:
|
fulfillment.card_fulfillment_reason
string
|
Reason for card fulfillment. Allowable Values:
|
fulfillment.card_personalization
object
|
Specifies personalized attributes to be added to the card. Allowable Values:
|
fulfillment.card_personalization.carrier
object
|
Specifies attributes of the card carrier. Allowable Values:
|
fulfillment.card_personalization.carrier.logo_file
string
|
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
|
Specifies a thumbnail-sized rendering of the image specified in the 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
|
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
|
Specifies a custom message that appears on the card carrier. Allowable Values: 60 char max |
fulfillment.card_personalization.carrier.template_id
string
|
Specifies the card carrier template to use. Allowable Values: Card carrier template ID |
fulfillment.card_personalization.images
object
|
Specifies personalized images that appear on the card. Allowable Values:
|
fulfillment.card_personalization.images.card
object
|
Specifies personalized images that appear on the card. Allowable Values:
|
fulfillment.card_personalization.images.card.name
string
|
Specifies a PNG image to display on the card. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
fulfillment.card_personalization.images.card.thermal_color
string
|
Specifies the color of the image displayed on the card. Allowable Values: Contains the name of the color and must match one of the provider’s predefined colors. |
fulfillment.card_personalization.images.carrier
object
|
Specifies personalized images that appear on the card carrier. Allowable Values:
|
fulfillment.card_personalization.images.carrier.message_1
string
|
Specifies a custom message that appears on the card carrier. Allowable Values: 60 char max |
fulfillment.card_personalization.images.carrier.name
string
|
Specifies a PNG image to display on the card carrier. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
fulfillment.card_personalization.images.carrier_return_window
object
|
Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders. Allowable Values:
|
fulfillment.card_personalization.images.carrier_return_window.name
string
|
Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
fulfillment.card_personalization.images.signature
object
|
Specifies a PNG image of the cardholder’s signature. Allowable Values:
|
fulfillment.card_personalization.images.signature.name
string
|
Specifies a PNG image of the cardholder’s signature. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
fulfillment.card_personalization.perso_type
string
|
Specifies the type of card personalization. Allowable Values:
|
fulfillment.card_personalization.text
object
|
Specifies personalized text that appears on the card. Allowable Values:
|
fulfillment.card_personalization.text.name_line_1
object
|
Specifies the first line of personalized text that appears on the card. Allowable Values:
21 char max; if Strings longer than the character limit are truncated. |
fulfillment.card_personalization.text.name_line_1.value
string
|
Line of personalized text printed on the card. Allowable Values: 21 char max |
fulfillment.card_personalization.text.name_line_2
object
|
Specifies the second line of personalized text that appears on the card. Allowable Values:
|
fulfillment.card_personalization.text.name_line_2.value
string
|
Line of personalized text printed on the card. Allowable Values: 21 char max |
fulfillment.card_personalization.text.name_line_3
object
|
Specifies the third line of personalized text that appears on the card. Allowable Values:
|
fulfillment.card_personalization.text.name_line_3.value
string
|
Line of personalized text printed on the card. Allowable Values: 21 char max |
fulfillment.shipping
object
|
Specifies shipping details for the order. Allowable Values:
|
fulfillment.shipping.care_of_line
string
|
Adds the specified value as a care of (C/O) line to the mailing carrier. NOTE: This field can be specified on cards, card products, and bulk card orders. If you specify this field at multiple levels, the order of precedence is: card, bulk card order, card product. Allowable Values: 255 char max |
fulfillment.shipping.method
string
|
Specifies the shipping service. Allowable Values:
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
|
Address to which the order will be shipped. In order to generate cards, a valid shipping address must be provided by one of these:
The order of precedence from highest to lowest is card, user, card product.
To be valid, an address must have the Allowable Values: Valid |
fulfillment.shipping.recipient_address.address1
string
|
Number and street of the address. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters. |
fulfillment.shipping.recipient_address.address2
string
|
Additional address information. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters. |
fulfillment.shipping.recipient_address.city
string
|
City of the address. Allowable Values: 40 char max |
fulfillment.shipping.recipient_address.country
string
|
Country of the address. Allowable Values: 40 char max English short name. For example, for the Kingdom of Spain, use the English short name "Spain". The ISO maintains the full list of country codes. |
fulfillment.shipping.recipient_address.first_name
string
|
First name of the addressee. Allowable Values: 40 char max |
fulfillment.shipping.recipient_address.last_name
string
|
Last name of the addressee. Allowable Values: 40 char max |
fulfillment.shipping.recipient_address.middle_name
string
|
Middle name of the addressee. Allowable Values: 40 char max |
fulfillment.shipping.recipient_address.phone
string
|
Telephone number of the addressee. Allowable Values: 20 char max |
fulfillment.shipping.recipient_address.postal_code
string
|
Postal code of the address. Allowable Values: 10 char max |
fulfillment.shipping.recipient_address.state
string
|
State of the address. Allowable Values: 32 char max |
fulfillment.shipping.recipient_address.zip
string
|
United States ZIP code of the address. Allowable Values: 10 char max |
fulfillment.shipping.return_address
object
|
Address to which the order will be returned if shipping fails. Allowable Values:
|
fulfillment.shipping.return_address.address1
string
|
Number and street of the address. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters. |
fulfillment.shipping.return_address.address2
string
|
Additional address information. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters. |
fulfillment.shipping.return_address.city
string
|
City of the address. Allowable Values: 40 char max |
fulfillment.shipping.return_address.country
string
|
Country of the address. Allowable Values: 40 char max English short name. For example, for the Kingdom of Spain, use the English short name "Spain". The ISO maintains the full list of country codes. |
fulfillment.shipping.return_address.first_name
string
|
First name of the addressee. Allowable Values: 40 char max |
fulfillment.shipping.return_address.last_name
string
|
Last name of the addressee. Allowable Values: 40 char max |
fulfillment.shipping.return_address.middle_name
string
|
Middle name of the addressee. Allowable Values: 40 char max |
fulfillment.shipping.return_address.phone
string
|
Telephone number of the addressee. Allowable Values: 20 char max |
fulfillment.shipping.return_address.postal_code
string
|
Postal code of the address. Allowable Values: 10 char max |
fulfillment.shipping.return_address.state
string
|
State of the address. Allowable Values: 32 char max |
fulfillment.shipping.return_address.zip
string
|
United States ZIP code of the address. Allowable Values: 10 char max |
metadata
object
|
Associates customer-provided metadata with the card. Allowable Values: You can define the names and values of up to 20 fields in the format |
reissue_pan_from_card_token
string
|
Reissues the specified card (known as the "source" card). This field reissues a card by copying the primary account number (PAN) and personal identification number (PIN) from the specified source card to the newly created card. The reissued card has the same PAN and PIN as the source card but a new expiration date and CVV2 number. Send a 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 Allowable Values: 36 char max Existing card token |
new_pan_from_card_token
string
|
Reissues the specified card (known as the "source" card) with a new primary account number (PAN). This field reissues a card with a new PAN from the specified source card. The source card is automatically terminated when the card is reissued with the new PAN. Use this field when reissuing a lost or stolen card. Send a Allowable Values: 36 char max Existing card token |
token
string
|
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
|
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 Send a Allowable Values: 36 char max Existing card token |
user_token
string
|
Unique identifier of the authorized user of the card. Allowable Values: 1–36 chars Existing user token Send a |
Response body
Copy section link
| Fields | Description |
|---|---|
activation_actions
object
|
Defines actions to execute when the card is activated. The fields in this object are mutually exclusive. Allowable Values:
|
activation_actions.swap_digital_wallet_tokens_from_card_token
string
|
Moves all digital wallet tokens from the specified card to the new card. Not relevant when Send a Allowable Values: 1–36 chars Existing card token |
activation_actions.terminate_reissued_source_card
boolean
|
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 Only relevant when Allowable Values:
Default value: |
barcode
string
|
Barcode printed on the card, expressed as numerals. Allowable Values: 10-20 chars |
bulk_issuance_token
string
|
Unique identifier of the bulk card order. Allowable Values: 1-36 chars |
card_product_token
string
|
Unique identifier of the card product. Allowable Values: 1-36 chars |
chip_cvv_number
string
|
Three-digit card verification value (ICVV) stored on the chip of the card. Allowable Values: 3 chars |
contactless_exemption_counter
integer
|
Running count of the contactless transactions successfully completed since the last strong customer authentication (SCA) challenge was issued. You can limit the number of contactless transactions that can be performed without issuing an SCA challenge at the card product level. For more information about strong customer authentication, see Card Products. Allowable Values: Any integer |
contactless_exemption_total_amount
decimal
|
Running total of the money spent in contactless transactions successfully completed since the last strong customer authentication (SCA) challenge was issued. You can limit the total amount that can be spent in contactless transactions without issuing an SCA challenge at the card product level. For more information about strong customer authentication, see Card Products. Allowable Values: Any integer |
created_time
datetime
|
Date and time when the resource was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
cvv_number
string
|
Three-digit card verification value (CVV2 or CVC2) printed on the card. Allowable Values: 3 chars |
expedite
boolean
|
A value of Allowable Values:
|
expiration
string
|
Expiration date in Allowable Values: Format: MMyy |
expiration_time
datetime
|
Expiration date and time, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
fulfillment
object
|
Determines physical characteristics of a card and shipment information. Allowable Values:
|
fulfillment.card_fulfillment_reason
string
|
Descriptive reason for the card fulfillment. Allowable Values:
|
fulfillment.card_personalization
object
|
Specifies personalized attributes to be added to the card. Allowable Values:
|
fulfillment.card_personalization.carrier
object
|
Specifies attributes of the card carrier. Allowable Values:
|
fulfillment.card_personalization.carrier.logo_file
string
|
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
|
Specifies a thumbnail-sized rendering of the image specified in the 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
|
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
|
Specifies a custom message that appears on the card carrier. Allowable Values: 60 char max |
fulfillment.card_personalization.carrier.template_id
string
|
Specifies the card carrier template to use. Allowable Values: Card carrier template ID |
fulfillment.card_personalization.images
object
|
Specifies personalized images that appear on the card. Allowable Values:
|
fulfillment.card_personalization.images.card
object
|
Specifies personalized images that appear on the card. Allowable Values:
|
fulfillment.card_personalization.images.card.name
string
|
Specifies a PNG image to display on the card. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
fulfillment.card_personalization.images.card.thermal_color
string
|
Specifies the color of the image displayed on the card. Allowable Values: Contains the name of the color and must match one of the provider’s predefined colors. |
fulfillment.card_personalization.images.carrier
object
|
Specifies personalized images that appear on the card carrier. Allowable Values:
|
fulfillment.card_personalization.images.carrier.message_1
string
|
Specifies a custom message that appears on the card carrier. Allowable Values: 60 char max |
fulfillment.card_personalization.images.carrier.name
string
|
Specifies a PNG image to display on the card carrier. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
fulfillment.card_personalization.images.carrier_return_window
object
|
Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders. Allowable Values:
|
fulfillment.card_personalization.images.carrier_return_window.name
string
|
Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
fulfillment.card_personalization.images.signature
object
|
Specifies a PNG image of the cardholder’s signature. Allowable Values:
|
fulfillment.card_personalization.images.signature.name
string
|
Specifies a PNG image of the cardholder’s signature. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
fulfillment.card_personalization.perso_type
string
|
Specifies the type of card personalization. Allowable Values:
|
fulfillment.card_personalization.text
object
|
Specifies personalized text that appears on the card. Allowable Values:
|
fulfillment.card_personalization.text.name_line_1
object
|
Specifies the first line of personalized text that appears on the card. Allowable Values:
21 char max; if Strings longer than the character limit are truncated. |
fulfillment.card_personalization.text.name_line_1.value
string
|
Line of personalized text printed on the card. Allowable Values: 21 char max |
fulfillment.card_personalization.text.name_line_2
object
|
Specifies the second line of personalized text that appears on the card. Allowable Values:
|
fulfillment.card_personalization.text.name_line_2.value
string
|
Line of personalized text printed on the card. Allowable Values: 21 char max |
fulfillment.card_personalization.text.name_line_3
object
|
Specifies the third line of personalized text that appears on the card. Allowable Values:
|
fulfillment.card_personalization.text.name_line_3.value
string
|
Line of personalized text printed on the card. Allowable Values: 21 char max |
fulfillment.shipping
object
|
Specifies shipping details for the order. This object is returned if it exists in the resource. Allowable Values:
|
fulfillment.shipping.care_of_line
string
|
Specifies the value of the care of (C/O) line on the mailing carrier. This field is returned if it exists in the resource. Allowable Values: 255 char max |
fulfillment.shipping.method
string
|
Specifies the shipping service. This field is returned if it exists in the resource. Allowable Values:
|
fulfillment.shipping.recipient_address
object
|
Address to which the order will be shipped. This field is returned if it exists in the resource. Allowable Values: Existing |
fulfillment.shipping.recipient_address.address1
string
|
Number and street of the address. This field is returned if it exists in the resource. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters. |
fulfillment.shipping.recipient_address.address2
string
|
Additional address information. This field is returned if it exists in the resource. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters. |
fulfillment.shipping.recipient_address.city
string
|
City of the address. This field is returned if it exists in the resource. Allowable Values: 40 char max |
fulfillment.shipping.recipient_address.country
string
|
Country of the address. This field is returned if it exists in the resource. Allowable Values: 40 char max English short name. For example, for the Kingdom of Spain, use the English short name "Spain". The ISO maintains the full list of country codes. |
fulfillment.shipping.recipient_address.first_name
string
|
First name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max |
fulfillment.shipping.recipient_address.last_name
string
|
Last name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max |
fulfillment.shipping.recipient_address.middle_name
string
|
Middle name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max |
fulfillment.shipping.recipient_address.phone
string
|
Telephone number of the addressee. This field is returned if it exists in the resource. Allowable Values: 20 char max |
fulfillment.shipping.recipient_address.postal_code
string
|
Postal code of the address. This field is returned if it exists in the resource. Allowable Values: 10 char max |
fulfillment.shipping.recipient_address.state
string
|
State or province of the address. This field is returned if it exists in the resource. Allowable Values: 32 char max |
fulfillment.shipping.recipient_address.zip
string
|
United States ZIP code of the address. This field is returned if it exists in the resource. Allowable Values: 10 char max |
fulfillment.shipping.return_address
object
|
Address to which the order will be returned if shipping fails. This object is returned if it exists in the resource. Allowable Values: Existing |
fulfillment.shipping.return_address.address1
string
|
Number and street of the address. This field is returned if it exists in the resource. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters. |
fulfillment.shipping.return_address.address2
string
|
Additional address information. This field is returned if it exists in the resource. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters. |
fulfillment.shipping.return_address.city
string
|
City of the address. This field is returned if it exists in the resource. Allowable Values: 40 char max |
fulfillment.shipping.return_address.country
string
|
Country of the address. This field is returned if it exists in the resource. Allowable Values: 40 char max English short name. For example, for the Kingdom of Spain, use the English short name "Spain". The ISO maintains the full list of country codes. |
fulfillment.shipping.return_address.first_name
string
|
First name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max |
fulfillment.shipping.return_address.last_name
string
|
Last name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max |
fulfillment.shipping.return_address.middle_name
string
|
Middle name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max |
fulfillment.shipping.return_address.phone
string
|
Telephone number of the addressee. This field is returned if it exists in the resource. Allowable Values: 20 char max |
fulfillment.shipping.return_address.postal_code
string
|
Postal code of the address. This field is returned if it exists in the resource. Allowable Values: 10 char max |
fulfillment.shipping.return_address.state
string
|
State or province of the address. This field is returned if it exists in the resource. Allowable Values: 32 char max |
fulfillment.shipping.return_address.zip
string
|
United States ZIP code of the address. This field is returned if it exists in the resource. Allowable Values: 10 char max |
fulfillment_status
string
|
Card fulfillment status:
Allowable Values:
|
instrument_type
string
|
Instrument type of the card:
Allowable Values:
|
last_four
string
|
Last four digits of the card primary account number (PAN). Allowable Values: 4 chars |
last_modified_time
datetime
|
Date and time when the resource was last modified, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
metadata
object
|
Associates customer-provided metadata with the card. Allowable Values: Contains the names and values of up to 20 fields in the format |
pan
string
|
Primary account number (PAN) of the card. Allowable Values: 16 char max |
pin_is_set
boolean
|
Specifies if the personal identification number (PIN) has been set for the card. Allowable Values: 4 chars |
reissue_pan_from_card_token
string
|
Reissues the specified card (known as the "source" card). Allowable Values: Existing card token |
new_pan_from_card_token
string
|
Reissues the specified card (known as the "source" card) with a new primary account number (PAN). Allowable Values: Existing card token |
state
string
|
Indicates the state of the card. Allowable Values:
|
state_reason
string
|
Descriptive reason for why the card is in its current state. For example, "Card activated by cardholder". Allowable Values: 255 char max |
token
string
|
Unique identifier of the card. Allowable Values: Existing card token |
translate_pin_from_card_token
string
|
Copies the personal identification number (PIN) from the specified source card to the newly created card. Allowable Values: Existing card token |
user_token
string
|
Unique identifier of the cardholder. Allowable Values: Existing user token |
List cards by last 4 digits of PAN
Copy section link
Action: GET
Endpoint: /cards
Retrieves an array of cards whose primary account numbers (PANs) end in the four digits specified by the last_four query parameter.
This endpoint supports field filtering, object expansion, sorting, and pagination.
URL query parameters
Copy section link
| Fields | Description |
|---|---|
count
integer
|
Number of resources to retrieve. Allowable Values: 1-10 Default value: |
start_index
integer
|
Sort order index of the first resource in the returned array. Allowable Values: Any integer Default value: |
last_four
string
|
Last four digits of the primary account number (PAN) of the card you want to locate. Allowable Values: 4 chars |
fields
string
|
Comma-delimited list of fields to return ( Allowable Values: Comma-delimited list of fields, or blank |
sort_by
string
|
Use any field in the resource model, or one of the system fields Allowable Values:
Default value: |
Response body
Copy section link
| Fields | Description |
|---|---|
count
integer
|
The number of resources retrieved. This field is returned if there are resources in your returned array. Allowable Values: 1-10 |
data
array of objects
|
Array of card objects. Objects are returned as appropriate to your query. Allowable Values: Valid array of one or more card objects |
data[].activation_actions
object
|
Defines actions to execute when the card is activated. The fields in this object are mutually exclusive. Allowable Values:
|
data[].activation_actions.swap_digital_wallet_tokens_from_card_token
string
|
Moves all digital wallet tokens from the specified card to the new card. Not relevant when Send a Allowable Values: 1–36 chars Existing card token |
data[].activation_actions.terminate_reissued_source_card
boolean
|
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 Only relevant when Allowable Values:
Default value: |
data[].barcode
string
|
Barcode printed on the card, expressed as numerals. Allowable Values: 10-20 chars |
data[].bulk_issuance_token
string
|
Unique identifier of the bulk card order. Allowable Values: 1-36 chars |
data[].card_product_token
string
|
Unique identifier of the card product. Allowable Values: 1-36 chars |
data[].chip_cvv_number
string
|
Three-digit card verification value (ICVV) stored on the chip of the card. Allowable Values: 3 chars |
data[].contactless_exemption_counter
integer
|
Running count of the contactless transactions successfully completed since the last strong customer authentication (SCA) challenge was issued. You can limit the number of contactless transactions that can be performed without issuing an SCA challenge at the card product level. For more information about strong customer authentication, see Card Products. Allowable Values: Any integer |
data[].contactless_exemption_total_amount
decimal
|
Running total of the money spent in contactless transactions successfully completed since the last strong customer authentication (SCA) challenge was issued. You can limit the total amount that can be spent in contactless transactions without issuing an SCA challenge at the card product level. For more information about strong customer authentication, see Card Products. Allowable Values: Any integer |
data[].created_time
datetime
|
Date and time when the resource was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
data[].cvv_number
string
|
Three-digit card verification value (CVV2 or CVC2) printed on the card. Allowable Values: 3 chars |
data[].expedite
boolean
|
A value of Allowable Values:
|
data[].expiration
string
|
Expiration date in Allowable Values: Format: MMyy |
data[].expiration_time
datetime
|
Expiration date and time, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
data[].fulfillment
object
|
Determines physical characteristics of a card and shipment information. Allowable Values:
|
data[].fulfillment.card_fulfillment_reason
string
|
Descriptive reason for the card fulfillment. Allowable Values:
|
data[].fulfillment.card_personalization
object
|
Specifies personalized attributes to be added to the card. Allowable Values:
|
data[].fulfillment.card_personalization.carrier
object
|
Specifies attributes of the card carrier. Allowable Values:
|
data[].fulfillment.card_personalization.carrier.logo_file
string
|
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
|
Specifies a thumbnail-sized rendering of the image specified in the 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
|
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
|
Specifies a custom message that appears on the card carrier. Allowable Values: 60 char max |
data[].fulfillment.card_personalization.carrier.template_id
string
|
Specifies the card carrier template to use. Allowable Values: Card carrier template ID |
data[].fulfillment.card_personalization.images
object
|
Specifies personalized images that appear on the card. Allowable Values:
|
data[].fulfillment.card_personalization.images.card
object
|
Specifies personalized images that appear on the card. Allowable Values:
|
data[].fulfillment.card_personalization.images.card.name
string
|
Specifies a PNG image to display on the card. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
data[].fulfillment.card_personalization.images.card.thermal_color
string
|
Specifies the color of the image displayed on the card. Allowable Values: Contains the name of the color and must match one of the provider’s predefined colors. |
data[].fulfillment.card_personalization.images.carrier
object
|
Specifies personalized images that appear on the card carrier. Allowable Values:
|
data[].fulfillment.card_personalization.images.carrier.message_1
string
|
Specifies a custom message that appears on the card carrier. Allowable Values: 60 char max |
data[].fulfillment.card_personalization.images.carrier.name
string
|
Specifies a PNG image to display on the card carrier. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
data[].fulfillment.card_personalization.images.carrier_return_window
object
|
Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders. Allowable Values:
|
data[].fulfillment.card_personalization.images.carrier_return_window.name
string
|
Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
data[].fulfillment.card_personalization.images.signature
object
|
Specifies a PNG image of the cardholder’s signature. Allowable Values:
|
data[].fulfillment.card_personalization.images.signature.name
string
|
Specifies a PNG image of the cardholder’s signature. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
data[].fulfillment.card_personalization.perso_type
string
|
Specifies the type of card personalization. Allowable Values:
|
data[].fulfillment.card_personalization.text
object
|
Specifies personalized text that appears on the card. Allowable Values:
|
data[].fulfillment.card_personalization.text.name_line_1
object
|
Specifies the first line of personalized text that appears on the card. Allowable Values:
21 char max; if Strings longer than the character limit are truncated. |
data[].fulfillment.card_personalization.text.name_line_1.value
string
|
Line of personalized text printed on the card. Allowable Values: 21 char max |
data[].fulfillment.card_personalization.text.name_line_2
object
|
Specifies the second line of personalized text that appears on the card. Allowable Values:
|
data[].fulfillment.card_personalization.text.name_line_2.value
string
|
Line of personalized text printed on the card. Allowable Values: 21 char max |
data[].fulfillment.card_personalization.text.name_line_3
object
|
Specifies the third line of personalized text that appears on the card. Allowable Values:
|
data[].fulfillment.card_personalization.text.name_line_3.value
string
|
Line of personalized text printed on the card. Allowable Values: 21 char max |
data[].fulfillment.shipping
object
|
Specifies shipping details for the order. This object is returned if it exists in the resource. Allowable Values:
|
data[].fulfillment.shipping.care_of_line
string
|
Specifies the value of the care of (C/O) line on the mailing carrier. This field is returned if it exists in the resource. Allowable Values: 255 char max |
data[].fulfillment.shipping.method
string
|
Specifies the shipping service. This field is returned if it exists in the resource. Allowable Values:
|
data[].fulfillment.shipping.recipient_address
object
|
Address to which the order will be shipped. This field is returned if it exists in the resource. Allowable Values: Existing |
data[].fulfillment.shipping.recipient_address.address1
string
|
Number and street of the address. This field is returned if it exists in the resource. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters. |
data[].fulfillment.shipping.recipient_address.address2
string
|
Additional address information. This field is returned if it exists in the resource. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters. |
data[].fulfillment.shipping.recipient_address.city
string
|
City of the address. This field is returned if it exists in the resource. Allowable Values: 40 char max |
data[].fulfillment.shipping.recipient_address.country
string
|
Country of the address. This field is returned if it exists in the resource. Allowable Values: 40 char max English short name. For example, for the Kingdom of Spain, use the English short name "Spain". The ISO maintains the full list of country codes. |
data[].fulfillment.shipping.recipient_address.first_name
string
|
First name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max |
data[].fulfillment.shipping.recipient_address.last_name
string
|
Last name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max |
data[].fulfillment.shipping.recipient_address.middle_name
string
|
Middle name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max |
data[].fulfillment.shipping.recipient_address.phone
string
|
Telephone number of the addressee. This field is returned if it exists in the resource. Allowable Values: 20 char max |
data[].fulfillment.shipping.recipient_address.postal_code
string
|
Postal code of the address. This field is returned if it exists in the resource. Allowable Values: 10 char max |
data[].fulfillment.shipping.recipient_address.state
string
|
State or province of the address. This field is returned if it exists in the resource. Allowable Values: 32 char max |
data[].fulfillment.shipping.recipient_address.zip
string
|
United States ZIP code of the address. This field is returned if it exists in the resource. Allowable Values: 10 char max |
data[].fulfillment.shipping.return_address
object
|
Address to which the order will be returned if shipping fails. This object is returned if it exists in the resource. Allowable Values: Existing |
data[].fulfillment.shipping.return_address.address1
string
|
Number and street of the address. This field is returned if it exists in the resource. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters. |
data[].fulfillment.shipping.return_address.address2
string
|
Additional address information. This field is returned if it exists in the resource. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters. |
data[].fulfillment.shipping.return_address.city
string
|
City of the address. This field is returned if it exists in the resource. Allowable Values: 40 char max |
data[].fulfillment.shipping.return_address.country
string
|
Country of the address. This field is returned if it exists in the resource. Allowable Values: 40 char max English short name. For example, for the Kingdom of Spain, use the English short name "Spain". The ISO maintains the full list of country codes. |
data[].fulfillment.shipping.return_address.first_name
string
|
First name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max |
data[].fulfillment.shipping.return_address.last_name
string
|
Last name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max |
data[].fulfillment.shipping.return_address.middle_name
string
|
Middle name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max |
data[].fulfillment.shipping.return_address.phone
string
|
Telephone number of the addressee. This field is returned if it exists in the resource. Allowable Values: 20 char max |
data[].fulfillment.shipping.return_address.postal_code
string
|
Postal code of the address. This field is returned if it exists in the resource. Allowable Values: 10 char max |
data[].fulfillment.shipping.return_address.state
string
|
State or province of the address. This field is returned if it exists in the resource. Allowable Values: 32 char max |
data[].fulfillment.shipping.return_address.zip
string
|
United States ZIP code of the address. This field is returned if it exists in the resource. Allowable Values: 10 char max |
data[].fulfillment_status
string
|
Card fulfillment status:
Allowable Values:
|
data[].instrument_type
string
|
Instrument type of the card:
Allowable Values:
|
data[].last_four
string
|
Last four digits of the card primary account number (PAN). Allowable Values: 4 chars |
data[].last_modified_time
datetime
|
Date and time when the resource was last modified, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
data[].metadata
object
|
Associates customer-provided metadata with the card. Allowable Values: Contains the names and values of up to 20 fields in the format |
data[].pan
string
|
Primary account number (PAN) of the card. Allowable Values: 16 char max |
data[].pin_is_set
boolean
|
Specifies if the personal identification number (PIN) has been set for the card. Allowable Values: 4 chars |
data[].reissue_pan_from_card_token
string
|
Reissues the specified card (known as the "source" card). Allowable Values: Existing card token |
data[].new_pan_from_card_token
string
|
Reissues the specified card (known as the "source" card) with a new primary account number (PAN). Allowable Values: Existing card token |
data[].state
string
|
Indicates the state of the card. Allowable Values:
|
data[].state_reason
string
|
Descriptive reason for why the card is in its current state. For example, "Card activated by cardholder". Allowable Values: 255 char max |
data[].token
string
|
Unique identifier of the card. Allowable Values: Existing card token |
data[].translate_pin_from_card_token
string
|
Copies the personal identification number (PIN) from the specified source card to the newly created card. Allowable Values: Existing card token |
data[].user_token
string
|
Unique identifier of the cardholder. Allowable Values: Existing user token |
end_index
integer
|
Sort order index of the last resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer |
is_more
boolean
|
A value of This field is returned if there are resources in your returned array. Allowable Values:
|
start_index
integer
|
Sort order index of the first resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer |
Retrieve card by barcode
Copy section link
Action: GET
Endpoint: /cards/barcode/{barcode}
Retrieves a card by its barcode.
This endpoint supports field filtering and object expansion.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
barcode
string
|
Barcode of the card to retrieve. Allowable Values: 10-20 chars |
URL query parameters
Copy section link
| Fields | Description |
|---|---|
fields
string
|
Comma-delimited list of fields to return ( Allowable Values: Comma-delimited list of fields, or blank |
Response body
Copy section link
| Fields | Description |
|---|---|
activation_actions
object
|
Defines actions to execute when the card is activated. The fields in this object are mutually exclusive. Allowable Values:
|
activation_actions.swap_digital_wallet_tokens_from_card_token
string
|
Moves all digital wallet tokens from the specified card to the new card. Not relevant when Send a Allowable Values: 1–36 chars Existing card token |
activation_actions.terminate_reissued_source_card
boolean
|
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 Only relevant when Allowable Values:
Default value: |
barcode
string
|
Barcode printed on the card, expressed as numerals. Allowable Values: 10-20 chars |
bulk_issuance_token
string
|
Unique identifier of the bulk card order. Allowable Values: 1-36 chars |
card_product_token
string
|
Unique identifier of the card product. Allowable Values: 1-36 chars |
chip_cvv_number
string
|
Three-digit card verification value (ICVV) stored on the chip of the card. Allowable Values: 3 chars |
contactless_exemption_counter
integer
|
Running count of the contactless transactions successfully completed since the last strong customer authentication (SCA) challenge was issued. You can limit the number of contactless transactions that can be performed without issuing an SCA challenge at the card product level. For more information about strong customer authentication, see Card Products. Allowable Values: Any integer |
contactless_exemption_total_amount
decimal
|
Running total of the money spent in contactless transactions successfully completed since the last strong customer authentication (SCA) challenge was issued. You can limit the total amount that can be spent in contactless transactions without issuing an SCA challenge at the card product level. For more information about strong customer authentication, see Card Products. Allowable Values: Any integer |
created_time
datetime
|
Date and time when the resource was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
cvv_number
string
|
Three-digit card verification value (CVV2 or CVC2) printed on the card. Allowable Values: 3 chars |
expedite
boolean
|
A value of Allowable Values:
|
expiration
string
|
Expiration date in Allowable Values: Format: MMyy |
expiration_time
datetime
|
Expiration date and time, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
fulfillment
object
|
Determines physical characteristics of a card and shipment information. Allowable Values:
|
fulfillment.card_fulfillment_reason
string
|
Descriptive reason for the card fulfillment. Allowable Values:
|
fulfillment.card_personalization
object
|
Specifies personalized attributes to be added to the card. Allowable Values:
|
fulfillment.card_personalization.carrier
object
|
Specifies attributes of the card carrier. Allowable Values:
|
fulfillment.card_personalization.carrier.logo_file
string
|
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
|
Specifies a thumbnail-sized rendering of the image specified in the 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
|
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
|
Specifies a custom message that appears on the card carrier. Allowable Values: 60 char max |
fulfillment.card_personalization.carrier.template_id
string
|
Specifies the card carrier template to use. Allowable Values: Card carrier template ID |
fulfillment.card_personalization.images
object
|
Specifies personalized images that appear on the card. Allowable Values:
|
fulfillment.card_personalization.images.card
object
|
Specifies personalized images that appear on the card. Allowable Values:
|
fulfillment.card_personalization.images.card.name
string
|
Specifies a PNG image to display on the card. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
fulfillment.card_personalization.images.card.thermal_color
string
|
Specifies the color of the image displayed on the card. Allowable Values: Contains the name of the color and must match one of the provider’s predefined colors. |
fulfillment.card_personalization.images.carrier
object
|
Specifies personalized images that appear on the card carrier. Allowable Values:
|
fulfillment.card_personalization.images.carrier.message_1
string
|
Specifies a custom message that appears on the card carrier. Allowable Values: 60 char max |
fulfillment.card_personalization.images.carrier.name
string
|
Specifies a PNG image to display on the card carrier. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
fulfillment.card_personalization.images.carrier_return_window
object
|
Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders. Allowable Values:
|
fulfillment.card_personalization.images.carrier_return_window.name
string
|
Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
fulfillment.card_personalization.images.signature
object
|
Specifies a PNG image of the cardholder’s signature. Allowable Values:
|
fulfillment.card_personalization.images.signature.name
string
|
Specifies a PNG image of the cardholder’s signature. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
fulfillment.card_personalization.perso_type
string
|
Specifies the type of card personalization. Allowable Values:
|
fulfillment.card_personalization.text
object
|
Specifies personalized text that appears on the card. Allowable Values:
|
fulfillment.card_personalization.text.name_line_1
object
|
Specifies the first line of personalized text that appears on the card. Allowable Values:
21 char max; if Strings longer than the character limit are truncated. |
fulfillment.card_personalization.text.name_line_1.value
string
|
Line of personalized text printed on the card. Allowable Values: 21 char max |
fulfillment.card_personalization.text.name_line_2
object
|
Specifies the second line of personalized text that appears on the card. Allowable Values:
|
fulfillment.card_personalization.text.name_line_2.value
string
|
Line of personalized text printed on the card. Allowable Values: 21 char max |
fulfillment.card_personalization.text.name_line_3
object
|
Specifies the third line of personalized text that appears on the card. Allowable Values:
|
fulfillment.card_personalization.text.name_line_3.value
string
|
Line of personalized text printed on the card. Allowable Values: 21 char max |
fulfillment.shipping
object
|
Specifies shipping details for the order. This object is returned if it exists in the resource. Allowable Values:
|
fulfillment.shipping.care_of_line
string
|
Specifies the value of the care of (C/O) line on the mailing carrier. This field is returned if it exists in the resource. Allowable Values: 255 char max |
fulfillment.shipping.method
string
|
Specifies the shipping service. This field is returned if it exists in the resource. Allowable Values:
|
fulfillment.shipping.recipient_address
object
|
Address to which the order will be shipped. This field is returned if it exists in the resource. Allowable Values: Existing |
fulfillment.shipping.recipient_address.address1
string
|
Number and street of the address. This field is returned if it exists in the resource. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters. |
fulfillment.shipping.recipient_address.address2
string
|
Additional address information. This field is returned if it exists in the resource. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters. |
fulfillment.shipping.recipient_address.city
string
|
City of the address. This field is returned if it exists in the resource. Allowable Values: 40 char max |
fulfillment.shipping.recipient_address.country
string
|
Country of the address. This field is returned if it exists in the resource. Allowable Values: 40 char max English short name. For example, for the Kingdom of Spain, use the English short name "Spain". The ISO maintains the full list of country codes. |
fulfillment.shipping.recipient_address.first_name
string
|
First name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max |
fulfillment.shipping.recipient_address.last_name
string
|
Last name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max |
fulfillment.shipping.recipient_address.middle_name
string
|
Middle name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max |
fulfillment.shipping.recipient_address.phone
string
|
Telephone number of the addressee. This field is returned if it exists in the resource. Allowable Values: 20 char max |
fulfillment.shipping.recipient_address.postal_code
string
|
Postal code of the address. This field is returned if it exists in the resource. Allowable Values: 10 char max |
fulfillment.shipping.recipient_address.state
string
|
State or province of the address. This field is returned if it exists in the resource. Allowable Values: 32 char max |
fulfillment.shipping.recipient_address.zip
string
|
United States ZIP code of the address. This field is returned if it exists in the resource. Allowable Values: 10 char max |
fulfillment.shipping.return_address
object
|
Address to which the order will be returned if shipping fails. This object is returned if it exists in the resource. Allowable Values: Existing |
fulfillment.shipping.return_address.address1
string
|
Number and street of the address. This field is returned if it exists in the resource. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters. |
fulfillment.shipping.return_address.address2
string
|
Additional address information. This field is returned if it exists in the resource. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters. |
fulfillment.shipping.return_address.city
string
|
City of the address. This field is returned if it exists in the resource. Allowable Values: 40 char max |
fulfillment.shipping.return_address.country
string
|
Country of the address. This field is returned if it exists in the resource. Allowable Values: 40 char max English short name. For example, for the Kingdom of Spain, use the English short name "Spain". The ISO maintains the full list of country codes. |
fulfillment.shipping.return_address.first_name
string
|
First name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max |
fulfillment.shipping.return_address.last_name
string
|
Last name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max |
fulfillment.shipping.return_address.middle_name
string
|
Middle name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max |
fulfillment.shipping.return_address.phone
string
|
Telephone number of the addressee. This field is returned if it exists in the resource. Allowable Values: 20 char max |
fulfillment.shipping.return_address.postal_code
string
|
Postal code of the address. This field is returned if it exists in the resource. Allowable Values: 10 char max |
fulfillment.shipping.return_address.state
string
|
State or province of the address. This field is returned if it exists in the resource. Allowable Values: 32 char max |
fulfillment.shipping.return_address.zip
string
|
United States ZIP code of the address. This field is returned if it exists in the resource. Allowable Values: 10 char max |
fulfillment_status
string
|
Card fulfillment status:
Allowable Values:
|
instrument_type
string
|
Instrument type of the card:
Allowable Values:
|
last_four
string
|
Last four digits of the card primary account number (PAN). Allowable Values: 4 chars |
last_modified_time
datetime
|
Date and time when the resource was last modified, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
metadata
object
|
Associates customer-provided metadata with the card. Allowable Values: Contains the names and values of up to 20 fields in the format |
pan
string
|
Primary account number (PAN) of the card. Allowable Values: 16 char max |
pin_is_set
boolean
|
Specifies if the personal identification number (PIN) has been set for the card. Allowable Values: 4 chars |
reissue_pan_from_card_token
string
|
Reissues the specified card (known as the "source" card). Allowable Values: Existing card token |
new_pan_from_card_token
string
|
Reissues the specified card (known as the "source" card) with a new primary account number (PAN). Allowable Values: Existing card token |
state
string
|
Indicates the state of the card. Allowable Values:
|
state_reason
string
|
Descriptive reason for why the card is in its current state. For example, "Card activated by cardholder". Allowable Values: 255 char max |
token
string
|
Unique identifier of the card. Allowable Values: Existing card token |
translate_pin_from_card_token
string
|
Copies the personal identification number (PIN) from the specified source card to the newly created card. Allowable Values: Existing card token |
user_token
string
|
Unique identifier of the cardholder. Allowable Values: Existing user token |
Retrieve card by PAN
Copy section link
Action: POST
Endpoint: /cards/getbypan
Retrieves the user_token and card_token for a primary account number (PAN).
In the case of a reissued card, where multiple cards share the same PAN, the information for the most recently issued card is returned.
This request is useful in IVR scenarios where a user has telephoned and identifies the card by the PAN.
The retrieval of these tokens is implemented as a POST request because supplying the PAN in the request body is more secure than supplying it in the URL (as would be required with a GET).
Warning
Sending a request to this endpoint requires PCI DSS compliance. You must comply with PCI DSS data security requirements if you want to store, transmit, or process sensitive card data such as the cardholder’s primary account number (PAN), personal identification number (PIN), and card expiration date.
Request body
Copy section link
| Fields | Description |
|---|---|
cvv_number
string
|
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
|
Card expiration date. Allowable Values: Format: MMyy |
pan
string
|
Primary account number (PAN) of the card whose information you want to retrieve. Send a Allowable Values: 16 char max |
Response body
Copy section link
| Fields | Description |
|---|---|
card_token
string
|
Unique identifier of the card. Allowable Values: Existing card token |
created_time
datetime
|
Date and time when the resource was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
last_modified_time
datetime
|
Date and time when the resource was last modified, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
user_token
string
|
Unique identifier of the cardholder. Allowable Values: Existing user token |
List cards for user
Copy section link
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
Copy section link
| Fields | Description |
|---|---|
token
string
|
Unique identifier of the user whose cards you want to list.
Send a Allowable Values: Existing user token |
URL query parameters
Copy section link
| Fields | Description |
|---|---|
count
integer
|
Number of resources to retrieve. Allowable Values: 1-10 Default value: |
start_index
integer
|
Sort order index of the first resource in the returned array. Allowable Values: Any integer Default value: |
fields
string
|
Comma-delimited list of fields to return ( Allowable Values: Comma-delimited list of fields, or blank |
sort_by
string
|
Use any field in the resource model, or one of the system fields Allowable Values:
Default value: |
Response body
Copy section link
| Fields | Description |
|---|---|
count
integer
|
The number of resources retrieved. This field is returned if there are resources in your returned array. Allowable Values: 1-10 |
data
array of objects
|
Array of card objects. Objects are returned as appropriate to your query. Allowable Values: Valid array of one or more card objects |
data[].activation_actions
object
|
Defines actions to execute when the card is activated. The fields in this object are mutually exclusive. Allowable Values:
|
data[].activation_actions.swap_digital_wallet_tokens_from_card_token
string
|
Moves all digital wallet tokens from the specified card to the new card. Not relevant when Send a Allowable Values: 1–36 chars Existing card token |
data[].activation_actions.terminate_reissued_source_card
boolean
|
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 Only relevant when Allowable Values:
Default value: |
data[].barcode
string
|
Barcode printed on the card, expressed as numerals. Allowable Values: 10-20 chars |
data[].bulk_issuance_token
string
|
Unique identifier of the bulk card order. Allowable Values: 1-36 chars |
data[].card_product_token
string
|
Unique identifier of the card product. Allowable Values: 1-36 chars |
data[].chip_cvv_number
string
|
Three-digit card verification value (ICVV) stored on the chip of the card. Allowable Values: 3 chars |
data[].contactless_exemption_counter
integer
|
Running count of the contactless transactions successfully completed since the last strong customer authentication (SCA) challenge was issued. You can limit the number of contactless transactions that can be performed without issuing an SCA challenge at the card product level. For more information about strong customer authentication, see Card Products. Allowable Values: Any integer |
data[].contactless_exemption_total_amount
decimal
|
Running total of the money spent in contactless transactions successfully completed since the last strong customer authentication (SCA) challenge was issued. You can limit the total amount that can be spent in contactless transactions without issuing an SCA challenge at the card product level. For more information about strong customer authentication, see Card Products. Allowable Values: Any integer |
data[].created_time
datetime
|
Date and time when the resource was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
data[].cvv_number
string
|
Three-digit card verification value (CVV2 or CVC2) printed on the card. Allowable Values: 3 chars |
data[].expedite
boolean
|
A value of Allowable Values:
|
data[].expiration
string
|
Expiration date in Allowable Values: Format: MMyy |
data[].expiration_time
datetime
|
Expiration date and time, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
data[].fulfillment
object
|
Determines physical characteristics of a card and shipment information. Allowable Values:
|
data[].fulfillment.card_fulfillment_reason
string
|
Descriptive reason for the card fulfillment. Allowable Values:
|
data[].fulfillment.card_personalization
object
|
Specifies personalized attributes to be added to the card. Allowable Values:
|
data[].fulfillment.card_personalization.carrier
object
|
Specifies attributes of the card carrier. Allowable Values:
|
data[].fulfillment.card_personalization.carrier.logo_file
string
|
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
|
Specifies a thumbnail-sized rendering of the image specified in the 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
|
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
|
Specifies a custom message that appears on the card carrier. Allowable Values: 60 char max |
data[].fulfillment.card_personalization.carrier.template_id
string
|
Specifies the card carrier template to use. Allowable Values: Card carrier template ID |
data[].fulfillment.card_personalization.images
object
|
Specifies personalized images that appear on the card. Allowable Values:
|
data[].fulfillment.card_personalization.images.card
object
|
Specifies personalized images that appear on the card. Allowable Values:
|
data[].fulfillment.card_personalization.images.card.name
string
|
Specifies a PNG image to display on the card. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
data[].fulfillment.card_personalization.images.card.thermal_color
string
|
Specifies the color of the image displayed on the card. Allowable Values: Contains the name of the color and must match one of the provider’s predefined colors. |
data[].fulfillment.card_personalization.images.carrier
object
|
Specifies personalized images that appear on the card carrier. Allowable Values:
|
data[].fulfillment.card_personalization.images.carrier.message_1
string
|
Specifies a custom message that appears on the card carrier. Allowable Values: 60 char max |
data[].fulfillment.card_personalization.images.carrier.name
string
|
Specifies a PNG image to display on the card carrier. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
data[].fulfillment.card_personalization.images.carrier_return_window
object
|
Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders. Allowable Values:
|
data[].fulfillment.card_personalization.images.carrier_return_window.name
string
|
Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
data[].fulfillment.card_personalization.images.signature
object
|
Specifies a PNG image of the cardholder’s signature. Allowable Values:
|
data[].fulfillment.card_personalization.images.signature.name
string
|
Specifies a PNG image of the cardholder’s signature. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
data[].fulfillment.card_personalization.perso_type
string
|
Specifies the type of card personalization. Allowable Values:
|
data[].fulfillment.card_personalization.text
object
|
Specifies personalized text that appears on the card. Allowable Values:
|
data[].fulfillment.card_personalization.text.name_line_1
object
|
Specifies the first line of personalized text that appears on the card. Allowable Values:
21 char max; if Strings longer than the character limit are truncated. |
data[].fulfillment.card_personalization.text.name_line_1.value
string
|
Line of personalized text printed on the card. Allowable Values: 21 char max |
data[].fulfillment.card_personalization.text.name_line_2
object
|
Specifies the second line of personalized text that appears on the card. Allowable Values:
|
data[].fulfillment.card_personalization.text.name_line_2.value
string
|
Line of personalized text printed on the card. Allowable Values: 21 char max |
data[].fulfillment.card_personalization.text.name_line_3
object
|
Specifies the third line of personalized text that appears on the card. Allowable Values:
|
data[].fulfillment.card_personalization.text.name_line_3.value
string
|
Line of personalized text printed on the card. Allowable Values: 21 char max |
data[].fulfillment.shipping
object
|
Specifies shipping details for the order. This object is returned if it exists in the resource. Allowable Values:
|
data[].fulfillment.shipping.care_of_line
string
|
Specifies the value of the care of (C/O) line on the mailing carrier. This field is returned if it exists in the resource. Allowable Values: 255 char max |
data[].fulfillment.shipping.method
string
|
Specifies the shipping service. This field is returned if it exists in the resource. Allowable Values:
|
data[].fulfillment.shipping.recipient_address
object
|
Address to which the order will be shipped. This field is returned if it exists in the resource. Allowable Values: Existing |
data[].fulfillment.shipping.recipient_address.address1
string
|
Number and street of the address. This field is returned if it exists in the resource. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters. |
data[].fulfillment.shipping.recipient_address.address2
string
|
Additional address information. This field is returned if it exists in the resource. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters. |
data[].fulfillment.shipping.recipient_address.city
string
|
City of the address. This field is returned if it exists in the resource. Allowable Values: 40 char max |
data[].fulfillment.shipping.recipient_address.country
string
|
Country of the address. This field is returned if it exists in the resource. Allowable Values: 40 char max English short name. For example, for the Kingdom of Spain, use the English short name "Spain". The ISO maintains the full list of country codes. |
data[].fulfillment.shipping.recipient_address.first_name
string
|
First name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max |
data[].fulfillment.shipping.recipient_address.last_name
string
|
Last name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max |
data[].fulfillment.shipping.recipient_address.middle_name
string
|
Middle name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max |
data[].fulfillment.shipping.recipient_address.phone
string
|
Telephone number of the addressee. This field is returned if it exists in the resource. Allowable Values: 20 char max |
data[].fulfillment.shipping.recipient_address.postal_code
string
|
Postal code of the address. This field is returned if it exists in the resource. Allowable Values: 10 char max |
data[].fulfillment.shipping.recipient_address.state
string
|
State or province of the address. This field is returned if it exists in the resource. Allowable Values: 32 char max |
data[].fulfillment.shipping.recipient_address.zip
string
|
United States ZIP code of the address. This field is returned if it exists in the resource. Allowable Values: 10 char max |
data[].fulfillment.shipping.return_address
object
|
Address to which the order will be returned if shipping fails. This object is returned if it exists in the resource. Allowable Values: Existing |
data[].fulfillment.shipping.return_address.address1
string
|
Number and street of the address. This field is returned if it exists in the resource. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters. |
data[].fulfillment.shipping.return_address.address2
string
|
Additional address information. This field is returned if it exists in the resource. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters. |
data[].fulfillment.shipping.return_address.city
string
|
City of the address. This field is returned if it exists in the resource. Allowable Values: 40 char max |
data[].fulfillment.shipping.return_address.country
string
|
Country of the address. This field is returned if it exists in the resource. Allowable Values: 40 char max English short name. For example, for the Kingdom of Spain, use the English short name "Spain". The ISO maintains the full list of country codes. |
data[].fulfillment.shipping.return_address.first_name
string
|
First name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max |
data[].fulfillment.shipping.return_address.last_name
string
|
Last name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max |
data[].fulfillment.shipping.return_address.middle_name
string
|
Middle name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max |
data[].fulfillment.shipping.return_address.phone
string
|
Telephone number of the addressee. This field is returned if it exists in the resource. Allowable Values: 20 char max |
data[].fulfillment.shipping.return_address.postal_code
string
|
Postal code of the address. This field is returned if it exists in the resource. Allowable Values: 10 char max |
data[].fulfillment.shipping.return_address.state
string
|
State or province of the address. This field is returned if it exists in the resource. Allowable Values: 32 char max |
data[].fulfillment.shipping.return_address.zip
string
|
United States ZIP code of the address. This field is returned if it exists in the resource. Allowable Values: 10 char max |
data[].fulfillment_status
string
|
Card fulfillment status:
Allowable Values:
|
data[].instrument_type
string
|
Instrument type of the card:
Allowable Values:
|
data[].last_four
string
|
Last four digits of the card primary account number (PAN). Allowable Values: 4 chars |
data[].last_modified_time
datetime
|
Date and time when the resource was last modified, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
data[].metadata
object
|
Associates customer-provided metadata with the card. Allowable Values: Contains the names and values of up to 20 fields in the format |
data[].pan
string
|
Primary account number (PAN) of the card. Allowable Values: 16 char max |
data[].pin_is_set
boolean
|
Specifies if the personal identification number (PIN) has been set for the card. Allowable Values: 4 chars |
data[].reissue_pan_from_card_token
string
|
Reissues the specified card (known as the "source" card). Allowable Values: Existing card token |
data[].new_pan_from_card_token
string
|
Reissues the specified card (known as the "source" card) with a new primary account number (PAN). Allowable Values: Existing card token |
data[].state
string
|
Indicates the state of the card. Allowable Values:
|
data[].state_reason
string
|
Descriptive reason for why the card is in its current state. For example, "Card activated by cardholder". Allowable Values: 255 char max |
data[].token
string
|
Unique identifier of the card. Allowable Values: Existing card token |
data[].translate_pin_from_card_token
string
|
Copies the personal identification number (PIN) from the specified source card to the newly created card. Allowable Values: Existing card token |
data[].user_token
string
|
Unique identifier of the cardholder. Allowable Values: Existing user token |
end_index
integer
|
Sort order index of the last resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer |
is_more
boolean
|
A value of This field is returned if there are resources in your returned array. Allowable Values:
|
start_index
integer
|
Sort order index of the first resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer |
Retrieve card
Copy section link
Action: GET
Endpoint: /cards/{token}
Retrieves a specific card.
This endpoint supports field filtering and object expansion.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
Unique identifier of the card you want to retrieve. Allowable Values: Existing card token |
URL query parameters
Copy section link
| Fields | Description |
|---|---|
fields
string
|
Comma-delimited list of fields to return ( Allowable Values: Comma-delimited list of fields, or blank |
expand
string
|
Embeds the associated object of the specified type into the response, for all Allowable Values:
|
Response body
Copy section link
| Fields | Description |
|---|---|
activation_actions
object
|
Defines actions to execute when the card is activated. The fields in this object are mutually exclusive. Allowable Values:
|
activation_actions.swap_digital_wallet_tokens_from_card_token
string
|
Moves all digital wallet tokens from the specified card to the new card. Not relevant when Send a Allowable Values: 1–36 chars Existing card token |
activation_actions.terminate_reissued_source_card
boolean
|
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 Only relevant when Allowable Values:
Default value: |
barcode
string
|
Barcode printed on the card, expressed as numerals. Allowable Values: 10-20 chars |
bulk_issuance_token
string
|
Unique identifier of the bulk card order. Allowable Values: 1-36 chars |
card_product_token
string
|
Unique identifier of the card product. Allowable Values: 1-36 chars |
chip_cvv_number
string
|
Three-digit card verification value (ICVV) stored on the chip of the card. Allowable Values: 3 chars |
contactless_exemption_counter
integer
|
Running count of the contactless transactions successfully completed since the last strong customer authentication (SCA) challenge was issued. You can limit the number of contactless transactions that can be performed without issuing an SCA challenge at the card product level. For more information about strong customer authentication, see Card Products. Allowable Values: Any integer |
contactless_exemption_total_amount
decimal
|
Running total of the money spent in contactless transactions successfully completed since the last strong customer authentication (SCA) challenge was issued. You can limit the total amount that can be spent in contactless transactions without issuing an SCA challenge at the card product level. For more information about strong customer authentication, see Card Products. Allowable Values: Any integer |
created_time
datetime
|
Date and time when the resource was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
cvv_number
string
|
Three-digit card verification value (CVV2 or CVC2) printed on the card. Allowable Values: 3 chars |
expedite
boolean
|
A value of Allowable Values:
|
expiration
string
|
Expiration date in Allowable Values: Format: MMyy |
expiration_time
datetime
|
Expiration date and time, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
fulfillment
object
|
Determines physical characteristics of a card and shipment information. Allowable Values:
|
fulfillment.card_fulfillment_reason
string
|
Descriptive reason for the card fulfillment. Allowable Values:
|
fulfillment.card_personalization
object
|
Specifies personalized attributes to be added to the card. Allowable Values:
|
fulfillment.card_personalization.carrier
object
|
Specifies attributes of the card carrier. Allowable Values:
|
fulfillment.card_personalization.carrier.logo_file
string
|
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
|
Specifies a thumbnail-sized rendering of the image specified in the 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
|
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
|
Specifies a custom message that appears on the card carrier. Allowable Values: 60 char max |
fulfillment.card_personalization.carrier.template_id
string
|
Specifies the card carrier template to use. Allowable Values: Card carrier template ID |
fulfillment.card_personalization.images
object
|
Specifies personalized images that appear on the card. Allowable Values:
|
fulfillment.card_personalization.images.card
object
|
Specifies personalized images that appear on the card. Allowable Values:
|
fulfillment.card_personalization.images.card.name
string
|
Specifies a PNG image to display on the card. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
fulfillment.card_personalization.images.card.thermal_color
string
|
Specifies the color of the image displayed on the card. Allowable Values: Contains the name of the color and must match one of the provider’s predefined colors. |
fulfillment.card_personalization.images.carrier
object
|
Specifies personalized images that appear on the card carrier. Allowable Values:
|
fulfillment.card_personalization.images.carrier.message_1
string
|
Specifies a custom message that appears on the card carrier. Allowable Values: 60 char max |
fulfillment.card_personalization.images.carrier.name
string
|
Specifies a PNG image to display on the card carrier. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
fulfillment.card_personalization.images.carrier_return_window
object
|
Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders. Allowable Values:
|
fulfillment.card_personalization.images.carrier_return_window.name
string
|
Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
fulfillment.card_personalization.images.signature
object
|
Specifies a PNG image of the cardholder’s signature. Allowable Values:
|
fulfillment.card_personalization.images.signature.name
string
|
Specifies a PNG image of the cardholder’s signature. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
fulfillment.card_personalization.perso_type
string
|
Specifies the type of card personalization. Allowable Values:
|
fulfillment.card_personalization.text
object
|
Specifies personalized text that appears on the card. Allowable Values:
|
fulfillment.card_personalization.text.name_line_1
object
|
Specifies the first line of personalized text that appears on the card. Allowable Values:
21 char max; if Strings longer than the character limit are truncated. |
fulfillment.card_personalization.text.name_line_1.value
string
|
Line of personalized text printed on the card. Allowable Values: 21 char max |
fulfillment.card_personalization.text.name_line_2
object
|
Specifies the second line of personalized text that appears on the card. Allowable Values:
|
fulfillment.card_personalization.text.name_line_2.value
string
|
Line of personalized text printed on the card. Allowable Values: 21 char max |
fulfillment.card_personalization.text.name_line_3
object
|
Specifies the third line of personalized text that appears on the card. Allowable Values:
|
fulfillment.card_personalization.text.name_line_3.value
string
|
Line of personalized text printed on the card. Allowable Values: 21 char max |
fulfillment.shipping
object
|
Specifies shipping details for the order. This object is returned if it exists in the resource. Allowable Values:
|
fulfillment.shipping.care_of_line
string
|
Specifies the value of the care of (C/O) line on the mailing carrier. This field is returned if it exists in the resource. Allowable Values: 255 char max |
fulfillment.shipping.method
string
|
Specifies the shipping service. This field is returned if it exists in the resource. Allowable Values:
|
fulfillment.shipping.recipient_address
object
|
Address to which the order will be shipped. This field is returned if it exists in the resource. Allowable Values: Existing |
fulfillment.shipping.recipient_address.address1
string
|
Number and street of the address. This field is returned if it exists in the resource. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters. |
fulfillment.shipping.recipient_address.address2
string
|
Additional address information. This field is returned if it exists in the resource. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters. |
fulfillment.shipping.recipient_address.city
string
|
City of the address. This field is returned if it exists in the resource. Allowable Values: 40 char max |
fulfillment.shipping.recipient_address.country
string
|
Country of the address. This field is returned if it exists in the resource. Allowable Values: 40 char max English short name. For example, for the Kingdom of Spain, use the English short name "Spain". The ISO maintains the full list of country codes. |
fulfillment.shipping.recipient_address.first_name
string
|
First name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max |
fulfillment.shipping.recipient_address.last_name
string
|
Last name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max |
fulfillment.shipping.recipient_address.middle_name
string
|
Middle name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max |
fulfillment.shipping.recipient_address.phone
string
|
Telephone number of the addressee. This field is returned if it exists in the resource. Allowable Values: 20 char max |
fulfillment.shipping.recipient_address.postal_code
string
|
Postal code of the address. This field is returned if it exists in the resource. Allowable Values: 10 char max |
fulfillment.shipping.recipient_address.state
string
|
State or province of the address. This field is returned if it exists in the resource. Allowable Values: 32 char max |
fulfillment.shipping.recipient_address.zip
string
|
United States ZIP code of the address. This field is returned if it exists in the resource. Allowable Values: 10 char max |
fulfillment.shipping.return_address
object
|
Address to which the order will be returned if shipping fails. This object is returned if it exists in the resource. Allowable Values: Existing |
fulfillment.shipping.return_address.address1
string
|
Number and street of the address. This field is returned if it exists in the resource. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters. |
fulfillment.shipping.return_address.address2
string
|
Additional address information. This field is returned if it exists in the resource. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters. |
fulfillment.shipping.return_address.city
string
|
City of the address. This field is returned if it exists in the resource. Allowable Values: 40 char max |
fulfillment.shipping.return_address.country
string
|
Country of the address. This field is returned if it exists in the resource. Allowable Values: 40 char max English short name. For example, for the Kingdom of Spain, use the English short name "Spain". The ISO maintains the full list of country codes. |
fulfillment.shipping.return_address.first_name
string
|
First name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max |
fulfillment.shipping.return_address.last_name
string
|
Last name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max |
fulfillment.shipping.return_address.middle_name
string
|
Middle name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max |
fulfillment.shipping.return_address.phone
string
|
Telephone number of the addressee. This field is returned if it exists in the resource. Allowable Values: 20 char max |
fulfillment.shipping.return_address.postal_code
string
|
Postal code of the address. This field is returned if it exists in the resource. Allowable Values: 10 char max |
fulfillment.shipping.return_address.state
string
|
State or province of the address. This field is returned if it exists in the resource. Allowable Values: 32 char max |
fulfillment.shipping.return_address.zip
string
|
United States ZIP code of the address. This field is returned if it exists in the resource. Allowable Values: 10 char max |
fulfillment_status
string
|
Card fulfillment status:
Allowable Values:
|
instrument_type
string
|
Instrument type of the card:
Allowable Values:
|
last_four
string
|
Last four digits of the card primary account number (PAN). Allowable Values: 4 chars |
last_modified_time
datetime
|
Date and time when the resource was last modified, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
metadata
object
|
Associates customer-provided metadata with the card. Allowable Values: Contains the names and values of up to 20 fields in the format |
pan
string
|
Primary account number (PAN) of the card. Allowable Values: 16 char max |
pin_is_set
boolean
|
Specifies if the personal identification number (PIN) has been set for the card. Allowable Values: 4 chars |
reissue_pan_from_card_token
string
|
Reissues the specified card (known as the "source" card). Allowable Values: Existing card token |
new_pan_from_card_token
string
|
Reissues the specified card (known as the "source" card) with a new primary account number (PAN). Allowable Values: Existing card token |
state
string
|
Indicates the state of the card. Allowable Values:
|
state_reason
string
|
Descriptive reason for why the card is in its current state. For example, "Card activated by cardholder". Allowable Values: 255 char max |
token
string
|
Unique identifier of the card. Allowable Values: Existing card token |
translate_pin_from_card_token
string
|
Copies the personal identification number (PIN) from the specified source card to the newly created card. Allowable Values: Existing card token |
user_token
string
|
Unique identifier of the cardholder. Allowable Values: Existing user token |
Update card
Copy section link
Action: PUT
Endpoint: /cards/{token}
Updates the details of an existing card.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
Unique identifier of the card you want to update. Allowable Values: Existing card token |
Request body
Copy section link
| Fields | Description |
|---|---|
expedite
boolean
|
Set to 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:
Default value: |
fulfillment
object
|
Specifies certain physical characteristics of a card, as well as shipment information. Allowable Values:
|
fulfillment.card_fulfillment_reason
string
|
Reason for card fulfillment. Allowable Values:
|
fulfillment.card_personalization
object
|
Specifies personalized attributes to be added to the card. Allowable Values:
|
fulfillment.card_personalization.carrier
object
|
Specifies attributes of the card carrier. Allowable Values:
|
fulfillment.card_personalization.carrier.logo_file
string
|
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
|
Specifies a thumbnail-sized rendering of the image specified in the 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
|
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
|
Specifies a custom message that appears on the card carrier. Allowable Values: 60 char max |
fulfillment.card_personalization.carrier.template_id
string
|
Specifies the card carrier template to use. Allowable Values: Card carrier template ID |
fulfillment.card_personalization.images
object
|
Specifies personalized images that appear on the card. Allowable Values:
|
fulfillment.card_personalization.images.card
object
|
Specifies personalized images that appear on the card. Allowable Values:
|
fulfillment.card_personalization.images.card.name
string
|
Specifies a PNG image to display on the card. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
fulfillment.card_personalization.images.card.thermal_color
string
|
Specifies the color of the image displayed on the card. Allowable Values: Contains the name of the color and must match one of the provider’s predefined colors. |
fulfillment.card_personalization.images.carrier
object
|
Specifies personalized images that appear on the card carrier. Allowable Values:
|
fulfillment.card_personalization.images.carrier.message_1
string
|
Specifies a custom message that appears on the card carrier. Allowable Values: 60 char max |
fulfillment.card_personalization.images.carrier.name
string
|
Specifies a PNG image to display on the card carrier. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
fulfillment.card_personalization.images.carrier_return_window
object
|
Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders. Allowable Values:
|
fulfillment.card_personalization.images.carrier_return_window.name
string
|
Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
fulfillment.card_personalization.images.signature
object
|
Specifies a PNG image of the cardholder’s signature. Allowable Values:
|
fulfillment.card_personalization.images.signature.name
string
|
Specifies a PNG image of the cardholder’s signature. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
fulfillment.card_personalization.perso_type
string
|
Specifies the type of card personalization. Allowable Values:
|
fulfillment.card_personalization.text
object
|
Specifies personalized text that appears on the card. Allowable Values:
|
fulfillment.card_personalization.text.name_line_1
object
|
Specifies the first line of personalized text that appears on the card. Allowable Values:
21 char max; if Strings longer than the character limit are truncated. |
fulfillment.card_personalization.text.name_line_1.value
string
|
Line of personalized text printed on the card. Allowable Values: 21 char max |
fulfillment.card_personalization.text.name_line_2
object
|
Specifies the second line of personalized text that appears on the card. Allowable Values:
|
fulfillment.card_personalization.text.name_line_2.value
string
|
Line of personalized text printed on the card. Allowable Values: 21 char max |
fulfillment.card_personalization.text.name_line_3
object
|
Specifies the third line of personalized text that appears on the card. Allowable Values:
|
fulfillment.card_personalization.text.name_line_3.value
string
|
Line of personalized text printed on the card. Allowable Values: 21 char max |
fulfillment.shipping
object
|
Specifies shipping details for the order. Allowable Values:
|
fulfillment.shipping.care_of_line
string
|
Adds the specified value as a care of (C/O) line to the mailing carrier. NOTE: This field can be specified on cards, card products, and bulk card orders. If you specify this field at multiple levels, the order of precedence is: card, bulk card order, card product. Allowable Values: 255 char max |
fulfillment.shipping.method
string
|
Specifies the shipping service. Allowable Values:
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
|
Address to which the order will be shipped. In order to generate cards, a valid shipping address must be provided by one of these:
The order of precedence from highest to lowest is card, user, card product.
To be valid, an address must have the Allowable Values: Valid |
fulfillment.shipping.recipient_address.address1
string
|
Number and street of the address. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters. |
fulfillment.shipping.recipient_address.address2
string
|
Additional address information. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters. |
fulfillment.shipping.recipient_address.city
string
|
City of the address. Allowable Values: 40 char max |
fulfillment.shipping.recipient_address.country
string
|
Country of the address. Allowable Values: 40 char max English short name. For example, for the Kingdom of Spain, use the English short name "Spain". The ISO maintains the full list of country codes. |
fulfillment.shipping.recipient_address.first_name
string
|
First name of the addressee. Allowable Values: 40 char max |
fulfillment.shipping.recipient_address.last_name
string
|
Last name of the addressee. Allowable Values: 40 char max |
fulfillment.shipping.recipient_address.middle_name
string
|
Middle name of the addressee. Allowable Values: 40 char max |
fulfillment.shipping.recipient_address.phone
string
|
Telephone number of the addressee. Allowable Values: 20 char max |
fulfillment.shipping.recipient_address.postal_code
string
|
Postal code of the address. Allowable Values: 10 char max |
fulfillment.shipping.recipient_address.state
string
|
State of the address. Allowable Values: 32 char max |
fulfillment.shipping.recipient_address.zip
string
|
United States ZIP code of the address. Allowable Values: 10 char max |
fulfillment.shipping.return_address
object
|
Address to which the order will be returned if shipping fails. Allowable Values:
|
fulfillment.shipping.return_address.address1
string
|
Number and street of the address. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters. |
fulfillment.shipping.return_address.address2
string
|
Additional address information. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters. |
fulfillment.shipping.return_address.city
string
|
City of the address. Allowable Values: 40 char max |
fulfillment.shipping.return_address.country
string
|
Country of the address. Allowable Values: 40 char max English short name. For example, for the Kingdom of Spain, use the English short name "Spain". The ISO maintains the full list of country codes. |
fulfillment.shipping.return_address.first_name
string
|
First name of the addressee. Allowable Values: 40 char max |
fulfillment.shipping.return_address.last_name
string
|
Last name of the addressee. Allowable Values: 40 char max |
fulfillment.shipping.return_address.middle_name
string
|
Middle name of the addressee. Allowable Values: 40 char max |
fulfillment.shipping.return_address.phone
string
|
Telephone number of the addressee. Allowable Values: 20 char max |
fulfillment.shipping.return_address.postal_code
string
|
Postal code of the address. Allowable Values: 10 char max |
fulfillment.shipping.return_address.state
string
|
State of the address. Allowable Values: 32 char max |
fulfillment.shipping.return_address.zip
string
|
United States ZIP code of the address. Allowable Values: 10 char max |
metadata
object
|
Associates customer-provided metadata with the card. Allowable Values: Contains the names and values of up to 20 fields in the format |
token
string
|
Unique identifier of the card you want to update. Allowable Values: 1–36 chars Existing card token Send a |
user_token
string
|
Specifies the user you want to associate with the card. Allowable Values: 1–36 chars Existing user token. Send a |