DOCS

Support
/
Guides
Core API

Launch and manage your company’s payment card program

Core API Reference

Endpoint definitions and field-level reference

Core API Explorer

Try out all endpoints from your browser

DiVA API

Access the production data behind Marqeta’s reporting and analytics tools

DiVA API Reference

Endpoint definitions and field-level reference

45 minute read
March 30, 2021

Cards

Hidden

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

Sign in to use API widgets
POST

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.

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’s
config.card_life_cycle.activate_upon_issue
field (see Card Products).

Send a

POST
request to
/pins/controltoken
to set the card PIN if your program requires PIN numbers (for example, for EMV cards); this action updates the
pin_is_set
field to
true
. See Create or Update PIN on this page for details.

Query parameters
Copy section link

You can use optional query parameters to show the PAN and CVV2 number in the response. If

show_pan
and
show_cvv_number
are set to
true
, the fulfillment state of the card is
DIGITALLY_PRESENTED
instead of the normal 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.

Fields Description

show_pan

boolean
Optional

Set to

true
to show the full PAN in the response.

Allowable Values:

true
,
false

Default value:

false

show_cvv_number

boolean
Optional

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
Optional

The unique identifier of the card.

If you do not include a token, the system will generate one automatically. Other API calls will require this token, so we recommend creating a token that is easy to remember rather than letting the system generate one. This value cannot be updated.

Allowable Values:

36 char max

user_token

string
Required

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
Optional

Determines physical characteristics of a card and shipment information.

Allowable Values:

Existing

fulfillment
object.

reissue_pan_from_card_token

string
Optional

Reissues the specified card (known as the "source" card).

This field reissues a card by copying the PAN and PIN from the specified source card to the newly created card. The reissued card has the same PAN and PIN as the source card but a new expiration date and CVV2 number.

Note
By default, the source card is automatically terminated. However, if your program is configured for multiple active cards, you can prevent the source card from being automatically terminated by setting the
activation_actions.terminate_reissued_source_card
field to
false
.

Allowable Values:

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
Optional

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
Required

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
Optional

Associates the card with the specified bulk card order. This field cannot be updated.

Allowable Values:

36 char max

expedite

boolean
Optional

Set to

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

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

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

Allowable Values:

true
,
false

Default value:

false

expiration_offset

object
Optional

Specifies the length of time 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
Optional

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
Optional

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
Optional

If you are reissuing a card, the source card is terminated by default. To prevent the source card from being terminated, set this field to

false
.

Only relevant when

reissue_pan_from_card_token
is set.

Allowable Values:

true
,
false

Default value:

true

swap_digital_wallet_tokens_from_card_token

string
Optional

Moves all digital wallet tokens from the specified card to the new card.

Not relevant when

reissue_pan_from_card_token
is set.

Allowable Values:

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
Optional

Specifies the units for the

value
field.

Allowable Values:

YEARS
,
MONTHS
,
DAYS
,
HOURS
,
MINUTES
,
SECONDS

Default value:

YEARS

value

integer
Optional

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:

  • YEARS – Rounds up to the last second of the last day of the month of expiration. For example, if the issue date is 1 Jan 2020 and

    value = 1
    , the card expires on the last day of Jan 2021.

  • MONTHS – Rounds up to the last second of the last day of the month of expiration. For example, if the issue date is 1 Jan 2020 and

    value = 1
    , the card expires on the last day of Feb 2020.

  • DAYS – Rounds up to the last second of the day of expiration.

  • HOURS, MINUTES, SECONDS – No rounding.

Allowable Values:

Any positive integer

Default value:
4
The fulfillment object
Copy section link
Fields Description

card_personalization

object
Required

Allows personalized attributes to be added to the card.

Allowable Values:

Existing

fulfillment.card_personalization
object.

shipping

object
Optional

Specifies shipping details for the card.

Allowable Values:

Existing

fulfillment.shipping
object.
The fulfillment.shipping object
Copy section link
Fields Description

return_address

