DOCS

New!

Support
Sign in to get developer support

Marqeta Home

/
Developer Guides
Core API Reference
DiVA API Reference
Core API Explorer

40 minute read

November 2, 2019

Cards

The cards resource represents the payment cards with which users conduct transactions. Cards are owned by users and communicate with the Marqeta platform over card networks such as Discover, Mastercard, and Visa. Each card has a number of attributes, such as a primary account number (PAN), expiration date, and card verification value (CVV2). Cards are derived from and controlled by a card product.

Some attributes of the card object can also be defined in an associated bulkissuance or cardproduct object. If you define one of these attributes in more than one object, the Marqeta platform applies an order of precedence to determine which attribute to use at fulfillment time. The order of precedence is as follows:

  1. card

  2. bulkissuance

  3. cardproduct

Defining an attribute in an object with higher precedence does not overwrite the same attribute in a lower-precedence object; the Marqeta platform ignores these lower-precedence attributes.

Note
For an overview of cards and the card object, see About Cards.

Create card
Copy section link

Action: POST
Endpoint: /cards

Develop Now!

Sign in and use your sandbox to access the API Explorer

Create a card using the user_token of the user that will own the card and the card_product_token of the card product that will control the card. You must therefore create the user and card product before you can create the card.

Note
By default, newly created cards are inactive and must be explicitly activated (see Create Card Transition for information on activating cards). Alternatively, you can configure your card product’s config.card_life_cycle.activate_upon_issue field such that cards are activated upon issue (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 the "Create or Update PIN" section on this page for details).

Query parameters
Copy section link

You can use optional query parameters to show both 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 alternate state does not affect the delivery of physical cards.

Note
Sending a request to 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 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.
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. This token is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. 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:

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 and shipping of the card. Expedited orders ignore the setting of the fulfillment.shipping.method field and always ship by FedEx Priority mail.

This expedited service is available only for cards fulfilled by Perfect Plastic Printing and IDEMIA. For other fulfillment providers, set this field to false.

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:

activation_actions

object, optional

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

Allowable Values:

metadata

object, optional

Associates customer-injected metadata with the user.

Allowable Values:

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 2019 and value=1, the card expires on the last day of Jan 2020.

  • 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 2019 and value=1, the card expires on the last day of Feb 2019.

  • 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, optional

Allows personalized attributes to be added to the card.

shipping

object, optional

Specifies shipping details for the card.

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 USA if the country field is unpopulated.

Allowable Values:

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 USA if the country field is unpopulated.

Allowable Values:

method

string, optional

Specifies the shipping company and shipping service level.

  • If your fulfillment provider is either Perfect Plastic Printing or IDEMIA and the expedite field is set to true, this field is ignored and the shipping method is implicitly FEDEX_EXPEDITED.

  • If your fulfillment provider is either Perfect Plastic Printing or IDEMIA and the expedite field is set to false, you must specify the shipping company and service level using the method field.

  • If your fulfillment provider is Arroweye Solutions, you must specify the shipping company and service level using the method field.

Allowable Values:

Values allowed depend on your fulfillment provider.

Perfect Plastic Printing and IDEMIA: USPS_REGULAR, FEDEX_EXPEDITED

Arroweye Solutions: UPS_REGULAR, UPS_EXPEDITED, USPS_REGULAR, USPS_EXPEDITED

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:

50 char max

state

string, optional

State.

Allowable Values:

50 char max

postal_code

string, optional

Postal code.

Allowable Values:

50 char max

country

string, optional

Country.

Allowable Values:

40 char max

phone

string, optional

Telephone number.

Allowable Values:

50 char max

first_name

string, optional

First Name.

Allowable Values:

50 char max

middle_name

string, optional

Middle Name.

Allowable Values:

50 char max

last_name

string, optional

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, optional

Specifies personalized text that appears on the card.

Allowable Values:

carrier

object, optional

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

Allowable Values:

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, optional

First line of personalized text printed on the card.

Allowable Values:

The card can accommodate only 21 characters. Strings longer than 21 characters are truncated.

