Cards
The
For more information on cards, see About Cards.
Some attributes of the
-
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:
Endpoint:
Creates a card.
Create the user and card product before you create the card. You create a card using the
Note
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’sSend a
Query parameters
Copy section link
You can use optional query parameters to show the PAN and CVV2 number in the response. If
This endpoint requires PCI DSS compliance if
Fields | Description |
---|---|
show_pan
boolean
|
Set to true to show the full PAN in the response.
Allowable Values: true , false
Default value: false
|
show_cvv_number
boolean
|
Set to true to show the CVV2 number in the response.
Allowable Values: true , false
Default value: false
|
Body field details
Copy section link
Fields | Description |
---|---|
token
string
|
The unique identifier of the card. If you do not include a token, the system will generate one automatically. Other API calls will require this token, so we recommend creating a token that is easy to remember rather than letting the system generate one. This value cannot be updated. Allowable Values: 36 char max |
user_token
string
|
The unique identifier of the authorized user of the card. Allowable Values: Existing user token. Send a GET request to /users to retrieve user tokens.
|
fulfillment
object
|
Determines physical characteristics of a card and shipment information. Allowable Values: Existing fulfillment object.
|
reissue_pan_from_card_token
string
|
Reissues the specified card (known as the "source" card). This field reissues a card by copying the PAN and PIN from the specified source card to the newly created card. The reissued card has the same PAN and PIN as the source card but a new expiration date and CVV2 number.
NoteBy default, the source card is automatically terminated. However, if your program is configured for multiple active cards, you can prevent the source card from being automatically terminated by setting theactivation_actions.terminate_reissued_source_card field to false .
Allowable Values: Existing card token. Send a GET request to /cards/user/{token} to retrieve card tokens for a particular user.
|
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. This field is not allowed if reissue_pan_from_card_token is set.
Allowable Values: Existing card token. Send a GET request to /cards/user/{token} to retrieve card tokens for a particular user.
|
card_product_token
string
|
The unique identifier of the card product. Allowable Values: Existing card product token. Send a GET request to /cardproducts to retrieve card product tokens.
|
bulk_issuance_token
string
|
Associates the card with the specified bulk card order. This field cannot be updated. Allowable Values: 36 char max |
expedite
boolean
|
Set to true to request expedited processing of the card by your card fulfillment provider.
This expedited service is available for cards fulfilled by Perfect Plastic Printing, IDEMIA, and Arroweye Solutions.
NoteContact your Marqeta representative for information regarding the cost of expedited service.Allowable Values: true , false
Default value: false
|
expiration_offset
object
|
Specifies the length of time for which the card is valid. In other words, the card expires this length of time after the date of issue. If not specified, the card uses the config.card_life_cycle.expiration_offset of the card product.
Allowable Values: Existing expiration_offset object.
|
activation_actions
object
|
Defines actions to execute when the card is activated. The fields in this object are mutually exclusive. Allowable Values: Existing activation_actions object.
|
metadata
object
|
Associates customer-injected metadata with the user. Allowable Values: Existing metadata object.
|
The activation_actions object
Copy section link
Fields | Description |
---|---|
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 false .
Only relevant when reissue_pan_from_card_token is set.
Allowable Values: true , false
Default value: true
|
swap_digital_wallet_tokens_from_card_token
string
|
Moves all digital wallet tokens from the specified card to the new card. Not relevant when reissue_pan_from_card_token is set.
Allowable Values: Existing card token. Send a GET request to /cards/user/{token} to retrieve card tokens for a particular user.
|
The expiration_offset object
Copy section link
Fields | Description |
---|---|
unit
string
|
Specifies the units for the value field.
Allowable Values: YEARS , MONTHS , DAYS , HOURS , MINUTES , SECONDS
Default value: YEARS
|
value
integer
|
Specifies the number of time units (as defined by the unit field) that the card is valid.
In other words, cards expire value x unit after the date of issue.
This number is rounded as follows:
Allowable Values: Any positive integer Default value: |
The fulfillment object
Copy section link
Fields | Description |
---|---|
card_personalization
object
|
Allows personalized attributes to be added to the card. Allowable Values: Existing fulfillment.card_personalization object.
|
shipping
object
|
Specifies shipping details for the card. Allowable Values: Existing fulfillment.shipping object.
|
The fulfillment.shipping object
Copy section link
Fields | Description |
---|---|
return_address
object
|
Address to which card will be returned if shipping fails. For individual card orders: If no return_address is specified for the card, then the return_address for the card product is used.
For an address to be valid for use, its address1 , city , state , and postal_code fields must be populated.
The country is assumed to be the United States if the country field is unpopulated.
Allowable Values: Existing fulfillment.shipping.return_address object.
|
recipient_address
object
|
Address to which card will be shipped. For individual card orders: If no recipient_address is specified for the card, then the recipient_address for the user is used.
If no recipient_address is specified for the user, then the recipient_address for the card product is used.
For an address to be valid for use, its address1 , city , state , and postal_code fields must be populated.
The country is assumed to be the United States if the country field is unpopulated.
Allowable Values: Existing fulfillment.shipping.recipient_address object.
|
method
string
|
Specifies the shipping service. Allowable Values: These allowed values specify shipping services and providers offered by your card fulfillment provider. Perfect Plastic Printing, IDEMIA, and Arroweye Solutions: These generic options specify shipping companies and services available from the card provider. For details on the specific shipping companies and services offered by the card providers, contact your Marqeta representative.
|
care_of_line
string
|
Adds the specified value as a C/O (care of) line to the mailing carrier.
NoteThis field overrides the equivalent field on the associated card product.Allowable Values: 255 char max |
The fulfillment.shipping.return_address & recipient_address objects
Copy section link
Fields | Description |
---|---|
address1
string
|
Number and street. Allowable Values: 255 char max, though lower limits may be imposed by providers. Perfect Plastic Printing and IDEMIA limit chars to 100, and Arroweye Solutions limits chars to 50. |
address2
string
|
Additional address information. Allowable Values: 255 char max, though lower limits may be imposed by providers. Perfect Plastic Printing and IDEMIA limit chars to 100, and Arroweye Solutions limits chars to 50. |
city
string
|
City. Allowable Values: 40 char max |
state
string
|
State. Allowable Values: 32 char max |
postal_code
string
|
Postal code. Allowable Values: 10 char max |
country
string
|
Country. Allowable Values: The short English name. For example, for Spain, use the short English name "Spain". The ISO maintains the full list of country codes. 40 char max |
phone
string
|
Telephone number. Allowable Values: 20 char max |
first_name
string
|
First name. Allowable Values: 50 char max |
middle_name
string
|
Middle name. Allowable Values: 50 char max |
last_name
string
|
Last name. Allowable Values: 50 char max |
The fulfillment.card_personalization object
Copy section link
Note
When the Marqeta platform fulfills an individual card order, card personalization attributes defined at the card level override matching attributes of the associated card product. Contact your Marqeta representative to make use of card personalization.Fields | Description |
---|---|
text
object
|
Specifies personalized text that appears on the card. Allowable Values: Existing fulfillment.card_personalization.text object.
|
carrier
object
|
Specifies attributes of the card carrier (if your fulfillment provider is Arroweye Solutions). Allowable Values: Existing fulfillment.card_personalization.carrier object.
|
images
object
|
Specifies personalized images that appear on the card (for individual card orders only). Also specifies attributes of the card carrier, if your fulfillment provider is Perfect Plastic Printing or IDEMIA.
NoteTheimages object does not store or pass any actual image data.
It only specifies image files that you send to your fulfillment provider.
Allowable Values: Existing fulfillment.card_personalization.images object.
|
perso_type
string
|
Specifies the method for printing personalized text on the card. Allowable Values: EMBOSS , LASER , FLAT
|
The fulfillment.card_personalization.text object
Copy section link
Fields | Description |
---|---|
name_line_1.value
string
|
First line of personalized text printed on the face of the card. Allowable Values: Valid characters differ according to your fulfillment provider:
21 char max Strings longer than 21 characters are truncated. |
name_line_2.value
string
|
Second line of personalized text printed on the face of the card. Allowable Values: Valid characters differ according to your fulfillment provider:
The combined maximum character limit for name_line_2.value and name_line_3.value is 21 characters.
Strings longer than 21 characters are truncated.
|
name_line_3.value
string
|
Third line of personalized text printed on the face of the card. Allowable Values: Valid characters differ according to your fulfillment provider:
The combined maximum character limit for name_line_2.value and name_line_3.value is 21 characters.
Strings longer than 21 characters are truncated.
|
The fulfillment.card_personalization.carrier object
Copy section link
Fields | Description |
---|---|
template_id
string
|
Specifies the card carrier template to use. Allowable Values: A card carrier template ID. |
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. |
logo_thumbnail_file
string
|
Specifies a thumbnail-sized rendering of the image specified in the logo_file field.
Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
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. |
message_line
string
|
Specifies a custom message that appears on the card carrier. Allowable Values: 60 char max |
The fulfillment.card_personalization.images object
Copy section link
Fields | Description |
---|---|
card
object
|
Specifies personalized images that appear on the card. Allowable Values: Existing card object.
|
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. Must end in .png .
|
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. Must end in .png .
|
The fulfillment.card_personalization.images.card object
Copy section link
Fields | Description |
---|---|
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. Must end in .png .
|
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. |
The metadata object
Copy section link
Fields | Description |
---|---|
customer_defined_name_01
customer_defined_name_02 … customer_defined_name_20
string
|
Associates customer-injected metadata with the card. You can define the names and values of up to 20 fields, for example:
Copied Allowable Values:
|
Card state and fulfillment status
Copy section link
Every card object has state and fulfillment status fields that cannot be set directly using the
Card state
Copy section link
State | Description |
---|---|
UNACTIVATED |
The card has been created but is non-functional. This is the initial state of a card. |
ACTIVE |
The card is functional. A card can transition to an ACTIVE state only from an UNACTIVATED or SUSPENDED state.
This state can result from card activation (or reactivation from a SUSPENDED state) by Marqeta, Marqeta customer, or the cardholder (see Create Card Transition). |
SUSPENDED |
The card is temporarily non-functional. Refunds can still be completed while a card is suspended. A card can transition from ACTIVE to SUSPENDED and back to ACTIVE again.
This state can result from card suspension by Marqeta, the Marqeta customer, or the cardholder. |
TERMINATED |
The card is permanently non-functional and cannot transition to any other state. Refunds can still be completed after a card is terminated. This state can result from card termination by Marqeta, the Marqeta customer, or the cardholder. Depending on your program settings, this state can also result from activation or reactivation of another card. |
Card fulfillment status
Copy section link
Status | Description |
---|---|
ISSUED |
Initial state of all newly created/issued cards. |
ORDERED |
Card ordered through card fulfillment provider. |
REORDERED |
Card reordered through card fulfillment provider. |
REJECTED |
Card rejected by card fulfillment provider. |
SHIPPED |
Card shipped by card fulfillment provider. |
DIGITALLY_PRESENTED |
Card digitally presented using the /cards/{token}/showpan endpoint; does not affect the delivery of physical cards. |
Retrieve card
Copy section link
Action:
Endpoint:
Retrieves a specific card.
This endpoint supports field filtering and object expansion.
URL path parameters
Copy section link
Fields | Description |
---|---|
token
string
|
Identifies the card to retrieve. Allowable Values: Existing card token. Send a GET request to /cards/user/{token} to retrieve card tokens for a specific user.
|
Update card
Copy section link
Action:
Endpoint:
Updates the details of an existing card.
URL path parameters
Copy section link
Fields | Description |
---|---|
token
string
|
Identifies the card to update. Allowable Values: Existing card token. Send a GET request to /cards/user/{token} to retrieve card tokens for a specific user.
|
Body field details
Copy section link
Fields | Description |
---|---|
user_token
string
|
Specifies the user you want to associate with the card. Allowable Values: Existing user token. Send a GET request to /users to retrieve user tokens.
|
expedite
boolean
|
Set to true to request expedited processing of the card by your card fulfillment provider.
This expedited service is available for cards fulfilled by Perfect Plastic Printing, IDEMIA, and Arroweye Solutions.
NoteContact your Marqeta representative for information regarding the cost of expedited service.Allowable Values: true , false
Default value: |
fulfillment
object
|
Determines physical characteristics of a card and shipment information. Allowable Values: Existing fulfillment object.
|
metadata
object
|
Associates customer-injected metadata with the card. Allowable Values: Existing metadata object.
|
The fulfillment object
Copy section link
Fields | Description |
---|---|
card_personalization
object
|
Allows personalized attributes to be added to the card. Allowable Values: Existing fulfillment.card_personalization object.
|
shipping
object
|
Specifies shipping details for the card. Allowable Values: Existing fulfillment.shipping object.
|
The fulfillment.shipping object
Copy section link
Fields | Description |
---|---|
return_address
object
|
Address to which card will be returned if shipping fails. For individual card orders: If no return_address is specified for the card, then the return_address for the card product is used.
For an address to be valid for use, its address1 , city , state , and postal_code fields must be populated.
The country is assumed to be the United States if the country field is unpopulated.
Allowable Values: Existing fulfillment.shipping.return_address object.
|
recipient_address
object
|
Address to which card will be shipped. For individual card orders: If no recipient_address is specified for the card, then the recipient_address for the user is used.
If no recipient_address is specified for the user, then the recipient_address for the card product is used.
For an address to be valid for use, its address1 , city , state , and postal_code fields must be populated.
The country is assumed to be the United States if the country field is unpopulated.
Allowable Values: Existing fulfillment.shipping.recipient_address object.
|
method
string
|
Specifies the shipping service. Allowable Values: These allowed values specify shipping services and providers offered by your card fulfillment provider. Perfect Plastic Printing, IDEMIA, and Arroweye Solutions: These generic options specify shipping companies and services available from the card provider. For details on the specific shipping companies and services offered by the card providers, contact your Marqeta representative.
|
care_of_line
string
|
Adds the specified value as a C/O (care of) line to the mailing carrier.
NoteThis field overrides the equivalent field on the associated card product.Allowable Values: 255 char max |
The fulfillment.shipping.return_address & recipient_address objects
Copy section link
Fields | Description |
---|---|
address1
string
|
Number and street. Allowable Values: 255 char max, though lower limits may be imposed by providers. Perfect Plastic Printing and IDEMIA limit chars to 100, and Arroweye Solutions limits chars to 50. |
address2
string
|
Additional address information. Allowable Values: 255 char max, though lower limits may be imposed by providers. Perfect Plastic Printing and IDEMIA limit chars to 100, and Arroweye Solutions limits chars to 50. |
city
string
|
City. Allowable Values: 40 char max |
state
string
|
State. Allowable Values: 32 char max |
postal_code
string
|
Postal code. Allowable Values: 10 char max |
country
string
|
Country. Allowable Values: The short English name. For example, for Spain, use the short English name "Spain". The ISO maintains the full list of country codes. 40 char max |
phone
string
|
Telephone number. Allowable Values: 20 char max |
first_name
string
|
First name. Allowable Values: 40 char max |
middle_name
string
|
Middle name. Allowable Values: 40 char max |
last_name
string
|
Last name. Allowable Values: 40 char max |
The fulfillment.card_personalization object
Copy section link
Note
When the Marqeta platform fulfills an individual card order, card personalization attributes defined at the card level override matching attributes of the associated card product. Contact your Marqeta representative to make use of card personalization.Fields | Description |
---|---|
text
object
|
Specifies personalized text that appears on the card. Allowable Values: Existing fulfillment.card_personalization.text object.
|
carrier
object
|
Specifies attributes of the card carrier (if your fulfillment provider is Arroweye Solutions). Allowable Values: Existing fulfillment.card_personalization.carrier object.
|
images
object
|
Specifies personalized images that appear on the card (for individual card orders only). Also specifies attributes of the card carrier, if your fulfillment provider is Perfect Plastic Printing or IDEMIA. Allowable Values: Existing fulfillment.card_personalization.images object.
|
The fulfillment.card_personalization.text object
Copy section link
Fields | Description |
---|---|
name_line_1.value
string
|
First line of personalized text printed on the face of the card. Allowable Values: Valid characters differ according to your fulfillment provider:
21 char max Strings longer than 21 characters are truncated. |
name_line_2.value
string
|
Second line of personalized text printed on the face of the card. Allowable Values: Valid characters differ according to your fulfillment provider:
The combined maximum character limit for name_line_2.value and name_line_3.value is 21 characters.
Strings longer than 21 characters are truncated.
|
name_line_3.value
string
|
Third line of personalized text printed on the face of the card. Allowable Values: Valid characters differ according to your fulfillment provider:
The combined maximum character limit for name_line_2.value and name_line_3.value is 21 characters.
Strings longer than 21 characters are truncated.
|
The fulfillment.card_personalization.carrier object
Copy section link
Fields | Description |
---|---|
template_id
string
|
Specifies the card carrier template to use. Allowable Values: A card carrier template ID. |
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. |
logo_thumbnail_file
string
|
Specifies a thumbnail-sized rendering of the image specified in the logo_file field.
Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider. |
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. |
message_line
string
|
Specifies a custom message that appears on the card carrier. Allowable Values: 60 char max |
The fulfillment.card_personalization.images object
Copy section link
Fields | Description |
---|---|
card
object
|
Specifies personalized images that appear on the card. Allowable Values: Existing fulfillment.card_personalization.images.card object.
|
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. Must end in .png .
|
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. Must end in .png .
|
The fulfillment.card_personalization.images.card object
Copy section link
Fields | Description |
---|---|
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. Must end in .png .
|
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. |
The metadata object
Copy section link
Fields | Description |
---|---|
customer_defined_name_01
customer_defined_name_02 … customer_defined_name_20
string
|
Associates customer-injected metadata with the card. You can define the names and values of up to 20 fields, for example:
Copied The following samples show how to update, add, and delete fields. Existing fields are unaffected unless they are included in the request. Update a field’s value:
Copied Add a new field:
Copied Delete an existing field:
Copied Allowable Values:
|
List cards for user
Copy section link
Action:
Endpoint:
Lists 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
|
Identifies the user whose cards you want to list. Allowable Values: Existing user token. Send a GET request to /users to retrieve user tokens.
|
Retrieve card by PAN
Copy section link
Action:
Endpoint:
Retrieves the
This call 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
Note
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.
Body field details
Copy section link
Fields | Description |
---|---|
pan
string
|
The PAN of the card whose information you want to retrieve. Allowable Values: 16 char max Send a GET request to /cards/{token}/showpan to retrieve the PAN for a specific card.
|
cvv_number
string
|
The three-digit card verification value (CVV2) included on the back of the card. This value cannot be updated. Allowable Values: 3 char max |
expiration
string
|
Card expiration date. Allowable Values: mmyy |
Show card PAN
Copy section link
Action:
Endpoint:
Retrieves a PAN (card number). For security reasons, the PAN is not fully visible on the card resource returned by
This endpoint supports field filtering and object expansion.
Note
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.
URL path parameters
Copy section link
Fields | Description |
---|---|
token
string
|
Identifies the card whose PAN you want to retrieve. Allowable Values: Existing card token. Send a GET request to /cards/user/{token} to retrieve existing card tokens for a specific user.
|
Query parameters
Copy section link
Fields | Description |
---|---|
show_cvv_number
boolean
|
Set to true to display the full CVV2 number in the response.
Allowable Values: true , false
|
Retrieve card by barcode
Copy section link
Action:
Endpoint:
Retrieves a card by its barcode.
This endpoint supports field filtering and object expansion.
URL path parameters
Copy section link
Fields | Description |
---|---|
barcode
string
|
The barcode of the card to retrieve. Allowable Values: Existing barcode |
List cards by last four digits of PAN
Copy section link
Action:
Endpoint:
Retrieves an array of cards whose PANs end in the four digits specified by the
This endpoint supports field filtering, object expansion, sorting, and pagination.
Query parameters
Copy section link
Fields | Description |
---|---|
last_four
string
|
The last four digits of the PAN of the card you want to locate. Allowable Values: four-digit string |
Create onboarding card
Copy section link
Action:
Endpoint:
Creates a merchant onboarding card. You cannot set the
The card product passed into the
As a result of the
URL path parameters
Copy section link
Fields | Description |
---|---|
merchant_token
string
|
Identifies the merchant for whom you are creating the card. Allowable Values: Existing merchant token. Send a GET request to /merchants to retrieve existing merchant tokens.
|
Body field details
Copy section link
Fields | Description |
---|---|
card_product_token
string
|
Specifies the card product to use when creating the card. The card product’s config.special.merchant_on_boarding field must be set to true .
Allowable Values: Existing card product token. Send a GET request to /cardproducts to retrieve card product tokens.
|
expedite
boolean
|
Set to true to request expedited processing of the card by your card fulfillment provider.
This expedited service is available for cards fulfilled by Perfect Plastic Printing, IDEMIA, and Arroweye Solutions.
NoteContact your Marqeta representative for information regarding the cost of expedited service.Allowable Values: true , false
Default value: false
|
Retrieve onboarding card
Copy section link
Action:
Endpoint:
Retrieves a specific merchant onboarding card.
This endpoint supports field filtering and object expansion.
URL path parameters
Copy section link
Fields | Description |
---|---|
merchant_token
string
|
Identifies the merchant whose card you want to retrieve. Allowable Values: Existing merchant token. Send a GET request to /merchants to retrieve existing merchant tokens.
|
Show onboarding card PAN
Copy section link
Action:
Endpoint:
Retrieves the PAN (card number) of a merchant onboarding card. For security reasons, the PAN is not fully visible on the card resource returned by
This endpoint supports field filtering and object expansion.
Note
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.
URL path parameters
Copy section link
Fields | Description |
---|---|
merchant_token
string
|
Identifies the merchant whose card you want to retrieve. Allowable Values: Existing merchant token. Send a GET request to /merchants to retrieve existing merchant tokens.
|
Query parameters
Copy section link
Fields | Description |
---|---|
show_cvv_number
boolean
|
Set to true to display the full CVV2 number in the response.
Allowable Values: true , false
|
Create card transition
Copy section link
Action:
Endpoint:
Creates a card state transition to set the state of an existing card.
If your system uses IVR, you can send a
It may not be possible to move a card from one user to another user once the card has been activated.
Body field details
Copy section link
Fields | Description |
---|---|
token
string
|
The unique identifier of the card transition. If you do not include a token, the system will generate one automatically. This token is referenced in other API calls, so we recommend that you define a simple string that is easy to remember. This value cannot be updated. Allowable Values: 36 char max |
card_token
string
|
Identifies the card whose state will transition. Allowable Values: Existing card token. Send a GET request to /cards/user/{token} to retrieve card tokens for a specific user.
|
state
string
|
Specifies the new state. Allowable Values: ACTIVE , SUSPENDED , TERMINATED
|
channel
string
|
The mechanism by which the transition was initiated.
Allowable Values: ADMIN , API , FRAUD , IVR , SYSTEM
|
reason
string
|
Additional information about the state change. Allowable Values: 255 char max |
reason_code
string
|
A standard code describing the reason for the transition. Allowable Values: See The reason_code field section. |
validations
object
|
Contains information about the user. Allowable Values: Existing validations object.
|
The reason_code field
Copy section link
Value | Description |
---|---|
00 |
Object activated for the first time. |
01 |
Requested by you. |
02 |
Inactivity over time. |
03 |
Provided address either does not accept mail or the addressee is not known at the address. |
04 |
Negative account balance. |
05 |
Account under review. |
06 |
Suspicious activity was identified. |
07 |
Activity outside the program parameters was identified. |
08 |
Confirmed fraud was identified. |
09 |
Matched with an Office of Foreign Assets Control list. |
10 |
Card was reported lost. |
11 |
Card information was cloned. |
12 |
Account or card information was compromised. |
13 |
Temporary status change while on hold/leave. |
14 |
Initiated by Marqeta. |
15 |
Initiated by issuer. |
16 |
Card expired. |
17 |
Failed KYC. |
18 |
Changed to ACTIVE because information was properly validated and confirmed. |
19 |
Changed to ACTIVE because account activity was properly validated and confirmed. |
20 |
Change occurred prior to the normalization of reason codes. |
21 |
Initiated by a third party, often a digital wallet provider. |
22 |
PIN retry limit reached. |
23 |
Card was reported stolen. |
The validations object
Copy section link
Fields | Description |
---|---|
user
object
|
Contains information about the user. Allowable Values: Existing validations object
|
The validations.user object
Copy section link
Fields | Description |
---|---|
birth_date
string
|
The birth date of the user associated with this card. Allowable Values: yyyy-MM-dd |
phone
string
|
The telephone number of the user associated with this card. Allowable Values: 5105551212 or 510-555-1212 |
ssn
string
|
The Social Security number of the user associated with this card. Allowable Values: 255 char max |
The type field (response)
Copy section link
Every card transition has a
Value | Description |
---|---|
state.activated |
Card was activated. |
state.reinstated |
Card was reinstated from a suspended state. |
state.suspended |
Card was suspended. |
state.terminated |
Card was terminated. |
fulfillment.digitally_presented |
Card was digitally presented using the /cards/{token}/showpan endpoint; does not affect the delivery of physical cards. |
fulfillment.issued |
Card was created/issued. |
fulfillment.ordered |
Card was ordered from card fulfillment provider. |
fulfillment.rejected |
Card was rejected by card fulfillment provider. |
fulfillment.reordered |
Card was reordered from card fulfillment provider. |
fulfillment.shipped |
Card was shipped by card fulfillment provider. |
The fulfillment_status field (response)
Copy section link
The card transition response contains a
Value | Description |
---|---|
ISSUED |
Initial state of all newly created/issued cards. |
ORDERED |
Card ordered through card fulfillment provider. |
REJECTED |
Card rejected by card fulfillment provider. |
SHIPPED |
Card shipped by card fulfillment provider. |
DIGITALLY_PRESENTED |
Card digitally presented using the /cards/{token}/showpan endpoint; does not affect the delivery of physical cards. |
The validations.user object (response)
Copy section link
The card transition request contains a
Name | Description | Allowable Values |
---|---|---|
birth_date |
Indicates whether the birth_date field in the request was validated. |
true , false |
phone |
Indicates whether the phone field in the request was validated. |
true , false |
ssn |
Indicates whether the ssn field in the request was validated. |
true , false |
Retrieve card transition
Copy section link
Action:
Endpoint:
Retrieves a specific card transition. This endpoint supports field filtering.
URL path parameters
Copy section link
Fields | Description |
---|---|
token
string
|
Identifies the card transition to retrieve. Allowable Values: Existing card transition token. Send a GET request to /cardtransitions/card/{token} to retrieve card transition tokens for a specific card.
|
The channel field (response)
Copy section link
Every card transition has a
Value | Description |
---|---|
ADMIN |
Indicates that the card transition was initiated through the Marqeta Dashboard. |
API |
Indicates that the card transition was initiated by you through the Core API. |
FRAUD |
Indicates that either Marqeta or the card network has determined that the card is fraudulent. |
IVR |
Indicates that the card transition was initiated through your Interactive Voice Response system. |
SYSTEM |
Indicates that the card transition was initiated by Marqeta. For example, Marqeta suspended the card due to excessive failed PIN entries. |
The type field (response)
Copy section link
Every card transition has a
Value | Description |
---|---|
state.activated |
Card was activated. |
state.reinstated |
Card was reinstated from a suspended state. |
state.suspended |
Card was suspended. |
state.terminated |
Card was terminated. |
fulfillment.digitally_presented |
Card was digitally presented using the /cards/{token}/showpan endpoint; does not affect the delivery of physical cards. |
fulfillment.issued |
Card was created/issued. |
fulfillment.ordered |
Card was ordered from card fulfillment provider. |
fulfillment.rejected |
Card was rejected by card fulfillment provider. |
fulfillment.reordered |
Card was reordered from card fulfillment provider. |
fulfillment.shipped |
Card was shipped by card fulfillment provider. |
The fulfillment_status field (response)
Copy section link
The card transition response contains a
Value | Description |
---|---|
ISSUED |
Initial state of all newly created/issued cards. |
ORDERED |
Card ordered through card fulfillment provider. |
REJECTED |
Card rejected by card fulfillment provider. |
SHIPPED |
Card shipped by card fulfillment provider. |
DIGITALLY_PRESENTED |
Card digitally presented using the /cards/{token}/showpan endpoint; does not affect the delivery of physical cards. |
The validations.user object (response)
Copy section link
The card transition request contains a
Name | Description | Allowable Values |
---|---|---|
birth_date |
Indicates whether the birth_date field in the request was validated. |
true , false |
phone |
Indicates whether the phone field in the request was validated. |
true , false |
ssn |
Indicates whether the ssn field in the request was validated. |
true , false |
List transitions for card
Copy section link
Action:
Endpoint:
Lists the transitions for a specific card. This endpoint supports field filtering and pagination.
URL path parameters
Copy section link
Fields | Description |
---|---|
token
string
|
Identifies the card whose state change information you want to retrieve. Allowable Values: Existing card token. Send a GET request to /cards/user/{token} to retrieve card tokens for a specific user.
|
The channel field (response)
Copy section link
Every card transition has a
Value | Description |
---|---|
ADMIN |
Indicates that the card transition was initiated through the Marqeta Dashboard. |
API |
Indicates that the card transition was initiated by you through the Core API. |
FRAUD |
Indicates that either Marqeta or the card network has determined that the card is fraudulent. |
IVR |
Indicates that the card transition was initiated through your Interactive Voice Response system. |
SYSTEM |
Indicates that the card transition was initiated by Marqeta. For example, Marqeta suspended the card due to excessive failed PIN entries. |
The type field (response)
Copy section link
Every card transition has a
Value | Description |
---|---|
state.activated |
Card was activated. |
state.reinstated |
Card was reinstated from a suspended state. |
state.suspended |
Card was suspended. |
state.terminated |
Card was terminated. |
fulfillment.digitally_presented |
Card was digitally presented using the /cards/{token}/showpan endpoint; does not affect the delivery of physical cards. |
fulfillment.issued |
Card was created/issued. |
fulfillment.ordered |
Card was ordered from card fulfillment provider. |
fulfillment.rejected |
Card was rejected by card fulfillment provider. |
fulfillment.reordered |
Card was reordered from card fulfillment provider. |
fulfillment.shipped |
Card was shipped by card fulfillment provider. |
The fulfillment_status field (response)
Copy section link
The card transition response contains a
Value | Description |
---|---|
ISSUED |
Initial state of all newly created/issued cards. |
ORDERED |
Card ordered through card fulfillment provider. |
REJECTED |
Card rejected by card fulfillment provider. |
SHIPPED |
Card shipped by card fulfillment provider. |
DIGITALLY_PRESENTED |
Card digitally presented using the /cards/{token}/showpan endpoint; does not affect the delivery of physical cards. |
The validations.user object (response)
Copy section link
The card transition request contains a
Name | Description | Allowable Values |
---|---|---|
birth_date |
Indicates whether the birth_date field in the request was validated. |
true , false |
phone |
Indicates whether the phone field in the request was validated. |
true , false |
ssn |
Indicates whether the ssn field in the request was validated. |
true , false |
Create PIN control token
Copy section link
Action:
Endpoint:
Creates a control token necessary for creating or updating a card PIN.
Creating a card PIN is a two-step process. You must first create the control token that is required to create the PIN, and then you create the PIN itself.
The lifespan of the control token in a production environment is one hour from creation. Once redeemed, a token cannot be reused.
Body field details
Copy section link
Fields | Description |
---|---|
card_token
string
|
Identifies the card for which you want to generate a control token. Allowable Values: Existing card token. Send a GET request to /cards/user/{token} to retrieve card tokens for a specific user.
|
Create or update PIN
Copy section link
Action:
Endpoint:
Creates or updates a PIN for an existing card.
If you want to update a card’s PIN, you create a new control token for the card, and then use that token to update the PIN. You must create a card before you can create a PIN.
You cannot retrieve a PIN that has previously been created. If the PIN has been forgotten, you must either update the card’s PIN or create a new card and PIN.
Note
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.
Body field details
Copy section link
Fields | Description |
---|---|
control_token
string
|
The unique value generated as a result of issuing a POST request to the /pins/controltoken endpoint.
This value cannot be updated.
Allowable Values: Existing control token |
pin
string
|
The four-digit number to associate with the card. Allowable Values: Must be 4 char |