object
Optional

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
Optional

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
Optional

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.

  • LOCAL_MAIL
    (not available for bulk orders, tracking not included)

  • GROUND
    (bulk orders only, tracking included)

  • TWO_DAY
    (tracking included)

  • OVERNIGHT
    (tracking included)

  • INTERNATIONAL
    (tracking included)

care_of_line

string
Optional

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

Note
This field overrides the equivalent field on the associated card product.

Allowable Values:

255 char max
The fulfillment.shipping.return_address & recipient_address objects
Copy section link
Fields Description

address1

string
Optional

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
Optional

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
Optional

City.

Allowable Values:

40 char max

state

string
Optional

State.

Allowable Values:

32 char max

postal_code

string
Optional

Postal code.

Allowable Values:

10 char max

country

string
Optional

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
Optional

Telephone number.

Allowable Values:

20 char max

first_name

string
Required

First name.

Allowable Values:

40 char max

middle_name

string
Optional

Middle name.

Allowable Values:

40 char max

last_name

string
Required

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
Required

Specifies personalized text that appears on the card.

Allowable Values:

Existing

fulfillment.card_personalization.text
object.

carrier

object
Optional

Specifies attributes of the card carrier (if your fulfillment provider is Arroweye Solutions).

Allowable Values:

Existing

fulfillment.card_personalization.carrier
object.

images

object
Optional

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.

Note
The
images
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
Optional

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
Required

First line of personalized text printed on the face of the card.

Allowable Values:

Valid characters differ according to your fulfillment provider:

  • For Arroweye Solutions, IDEMIA Poland, and IDEMIA Czech Republic, all characters are valid. For specific character and language guidelines, contact your fulfillment provider.

  • For all other providers, valid characters are:

    • A-Z (uppercase letters)

    • a-z (lowercase letters)

    • 0-9 (integers)

    •  
      (space)

    • .
      (period)

    • ,
      (comma)

    • /
      (forward slash)

    • -
      (hyphen)

    • &
      (ampersand)

    • '
      (single quote)

    • @
      (stylized D for Discover cards)

21 char max Strings longer than 21 characters are truncated.

name_line_2.value

string
Optional

Second line of personalized text printed on the face of the card.

Allowable Values:

Valid characters differ according to your fulfillment provider:

  • For Arroweye Solutions, IDEMIA Poland, and IDEMIA Czech Republic, all characters are valid. For specific character and language guidelines, contact your fulfillment provider.

  • For all other providers, valid characters are:

    • A-Z (uppercase letters)

    • a-z (lowercase letters)

    • 0-9 (integers)

    •  
      (space)

    • .
      (period)

    • ,
      (comma)

    • /
      (forward slash)

    • -
      (hyphen)

    • &
      (ampersand)

    • '
      (single quote)

    • @
      (stylized D for Discover cards)

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
Optional

Third line of personalized text printed on the face of the card.

Allowable Values:

Valid characters differ according to your fulfillment provider:

  • For Arroweye Solutions, IDEMIA Poland, and IDEMIA Czech Republic, all characters are valid. For specific character and language guidelines, contact your fulfillment provider.

  • For all other providers, valid characters are:

    • A-Z (uppercase letters)

    • a-z (lowercase letters)

    • 0-9 (integers)

    •  
      (space)

    • .
      (period)

    • ,
      (comma)

    • /
      (forward slash)

    • -
      (hyphen)

    • &
      (ampersand)

    • '
      (single quote)

    • @
      (stylized D for Discover cards)

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
Optional

Specifies the card carrier template to use.

Allowable Values:

A card carrier template ID.

logo_file

string
Optional

Specifies an image to display on the card carrier.

Allowable Values:

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

logo_thumbnail_file

string
Optional

Specifies a thumbnail-sized rendering of the image specified in the

logo_file
field.

Allowable Values:

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

message_file

string
Optional

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

Allowable Values:

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

message_line

string
Optional

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
Optional

Specifies personalized images that appear on the card.

Allowable Values:

Existing

card
object.

signature.name

string
Optional

Specifies a PNG image of the cardholder’s signature.

Allowable Values:

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

Must end in

.png
.

carrier_return_window.name

string
Optional

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

Allowable Values:

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

Must end in