name_line_2.value

string, optional

Second line of personalized text printed on the card.

Allowable Values:

The card can accommodate only 21 characters. Strings longer than 21 characters are truncated.

name_line_3.value

string, optional

Third line of personalized text printed on the card.

Allowable Values:

The card can accommodate only 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:

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. The Marqeta customer defines the names and values of up to 20 fields, for example:

"metadata": {
  "my_name_1": "my_value_1",
  "my_name_2": "my_value_2"
}

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 is 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

{
  "token": "mytestcard01",
  "user_token": "my_user_01",
  "fulfillment": {
    "card_personalization": {
      "text": {
          "name_line_1": {
            "value": "My card personalization line 1"
          },
          "name_line_2": {
            "value": "My card personalization line 2"
          }
      },
      "carrier": {
        "name": "my_carrier_logo.png",
        "message_line": "My message"
        },
      "images": {
        "card": {
           "name": "my_card_logo.png",
           "thermal_color": "Black"
        },
        "signature": {
          "name": "my_signature.png"
        },
        "carrier_return_window": {
          "name": "my_return_address_image.png"
        }
      }
    }
  },
  "card_product_token": "red_cardproduct",
  "metadata": {
    	"key1":"value1",
    	"key2":"value2"
  }
}

Is this helpful?

Sample response body
Copy section link

{
  "created_time": "2019-02-14T18:48:10Z",
  "last_modified_time": "2019-02-14T18:48:10Z",
  "token": "mytestcard01",
  "user_token": "my_user_01",
  "card_product_token": "red_cardproduct",
  "last_four": "8949",
  "pan": "111111______8949",
  "expiration": "0221",
  "expiration_time": "2021-02-28T23:59:59Z",
  "barcode": "17469201908992951865",
  "pin_is_set": false,
  "state": "UNACTIVATED",
  "state_reason": "New card",
  "expedite": false,
  "fulfillment_status": "ISSUED",
  "fulfillment": {
    "card_personalization": {
      "text": {
          "name_line_1": {
            "value": "My card personalization line 1"
          },
          "name_line_2": {
            "value": "My card personalization line 2"
          }
        },
      "carrier": {
        "name": "my_carrier_logo.png",
        "message_line": "My message"
        },
      "images": {
        "card": {
           "name": "my_card_logo.png",
           "thermal_color": "Black"
        },
        "signature": {
          "name": "my_signature.png"
        },
        "carrier_return_window": {
          "name": "my_return_address_image.png"
        }
      }
    }
  },
  "instrument_type": "PHYSICAL_MSR",
  "metadata": {
    	"key1":"value1",
    	"key2":"value2"
  }
}

Is this helpful?

Retrieve card
Copy section link