.png
.
The fulfillment.card_personalization.images.card object
Copy section link
Fields Description

name

string
Optional

Specifies a PNG image to display on the card.

Allowable Values:

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

Must end in

.png
.

thermal_color

string
Optional

Specifies the color of the image displayed on the card.

Allowable Values:

Contains the name of the color, and must match one of the provider’s predefined colors.
The metadata object
Copy section link
Fields Description

customer_defined_name_01 customer_defined_name_02

…​

customer_defined_name_20

string
Optional

Associates customer-injected metadata with the card. You can define the names and values of up to 20 fields, for example:

Copied

Allowable Values:

  • Up to 20 name-value pairs

  • 255 char max per name

  • 255 char max per value
Card state and fulfillment status
Copy section link

Every card object has state and fulfillment status fields that cannot be set directly using the

/cards
endpoint. A card’s state and physical order fulfillment status are managed either by the Marqeta platform or through the
/cardtransitions
endpoint (see Managing Lost, Stolen, or Damaged Cards.

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.
Sample request body
Copy section link
Copied

Is this helpful?

Yes
No
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

Retrieve card
Copy section link

Action:

GET

Endpoint:
/cards/{token}

Sign in to use API widgets
GET

Retrieves a specific card.

This endpoint supports field filtering and object expansion.

URL path parameters
Copy section link
Fields Description

token

string
Required

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.
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

Update card
Copy section link

Action:

PUT

Endpoint:
/cards/{token}

Sign in to use API widgets
PUT

Updates the details of an existing card.

URL path parameters
Copy section link
Fields Description

token

string
Required

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
Optional

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
Optional

Set to

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

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

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

Allowable Values:

true
,
false

Default value:
false

fulfillment

object
Optional

Determines physical characteristics of a card and shipment information.

Allowable Values:

Existing

fulfillment
object.

metadata

object
Optional

Associates customer-injected metadata with the card.

Allowable Values:

Existing

metadata
object.
The fulfillment object
Copy section link
Fields Description

card_personalization

object
Required

Allows personalized attributes to be added to the card.

Allowable Values:

Existing

fulfillment.card_personalization
object.

shipping

object
Optional

Specifies shipping details for the card.

Allowable Values:

Existing

fulfillment.shipping
object.
The fulfillment.shipping object
Copy section link
Fields Description

return_address

object
Optional

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
Optional

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
Optional

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.

  • LOCAL_MAIL
    (not available for bulk orders, tracking not included)

  • GROUND
    (bulk orders only, tracking included)

  • TWO_DAY
    (tracking included)

  • OVERNIGHT
    (tracking included)

  • INTERNATIONAL
    (tracking included)

care_of_line

string
Optional

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

Note
This field overrides the equivalent field on the associated card product.

Allowable Values:

255 char max
The fulfillment.shipping.return_address & recipient_address objects
Copy section link
Fields Description

address1

string
Optional

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
Optional

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
Optional

City.

Allowable Values:

40 char max

state

string
Optional

State.

Allowable Values:

32 char max

postal_code

string
Optional

Postal code.

Allowable Values:

10 char max

country

string
Optional

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
Optional

Telephone number.

Allowable Values:

20 char max

first_name

string
Required

First name.

Allowable Values:

40 char max

middle_name

string
Optional

Middle name.

Allowable Values:

40 char max

last_name

string
Required

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
Required

Specifies personalized text that appears on the card.

Allowable Values:

Existing

fulfillment.card_personalization.text
object.

carrier

object
Optional

Specifies attributes of the card carrier (if your fulfillment provider is Arroweye Solutions).

Allowable Values:

Existing

fulfillment.card_personalization.carrier
object.

images

object
Optional

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
Required

First line of personalized text printed on the face of the card.

Allowable Values:

Valid characters differ according to your fulfillment provider:

  • For Arroweye Solutions, IDEMIA Poland, and IDEMIA Czech Republic, all characters are valid. For specific character and language guidelines, contact your fulfillment provider.

  • For all other providers, valid characters are:

    • A-Z (uppercase letters)

    • a-z (lowercase letters)

    • 0-9 (integers)

    •  
      (space)

    • .
      (period)

    • ,
      (comma)

    • /
      (forward slash)

    • -
      (hyphen)

    • &
      (ampersand)

    • '
      (single quote)

    • @
      (stylized D for Discover cards)

21 char max Strings longer than 21 characters are truncated.

name_line_2.value

string
Optional

Second line of personalized text printed on the face of the card.

Allowable Values:

Valid characters differ according to your fulfillment provider:

  • For Arroweye Solutions, IDEMIA Poland, and IDEMIA Czech Republic, all characters are valid. For specific character and language guidelines, contact your fulfillment provider.

  • For all other providers, valid characters are:

    • A-Z (uppercase letters)

    • a-z (lowercase letters)

    • 0-9 (integers)

    •  
      (space)

    • .
      (period)

    • ,
      (comma)

    • /
      (forward slash)

    • -
      (hyphen)

    • &
      (ampersand)

    • '
      (single quote)

    • @
      (stylized D for Discover cards)

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
Optional

Third line of personalized text printed on the face of the card.

Allowable Values:

Valid characters differ according to your fulfillment provider:

  • For Arroweye Solutions, IDEMIA Poland, and IDEMIA Czech Republic, all characters are valid. For specific character and language guidelines, contact your fulfillment provider.

  • For all other providers, valid characters are:

    • A-Z (uppercase letters)

    • a-z (lowercase letters)

    • 0-9 (integers)

    •  
      (space)

    • .
      (period)

    • ,
      (comma)

    • /
      (forward slash)

    • -
      (hyphen)

    • &
      (ampersand)

    • '
      (single quote)

    • @
      (stylized D for Discover cards)

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
Optional

Specifies the card carrier template to use.

Allowable Values:

A card carrier template ID.

logo_file

string
Optional

Specifies an image to display on the card carrier.

Allowable Values:

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

logo_thumbnail_file

string
Optional

Specifies a thumbnail-sized rendering of the image specified in the

logo_file
field.

Allowable Values:

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

message_file

string
Optional

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

Allowable Values:

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

message_line

string
Optional

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
Optional

Specifies personalized images that appear on the card.

Allowable Values:

Existing

fulfillment.card_personalization.images.card
object.

signature.name

string
Optional

Specifies a PNG image of the cardholder’s signature.

Allowable Values:

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

Must end in

.png
.

carrier_return_window.name

string
Optional

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

Allowable Values:

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

Must end in

.png
.
The fulfillment.card_personalization.images.card object
Copy section link
Fields Description

name

string
Optional

Specifies a PNG image to display on the card.

Allowable Values:

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

Must end in

.png
.

thermal_color

string
Optional

Specifies the color of the image displayed on the card.

Allowable Values:

Contains the name of the color, and must match one of the provider’s predefined colors.
The metadata object
Copy section link
Fields Description

customer_defined_name_01 customer_defined_name_02

…​

customer_defined_name_20

string
Optional

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:

  • Up to 20 name-value pairs

  • 255 char max per name

  • 255 char max per value
Sample request body
Copy section link
Copied

Is this helpful?

Yes
No
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

List cards for user
Copy section link

Action:

GET

Endpoint:
/cards/user/{token}

Sign in to use API widgets
GET

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
Required

Identifies the user whose cards you want to list.

Allowable Values:

Existing user token.

Send a

GET
request to
/users
to retrieve user tokens.
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

Retrieve card by PAN
Copy section link

Action:

POST

Endpoint:
/cards/getbypan

Sign in to use API widgets
POST

Retrieves the

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

This 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

POST
call because supplying the PAN in the request body is more secure than supplying it in the URL (as would be required with a
GET
).

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
Required

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

Allowable Values:

16 char max

Send a

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

cvv_number

string
Optional

The three-digit card verification value (CVV2) included on the back of the card.

This value cannot be updated.

Allowable Values:

3 char max

expiration

string
Optional

Card expiration date.

Allowable Values:

mmyy
Sample request body
Copy section link
Copied

Is this helpful?

Yes
No
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

Show card PAN
Copy section link

Action:

GET

Endpoint:
/cards/{token}/showpan

Sign in to use API widgets
GET

Retrieves a PAN (card number). For security reasons, the PAN is not fully visible on the card resource returned by

GET
/cards/{token}
.

This endpoint supports field filtering and object expansion.

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
Required

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
Optional

Set to

true
to display the full CVV2 number in the response.

Allowable Values:

true
,
false
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

Retrieve card by barcode
Copy section link

Action:

GET

Endpoint:
/cards/barcode/{barcode}

Sign in to use API widgets
GET

Retrieves a card by its barcode.

This endpoint supports field filtering and object expansion.

URL path parameters
Copy section link
Fields Description

barcode

string
Required

The barcode of the card to retrieve.

Allowable Values:

Existing barcode
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

List cards by last four digits of PAN
Copy section link

Action:

GET

Endpoint:
/cards

Sign in to use API widgets
GET

Retrieves an array of cards whose PANs end in the four digits specified by the

last_four
query parameter.

This endpoint supports field filtering, object expansion, sorting, and pagination.

Query parameters
Copy section link
Fields Description

last_four

string
Required

The last four digits of the PAN of the card you want to locate.

Allowable Values:

four-digit string
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

Create onboarding card
Copy section link

Action:

POST

Endpoint:
/cards/merchant/{merchant_token}

Sign in to use API widgets
POST

Creates a merchant onboarding card. You cannot set the

token
field for this card; the merchant token is automatically used as the card token.

The card product passed into the

POST
must have the
merchant_on_boarding
field set to
true
. When a merchant onboarding card is created, the Marqeta platform automatically creates a user for the merchant, using the merchant’s token as the user token value. There can only be one merchant onboarding card per merchant.

As a result of the

POST
to
/cards/merchant/{merchant_token}
, the Marqeta platform automatically generates a PAN and sets the
pin_is_set
field to
false
. In addition, the
last_four
field is set to the last 4 digits of the PAN, and the
expiration
field is set to the current month plus four years (mmyy). Finally, the
cvv_number
is also generated, but is not visible in the response.

URL path parameters
Copy section link
Fields Description

merchant_token

string
Required

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
Required

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
Optional

Set to

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

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

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

Allowable Values:

true
,
false

Default value:

false
Sample request body
Copy section link
Copied

Is this helpful?

Yes
No
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

Retrieve onboarding card
Copy section link

Action:

GET

Endpoint:
/cards/merchant/{merchant_token}

Sign in to use API widgets
GET

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
Required

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.
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

Show onboarding card PAN
Copy section link

Action:

GET

Endpoint:
/cards/merchant/{merchant_token}/showpan

Sign in to use API widgets
GET

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

GET
/cards/merchant/{token}
.

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
Required

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
Optional

Set to

true
to display the full CVV2 number in the response.

Allowable Values:

true
,
false
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

Create card transition
Copy section link

Action:

POST

Endpoint:
/cardtransitions

Sign in to use API widgets
POST

Creates a card state transition to set the state of an existing card.

If your system uses IVR, you can send a

POST
to
/cards/getbypan
to retrieve a card token, which you can then use in your
POST
request to
/cardtransitions
.

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
Optional

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
Required

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
Required

Specifies the new state.

Allowable Values:

ACTIVE
,
SUSPENDED
,
TERMINATED

channel

string
Required

The mechanism by which the transition was initiated.

  • 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. Use this value when creating a card transition with an API

    POST
    request.

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

Allowable Values:

ADMIN
,
API
,
FRAUD
,
IVR
,
SYSTEM

reason

string
Optional

Additional information about the state change.

Allowable Values:

255 char max

reason_code

string
Optional

A standard code describing the reason for the transition.

Allowable Values:

See The reason_code field section.

validations

object
Optional

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

This address cannot accept mail or the addressee is unknown.

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.

19

Changed to

ACTIVE
because account activity was properly validated.

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.

24

Address issue.

25

Name issue.

26

SSN issue.

27

DOB issue.

28

Email issue.

29

Phone issue.

30

Account/fulfillment mismatch.

31

Other reason.
The validations object
Copy section link
Fields Description

user

object
Optional

Contains information about the user.

Allowable Values: Existing

validations
object

The validations.user object
Copy section link
Fields Description

birth_date

string
Optional

The birth date of the user associated with this card.

Allowable Values:

Format: yyyy-MM-dd

phone

string
Optional

The telephone number of the user associated with this card.

Allowable Values:

5105551212 or 510-555-1212

ssn

string
Optional

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

type
field, which cannot be set directly using the
/cardtransitions
endpoint. A card transition’s type is managed by the Marqeta platform, based on the before and after state of the transition, as specified in the request’s
state
field. The
type
field is returned in the response. The following table describes this field’s possible values:

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. This field appears only when populated by the card fulfillment provider.
The fulfillment_status field (response)
Copy section link

The card transition response contains a

fulfillment_status
field that provides status information about the card related to order and delivery. The following table describes this field’s possible values:

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

validations.user
object, which contains several fields. The Marqeta platform validates the field values in the request and returns the fields as booleans in the response. A value of
true
indicates that a field was successfully validated. The following table describes these fields:

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
Sample request body
Copy section link
Copied

Is this helpful?

Yes
No
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

Retrieve card transition
Copy section link

Action:

GET

Endpoint:
/cardtransitions/{token}

Sign in to use API widgets
GET

Retrieves a specific card transition. This endpoint supports field filtering.

URL path parameters
Copy section link
Fields Description

token

string
Required

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

channel
field that indicates how the card transition was initiated. The
channel
field is returned in the response. The following table describes this field’s possible values:

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

type
field, which cannot be set directly using the
/cardtransitions
endpoint. A card transition’s type is managed by the Marqeta platform, based on the before and after state of the transition, as specified in the request’s
state
field. The
type
field is returned in the response. The following table describes this field’s possible values:

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. This field appears only when populated by the card fulfillment provider.
The fulfillment_status field (response)
Copy section link

The card transition response contains a

fulfillment_status
field that provides status information about the card related to order and delivery. The following table describes this field’s possible values:

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

validations.user
object, which contains several fields. The Marqeta platform validates the field values in the request and returns the fields as booleans in the response. A value of
true
indicates that a field was successfully validated. The following table describes these fields:

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
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

List transitions for card
Copy section link

Action:

GET

Endpoint:
/cardtransitions/card/{token}

Sign in to use API widgets
GET

Retrieves a list of the transitions for a specific card. This endpoint supports field filtering and pagination.

URL path parameters
Copy section link
Fields Description

token

string
Required

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

channel
field that indicates how the card transition was initiated. The
channel
field is returned in the response. The following table describes this field’s possible values:

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

type
field, which cannot be set directly using the
/cardtransitions
endpoint. A card transition’s type is managed by the Marqeta platform, based on the before and after state of the transition, as specified in the request’s
state
field. The
type
field is returned in the response. The following table describes this field’s possible values:

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. This field appears only when populated by the card fulfillment provider.
The fulfillment_status field (response)
Copy section link

The card transition response contains a

fulfillment_status
field that provides status information about the card related to order and delivery. The following table describes this field’s possible values:

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

validations.user
object, which contains several fields. The Marqeta platform validates the field values in the request and returns the fields as booleans in the response. A value of
true
indicates that a field was successfully validated. The following table describes these fields:

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
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

Create PIN control token
Copy section link

Action:

POST

Endpoint:
/pins/controltoken

Sign in to use API widgets
POST

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
Required

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.
Sample request body
Copy section link
Copied

Is this helpful?

Yes
No
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

Create or update PIN
Copy section link

Action:

PUT

Endpoint:
/pins

Sign in to use API widgets
PUT

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
Required

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
Required

The four-digit number to associate with the card.

Allowable Values:

Must be 4 char
Sample request body
Copy section link
Copied

Is this helpful?

Yes
No
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No
Related materials

Feedback on this page?

If you feel we can do anything better, please let our team know.

© 2021 Marqeta, Inc.

• Terms
 • API Terms
 • Privacy
 • Cookies
Back to Marqeta.com