Action: GET
Endpoint: /cards/{token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

Retrieve 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

{
  "created_time": "2019-02-14T18:48:10Z",
  "last_modified_time": "2019-02-14T18:48:10Z",
  "token": "mytestcard01",
  "user_token": "my_user_01",
  "card_product_token": "red_cardproduct",
  "last_four": "8949",
  "pan": "111111______8949",
  "expiration": "0221",
  "expiration_time": "2021-02-28T23:59:59Z",
  "barcode": "17469201908992951865",
  "pin_is_set": false,
  "state": "UNACTIVATED",
  "state_reason": "New card",
  "expedite": false,
  "fulfillment_status": "ISSUED",
  "fulfillment": {
    "card_personalization": {
      "text": {
          "name_line_1": {
            "value": "My card personalization line 1"
          },
          "name_line_2": {
            "value": "My card personalization line 2"
          }
      },
      "carrier": {
        "name": "my_carrier_logo.png",
        "message_line": "My message"
      },
      "images": {
        "card": {
           "name": "my_card_logo.png",
           "thermal_color": "Black"
        },
        "signature": {
          "name": "my_signature.png"
        },
        "carrier_return_window": {
          "name": "my_return_address_image.png"
        }
      }
    }
  },
  "instrument_type": "PHYSICAL_MSR",
  "metadata": {
    	"key1":"value1",
    	"key2":"value2"
  }
}

Is this helpful?

Update card
Copy section link

Action: PUT
Endpoint: /cards/{token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

Update 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 and shipping of the card. Expedited orders ignore the setting of the fulfillment.shipping.method field and always ship by FedEx Priority mail.

This expedited service is available only for cards fulfilled by Perfect Plastic Printing and IDEMIA. For other fulfillment providers, set this field to false.

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:

metadata

object, optional

Associates customer-injected metadata with the card.

Allowable Values:

The fulfillment object
Copy section link

Fields Description

card_personalization

object, optional

Allows personalized attributes to be added to the card.

shipping

object, optional

Specifies shipping details for the card.

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 USA if the country field is unpopulated.

Allowable Values:

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 USA if the country field is unpopulated.

Allowable Values:

method

string, optional

Specifies the shipping company and shipping service level.

  • If your fulfillment provider is either Perfect Plastic Printing or IDEMIA and the expedite field is set to true, this field is ignored and the shipping method is implicitly FEDEX_EXPEDITED.

  • If your fulfillment provider is either Perfect Plastic Printing or IDEMIA and the expedite field is set to false, you must specify the shipping company and service level using the method field.

  • If your fulfillment provider is Arroweye Solutions, you must specify the shipping company and service level using the method field.

Allowable Values:

Values allowed depend on your fulfillment provider.

Perfect Plastic Printing and IDEMIA: USPS_REGULAR, FEDEX_EXPEDITED

Arroweye Solutions: UPS_REGULAR, UPS_EXPEDITED, USPS_REGULAR, USPS_EXPEDITED

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:

50 char max

state

string, optional

State.

Allowable Values:

50 char max

postal_code

string, optional

Postal code.

Allowable Values:

50 char max

country

string, optional

Country.

Allowable Values:

40 char max

phone

string, optional

Telephone number.

Allowable Values:

50 char max

first_name

string, optional

First Name.

Allowable Values:

50 char max

middle_name

string, optional

Middle Name.

Allowable Values:

50 char max

last_name

string, optional

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, optional

Specifies personalized text that appears on the card.

carrier

object, optional

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

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.

The fulfillment.card_personalization.text object
Copy section link

Fields Description

name_line_1.value

string, optional

First line of personalized text printed on the card.

Allowable Values:

The card can accommodate only 21 characters. Strings longer than 21 characters are truncated.

name_line_2.value

string, optional

Second line of personalized text printed on the card.

Allowable Values:

The card can accommodate only 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.

The fulfillment.card_personalization.images object
Copy section link

Fields Description

card

object, optional

Specifies personalized images that appear on the card.

Allowable Values:

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. The Marqeta customer defines the names and values of up to 20 fields, for example:

"metadata": {
  "my_name_1": "my_value_1",
  "my_name_2": "my_value_2"
}

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:

"metadata": {
  "my_name_1": "my_updated_value"
}

Add a new field:

"metadata": {
  "my_new_field": "my_value"
}

Delete an existing field:

"metadata": {
  "my_name_1": null
}

Allowable Values:

  • Up to 20 name-value pairs

  • 255 char max per name

  • 255 char max per value

Sample request body
Copy section link

{
  "user_token": "my_user_03"
}

Is this helpful?

Sample response body
Copy section link

{
  "created_time": "2019-02-14T18:48:10Z",
  "last_modified_time": "2019-02-14T19:03:04Z",
  "token": "mytestcard01",
  "user_token": "my_user_03",
  "card_product_token": "red_cardproduct",
  "last_four": "8949",
  "pan": "111111______8949",
  "expiration": "0221",
  "expiration_time": "2021-02-28T23:59:59Z",
  "barcode": "17469201908992951865",
  "pin_is_set": false,
  "state": "UNACTIVATED",
  "state_reason": "New card",
  "expedite": false,
  "fulfillment_status": "ISSUED",
  "fulfillment": {
    "shipping": {
      "method": "FEDEX_EXPEDITED",
      "return_address": {
        "address1": "123 Henry St",
        "address2": "Suite 101",
        "city": "Porterville",
        "state": "CA",
        "postal_code": "93257",
        "country": "USA",
        "phone": "831-555-5555",
        "first_name": "Saki",
        "middle_name": "R",
        "last_name": "Dogger"
      },
      "recipient_address": {
        "address1": "1000 Pacific Ave",
        "city": "Santa Lucia",
        "state": "WA",
        "postal_code": "00112",
        "country": "USA",
        "phone": "345-123-9876",
        "first_name": "Big",
        "last_name": "Bird"
      }
    },
    "card_personalization": {
      "text": {
          "name_line_1": {
            "value": "My card personalization line 1"
          },
          "name_line_2": {
            "value": "My card personalization line 2"
          }
      },
      "carrier": {
        "name": "my_carrier_logo.png",
        "message_line": "My message"
      },
      "images": {
        "card": {
           "name": "my_card_logo.png",
           "thermal_color": "Black"
        },
        "signature": {
          "name": "my_signature.png"
        },
        "carrier_return_window": {
          "name": "my_return_address_image.png"
        }
      }
    }
  },
  "instrument_type": "PHYSICAL_MSR",
  "metadata": {
    	"key1":"value1"
  }
}

Is this helpful?

List cards for user
Copy section link

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

Develop Now!

Sign in and use your sandbox to access the API Explorer

List 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

{
  "count": 3,
  "start_index": 0,
  "end_index": 2,
  "is_more": false,
  "data": [
    {
      "created_time": "2018-10-24T21:23:31Z",
      "last_modified_time": "2019-01-12T19:55:09Z",
      "token": "my_user_01_card_01",
      "user_token": "my_user_01",
      "card_product_token": "blue_cardproduct",
      "last_four": "2160",
      "pan": "111111______2160",
      "expiration": "1026",
      "expiration_time": "2026-10-31T23:59:59Z",
      "barcode": "11379418395311581864",
      "pin_is_set": false,
      "state": "SUSPENDED",
      "state_reason": "I do not want to use this card, so suspend it.",
      "expedite": false,
      "fulfillment_status": "ISSUED",
      "instrument_type": "PHYSICAL_MSR"
    },
    {
      "created_time": "2018-12-28T18:31:23Z",
      "last_modified_time": "2018-12-28T18:31:23Z",
      "token": "my_user_01_card_02",
      "user_token": "my_user_01",
      "card_product_token": "red_cardproduct",
      "last_four": "0865",
      "pan": "111111______0865",
      "expiration": "1220",
      "expiration_time": "2020-12-31T23:59:59Z",
      "barcode": "25815105237561780909",
      "pin_is_set": false,
      "state": "UNACTIVATED",
      "state_reason": "New card",
      "expedite": false,
      "fulfillment_status": "ISSUED",
      "fulfillment": {
        "shipping": {
          "method": "FEDEX_REGULAR",
          "care_of_line": "my_care_of_value"
        }
      },
     "instrument_type": "PHYSICAL_MSR"
    },
    {
      "created_time": "2018-11-03T21:55:08Z",
      "last_modified_time": "2018-11-03T21:55:08Z",
      "token": "my_user-01-child_01_card_01",
      "user_token": "my_user-01-child_01",
      "card_product_token": "blue_cardproduct",
      "last_four": "2810",
      "pan": "111111______2810",
      "expiration": "1126",
      "expiration_time": "2026-11-30T23:59:59Z",
      "barcode": "63143403984499099324",
      "pin_is_set": false,
      "state": "UNACTIVATED",
      "state_reason": "New card",
      "expedite": false,
      "fulfillment_status": "ISSUED",
      "instrument_type": "PHYSICAL_MSR"
    }
  ]
}

Is this helpful?

Retrieve card by PAN
Copy section link

Action: POST
Endpoint: /cards/getbypan

Develop Now!

Sign in and use your sandbox to access the API Explorer

Retrieve 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

{
    "pan": "5454545454545454"
}

Is this helpful?

Sample response body
Copy section link

{
    "user_token": "my_user",
    "card_token": "my_card1"
}

Is this helpful?

Show card PAN
Copy section link

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

Develop Now!

Sign in and use your sandbox to access the API Explorer

Retrieve 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, required

Set to true to display the full CVV2 number in the response.

Allowable Values:

true, false

Sample response body
Copy section link

{
  "created_time": "2018-12-28T18:31:23Z",
  "last_modified_time": "2019-02-14T19:32:38Z",
  "token": "my_user_01_card_02",
  "user_token": "my_user_01",
  "card_product_token": "red_cardproduct",
  "last_four": "0865",
  "pan": "1111111824980865",
  "expiration": "1220",
  "expiration_time": "2020-12-31T23:59:59Z",
  "cvv_number": "137",
  "barcode": "25815105237561780909",
  "pin_is_set": false,
  "state": "UNACTIVATED",
  "state_reason": "New card",
  "expedite": false,
  "fulfillment_status": "DIGITALLY_PRESENTED",
  "fulfillment": {
    "shipping": {
      "method": "FEDEX_REGULAR",
      "care_of_line": "my_care_of_value"
    }
  },
  "instrument_type": "PHYSICAL_MSR"
}

Is this helpful?

Retrieve card by barcode
Copy section link

Action: GET
Endpoint: /cards/barcode/{barcode}

Develop Now!

Sign in and use your sandbox to access the API Explorer

Retrieve 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

{
    "token": "my_card",
    "pan": "545454______5454",
    "expiration": "0216",
    "barcode": "780672318863",
    "state": "ACTIVE",
    "user_token": "my_user",
    "card_product_token": "my_cardproduct",
    "last_four": "5454",
    "expiration_time": "2018-02-29T23:59:59Z",
    "pin_is_set": "false",
    "expedite": false,
    "fulfillment_status": "SHIPPED",
    "instrument_type": "PHYSICAL_MSR"
}

Is this helpful?

List cards by last four digits of PAN
Copy section link

Action: GET
Endpoint: /cards

Develop Now!

Sign in and use your sandbox to access the API Explorer

Retrieve 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

{
  "count": 1,
  "start_index": 0,
  "end_index": 0,
  "is_more": false,
  "data": [
    {
      "created_time": "2018-12-28T18:31:23Z",
      "last_modified_time": "2019-02-14T19:32:38Z",
      "token": "my_user_01_card_02",
      "user_token": "my_user_01",
      "card_product_token": "red_cardproduct",
      "last_four": "0865",
      "pan": "111111______0865",
      "expiration": "1220",
      "expiration_time": "2020-12-31T23:59:59Z",
      "barcode": "25815105237561780909",
      "pin_is_set": false,
      "state": "UNACTIVATED",
      "state_reason": "New card",
      "expedite": false,
      "fulfillment_status": "DIGITALLY_PRESENTED",
      "fulfillment": {
        "shipping": {
          "method": "FEDEX_REGULAR",
          "care_of_line": "my_care_of_value"
        }
      },
      "instrument_type": "PHYSICAL_MSR"
    }
  ]
}

Is this helpful?

Create onboarding card
Copy section link

Action: POST
Endpoint: /cards/merchant/{merchant_token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

Create a merchant on-boarding 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 on-boarding 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 in 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 and shipping of the card. Expedited orders ignore the setting of the associated card product’s fulfillment.shipping.method field and always ship by FedEx Priority mail.

This expedited service is available only for cards fulfilled by Perfect Plastic Printing and IDEMIA. For other fulfillment providers, set this field to false.

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

{
  "card_product_token": "blue_cardproduct"
}

Is this helpful?

Sample response body
Copy section link

{
  "created_time": "2019-02-16T00:27:21Z",
  "last_modified_time": "2019-02-16T00:27:21Z",
  "token": "chicken_tooth_token",
  "user_token": "chicken_tooth_token",
  "card_product_token": "blue_cardproduct",
  "last_four": "8751",
  "pan": "111111______8751",
  "expiration": "0227",
  "expiration_time": "2027-02-28T23:59:59Z",
  "barcode": "18254577769269137761",
  "pin_is_set": false,
  "state": "ACTIVE",
  "state_reason": "New card activated",
  "expedite": false,
  "fulfillment_status": "ISSUED",
  "instrument_type": "PHYSICAL_MSR"
}

Is this helpful?

Retrieve onboarding card
Copy section link

Action: GET
Endpoint: /cards/merchant/{merchant_token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

Retrieve 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

{
  "created_time": "2019-02-16T00:27:21Z",
  "last_modified_time": "2019-02-16T00:27:21Z",
  "token": "chicken_tooth_token",
  "user_token": "chicken_tooth_token",
  "card_product_token": "blue_cardproduct",
  "last_four": "8751",
  "pan": "111111______8751",
  "expiration": "0227",
  "expiration_time": "2027-02-28T23:59:59Z",
  "barcode": "18254577769269137761",
  "pin_is_set": false,
  "state": "ACTIVE",
  "state_reason": "New card activated",
  "expedite": false,
  "fulfillment_status": "ISSUED",
  "instrument_type": "PHYSICAL_MSR"
}

Is this helpful?

Show onboarding card PAN
Copy section link

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

Develop Now!

Sign in and use your sandbox to access the API Explorer

Retrieve 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, required

Set to true to display the full CVV2 number in the response.

Allowable Values:

true, false

Sample response body
Copy section link

{
  "created_time": "2019-02-16T00:27:21Z",
  "last_modified_time": "2019-02-16T00:42:32Z",
  "token": "chicken_tooth_token",
  "user_token": "chicken_tooth_token",
  "card_product_token": "blue_cardproduct",
  "last_four": "8751",
  "pan": "1111119386918751",
  "expiration": "0227",
  "expiration_time": "2027-02-28T23:59:59Z",
  "barcode": "18254577769269137761",
  "pin_is_set": false,
  "state": "ACTIVE",
  "state_reason": "New card activated",
  "expedite": false,
  "fulfillment_status": "DIGITALLY_PRESENTED",
  "instrument_type": "PHYSICAL_MSR"
}

Is this helpful?

Create card transition
Copy section link

Action: POST
Endpoint: /cardtransitions

Develop Now!

Sign in and use your sandbox to access the API Explorer

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

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 transaction was initiated.

Allowable Values:

API, IVR, FRAUD, ADMIN, SYSTEM, UNSUPPORTED

reason

string, optional

Additional information about the state change.

Allowable Values:

255 char max

reason_code

string, required

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:

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 or stolen.

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.

The validations object
Copy section link

Fields Description

user

object, optional

Contains information about the user.

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:

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.

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

{
    "token": "activate_05",
    "state": "ACTIVE",
    "reason": "I want to use this card, so activate it.",
    "reason_code": "00",
    "channel": "API",
    "card_token": "my_user_01_card_01",
    "validations": {
        "user": {
            "birth_date": "1990-01-31"
        }
    }
}

Is this helpful?

Sample response body
Copy section link

{
  "token": "activate_05",
  "card_token": "my_user_01_card_01",
  "user_token": "my_user_01",
  "state": "ACTIVE",
  "reason": "I want to use this card, so activate it.",
  "reason_code": "00",
  "channel": "API",
  "expedite": false,
  "fulfillment_status": "ISSUED",
  "validations": {
    "user": {
      "birth_date": true,
      "phone": false,
      "ssn": false
    }
  },
  "type": "state.activated",
  "created_time": "2018-11-23T23:28:39Z",
  "card_product_token": "blue_cardproduct",
  "last_four": "2160",
  "pan": "111111______2160",
  "expiration": "1026",
  "expiration_time": "2026-10-31T23:59:59Z",
  "barcode": "11379418395311581864",
  "pin_is_set": false,
  "user": {
    "metadata": {
      "key1": "value1",
      "key2": "value2"
    }
  }
}

Is this helpful?

Retrieve card transition
Copy section link

Action: GET
Endpoint: /cardtransitions/{token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

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

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

{
  "token": "activate_05",
  "card_token": "my_user_01_card_01",
  "user_token": "my_user_01",
  "state": "ACTIVE",
  "reason": "I want to use this card, so activate it.",
  "reason_code": "00",
  "channel": "API",
  "expedite": false,
  "fulfillment_status": "ISSUED",
  "validations": {
    "user": {
      "birth_date": true,
      "phone": false,
      "ssn": false
    }
  },
  "type": "state.activated",
  "created_time": "2018-11-23T23:28:39Z",
  "card_product_token": "blue_cardproduct",
  "last_four": "2160",
  "pan": "111111______2160",
  "expiration": "1026",
  "expiration_time": "2026-10-31T23:59:59Z",
  "barcode": "11379418395311581864",
  "pin_is_set": false,
  "user": {
    "metadata": {
      "key1": "value1",
      "key2": "value2"
    }
  }
}

Is this helpful?

List transitions for card
Copy section link

Action: GET
Endpoint: /cardtransitions/card/{token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

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

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

{
  "count": 2,
  "start_index": 0,
  "end_index": 1,
  "is_more": false,
  "data": [
    {
      "token": "suspend_01",
      "card_token": "my_user_01_card_01",
      "user_token": "my_user_01",
      "state": "SUSPENDED",
      "reason": "I do not want to use this card, so suspend it.",
      "reason_code": "01",
      "channel": "API",
      "expedite": false,
      "fulfillment_status": "ISSUED",
      "validations": {
        "user": {
          "birth_date": true,
          "phone": false,
          "ssn": false
        }
      },
      "type": "state.suspended",
      "created_time": "2019-01-12T19:54:12Z",
      "card_product_token": "blue_cardproduct",
      "last_four": "2160",
      "pan": "111111______2160",
      "expiration": "1026",
      "expiration_time": "2026-10-31T23:59:59Z",
      "barcode": "11379418395311581864",
      "pin_is_set": false,
      "user": {
        "metadata": {
          "key1": "value1",
          "key2": "value2"
        }
      }
    },
    {
      "token": "activate_05",
      "card_token": "my_user_01_card_01",
      "user_token": "my_user_01",
      "state": "ACTIVE",
      "reason": "I want to use this card, so activate it.",
      "reason_code": "00",
      "channel": "API",
      "expedite": false,
      "fulfillment_status": "ISSUED",
      "validations": {
        "user": {
          "birth_date": true,
          "phone": false,
          "ssn": false
        }
      },
      "type": "state.activated",
      "created_time": "2018-11-23T23:28:39Z",
      "card_product_token": "blue_cardproduct",
      "last_four": "2160",
      "pan": "111111______2160",
      "expiration": "1026",
      "expiration_time": "2026-10-31T23:59:59Z",
      "barcode": "11379418395311581864",
      "pin_is_set": false,
      "user": {
        "metadata": {
          "key1": "value1",
          "key2": "value2"
        }
      }
    }
  ]
}

Is this helpful?

Create PIN control token
Copy section link

Action: POST
Endpoint: /pins/controltoken

Develop Now!

Sign in and use your sandbox to access the API Explorer

Create 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

{
    "card_token": "my_card"
}

Is this helpful?

Sample response body
Copy section link

{
    "control_token": "b4647c9a-d4b8-4091-a5ff-dd67a7bb9ffc"
}

Is this helpful?

Create or update PIN
Copy section link

Action: PUT
Endpoint: /pins

Develop Now!

Sign in and use your sandbox to access the API Explorer

Create or update 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:

4 char max

Sample request body
Copy section link

{
    "control_token": "b4647c9a-d4b8-4091-a5ff-dd67a7bb9ffc",
    "pin": "5678"
}

Is this helpful?

Sample response body
Copy section link

HTTP response code 204

Is this helpful?

Related Materials

Have any feedback on this page?

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

We strive for the best possible developer experience.