Create card

Action: POST
Endpoint: /cards

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

Submit a POST 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

You can use optional query parameters to show both PAN and CVV2 number in the response. Note that 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.

Name Type Required? Description Allowable Values
show_pan boolean No Set to true to show the full PAN in the response. true | false

Default: false
show_cvv_number boolean No Set to true to show the CVV2 number in the response. true | false

Default: false

Body field details

Name Type Required? Description Allowable Values
token string No 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.
36 char max
user_token string Yes The unique identifier of the authorized user of the card. Existing user token.

Issue a GET to /users to retrieve user tokens.
fulfillment object No Determines physical characteristics of a card and shipment information.
reissue_pan_from_card_token string No 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.
Existing card token.

Issue a GET to /cards/user/{token} to retrieve card tokens for a particular user.
translate_pin_from_card_token string No 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.
Existing card token.

Issue a GET to /cards/user/{token} to retrieve card tokens for a particular user.
card_product_token string Yes The unique identifier of the card product. Existing card product token.

Issue a GET to /cardproducts to retrieve card product tokens.
bulk_issuance_token string No Associates the card with the specified bulk card order. This field cannot be updated. 36 char max
expedite boolean No Set to true to request expedited processing and shipping of the card. Expedited orders ignore the setting of thefulfillment.shipping.method field and always ship by FedEx Priority mail.

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

Note: Contact Marqeta Customer Success for information regarding the cost of expedited service.
true | false;

Default: false
expiration_offset object No 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.
activation_actions object No Defines actions to execute when the card is activated. The fields in this object are mutually exclusive.
metadata object No Associates customer-injected metadata with the user.

The activation_actions object

Name Type Required? Description Allowable Values
terminate_reissued_source_card boolean No 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.
true | false;

Default: true
swap_digital_wallet_tokens_from_card_token string No Moves all digital wallet tokens from the specified card to the new card.

Not relevant when reissue_pan_from_card_token is set.
Existing card token.

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

The expiration_offset object

Name Type Required? Description Allowable Values
unit string No Specifies the units for the value field. YEARS | MONTHS | DAYS | HOURS | MINUTES | SECONDS

Default: YEARS
value integer No 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 2015 and value=1, the card expires on the last day of Jan 2016.

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

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

HOURS, MINUTES, SECONDS – No rounding.
Any positive integer

Default: 4

The fulfillment object

Name Type Required? Description
card_personalization object No Allows personalized attributes to be added to the card.
shipping object No Specifies shipping details for the card.

The fulfillment.shipping object

Name Type Required? Description Allowable Values
return_address object No 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.
recipient_address object No 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.
method string No Specifies the shipping company and shipping service level.

This field is ignored if your fulfillment provider is either Perfect Plastic Printing or Oberthur and the expedite field is set to true. In this case, the shipping method is implicitly FEDEX_EXPEDITED.
Values allowed depend on your fulfillment provider.

Perfect Plastic Printing and Oberthur Technologies:
USPS_REGULAR | FEDEX_EXPEDITED

Arroweye Solutions:
UPS_REGULAR | UPS_EXPEDITED | USPS_REGULAR | USPS_EXPEDITED
care_of_line string No 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.
255 char max

The fulfillment.shipping.return_address & recipient_address objects

Name Type Required? Description Allowable Values
address1 string No Number and street. 50 char max
address2 string No Additional address information. 50 char max
city string No City. 50 char max
state string No State. 50 char max
postal_code string No Postal code. 50 char max
country string No Country. 40 char max
phone string No Telephone number. 50 char max
first_name string No First Name. 50 char max
middle_name string No Middle Name. 50 char max
last_name string No Last Name. 50 char max

The fulfillment.card_personalization object

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 Customer Success representative to make use of card personalization.

Name Type Required? Description
text object No Specifies personalized text that appears on the card.
carrier object No Specifies attributes of the card carrier (if your fulfillment provider is Arroweye Solutions).
images object No 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 Oberthur Technologies).

The fulfillment.card_personalization.text object

Name Type Required? Description Allowable Values
name_line_1.value string No First line of personalized text printed on the card. The card can accommodate only 21 characters. Strings longer than 21 characters are truncated.
name_line_2.value string No Second line of personalized text printed on the card. The card can accommodate only 21 characters. Strings longer than 21 characters are truncated.

The fulfillment.card_personalization.carrier object

Note: Use this carrier object if your fulfillment provider is Arroweye Solutions.

Name Type Required? Description Allowable Values
template_id string No Specifies the card carrier template to use. A card carrier template ID.
logo_file string No Specifies an image to display on the card carrier. 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 No Specifies a thumbnail-sized rendering of the image specified in the logo_file field. Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
message_file string No Specifies a text file containing a custom message to print on the card carrier. 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

Name Type Required? Description Allowable Values
card object No Specifies personalized images that appear on the card.
carrier object No Specifies personalized images and text that appear on the card carrier (if your fulfillment provider is Perfect Plastic Printing or Oberthur Technologies).
signature.name string No Specifies a PNG image of the card holder's signature. 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 No Specifies a PNG image to display in the return-address window of envelopes used for sending cards to card holders. 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

Name Type Required? Description Allowable Values
name string No Specifies a PNG image to display on the card. 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 No Specifies the color of the image displayed on the card. Contains the name of the color and must match one of the provider's predefined colors.

The fulfillment.card_personalization.images.carrier object

Note: Use this carrier object if your fulfillment provider is Perfect Plastic Printing or Oberthur Technologies.

Name Type Required? Description Allowable Values
name string No Specifies a PNG image to display on the card carrier. Contains the name of the image file and must match the file you send to your fulfillment provider.

Must end in .png.
message_1 string No Specifies a custom message that appears on the card carrier. 60 char max

The metadata object

Name Type Required? Description Allowable Values
customer_defined_name_01
customer_defined_name_02

...

customer_defined_name_20

(255 char max per name)
string No 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"
  }
Up to 20 name-value pairs.

255 char max per name; 255 char max per value.

Card state and fulfillment status

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

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 re-activation from a SUSPENDED state) by Marqeta, Marqeta customer, or the card holder (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 card holder.
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 card holder. Depending on your program settings, this state can also result from activation or re-activation of another card.

Card fulfillment status

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.
DELIVERED Card delivered by shipping provider.
DIGITALLY_PRESENTED Card digitally presented using the /cards/{token}/showpan endpoint; does not affect the delivery of physical cards.

Sample request body

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

Sample response body

{
"created_time": "2017-02-14T18:48:10Z",
"last_modified_time": "2017-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 line 1 text"
},
"name_line_2": {
"value": "my line 2 text"
}
},
"images": {
"card": {
"name": "my_card_logo.png",
"thermal_color": "Black"
},
"carrier": {
"name": "my_carrier_logo.png",
"message_1": "my message"
},
"signature": {
"name": "my_signature.png"
},
"carrier_return_window": {
"name": "my_return_address_image.png"
}
}
}
},
"instrument_type": "PHYSICAL_MSR",
"metadata": {
"key1":"value1",
"key2":"value2"
}


Retrieve card

Action: GET
Endpoint: /cards/{token}

Retrieve a specific card.

This endpoint supports field filtering and object expansion.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the card to retrieve. Existing card token.

Issue a GET to /cards/user/{token} to retrieve card tokens for a specific user.

Sample response body

{
"created_time": "2017-02-14T18:48:10Z",
"last_modified_time": "2017-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 line 1 text"
},
"name_line_2": {
"value": "my line 2 text"
}
},
"images": {
"card": {
"name": "my_card_logo.png",
"thermal_color": "Black"
},
"carrier": {
"name": "my_carrier_logo.png",
"message_1": "my message"
},
"signature": {
"name": "my_signature.png"
},
"carrier_return_window": {
"name": "my_return_address_image.png"
}
}
}
},
"instrument_type": "PHYSICAL_MSR",
"metadata": {
"key1":"value1",
"key2":"value2"
}
}


Update card

Action: PUT
Endpoint: /cards/{token}

Update the details of an existing card. For example, you can update an unactivated card in order to associate it with a different user.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the card to update. Existing card token.

Issue a GET to /cards/user/{token} to retrieve card tokens for a specific user.

Body field details

Name Type Required? Description Allowable Values
user_token string No Specifies the user you want to associate with the card. Existing user token.

Issue a GET to /users to retrieve user tokens.
expedite boolean No Set to true to request expedited processing and shipping of the card. Expedited orders ignore the setting of thefulfillment.shipping.method field and always ship by FedEx Priority mail.

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

Note: Contact Marqeta Customer Success for information regarding the cost of expedited service.
true | false;

Default: false
fulfillment object No Determines physical characteristics of a card and shipment information.
metadata object No Associates customer-injected metadata with the card.

The fulfillment object

Name Type Required? Description
card_personalization object No Allows personalized attributes to be added to the card.
shipping object No Specifies shipping details for the card.

The fulfillment.shipping object

Name Type Required? Description Allowable Values
return_address object No 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.
recipient_address object No 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.
method string No Specifies the shipping company and shipping service level.

This field is ignored if your fulfillment provider is either Perfect Plastic Printing or Oberthur and the expedite field is set to true. In this case, the shipping method is implicitly FEDEX_EXPEDITED.
Values allowed depend on your fulfillment provider.

Perfect Plastic Printing and Oberthur Technologies:
USPS_REGULAR | FEDEX_EXPEDITED

Arroweye Solutions:
UPS_REGULAR | UPS_EXPEDITED | USPS_REGULAR | USPS_EXPEDITED
care_of_line string No 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.
255 char max

The fulfillment.shipping.return_address & recipient_address objects

Name Type Required? Description Allowable Values
address1 string No Number and street. 50 char max
address2 string No Additional address information. 50 char max
city string No City. 50 char max
state string No State. 50 char max
postal_code string No Postal code. 50 char max
country string No Country. 40 char max
phone string No Telephone number. 50 char max
first_name string No First Name. 50 char max
middle_name string No Middle Name. 50 char max
last_name string No Last Name. 50 char max

The fulfillment.card_personalization object

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 Customer Success representative to make use of card personalization.

Name Type Required? Description
text object No Specifies personalized text that appears on the card.
carrier object No Specifies attributes of the card carrier (if your fulfillment provider is Arroweye Solutions).
images object No 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 Oberthur Technologies).

The fulfillment.card_personalization.text object

Name Type Required? Description Allowable Values
name_line_1.value string No First line of personalized text printed on the card. The card can accommodate only 21 characters. Strings longer than 21 characters are truncated.
name_line_2.value string No Second line of personalized text printed on the card. The card can accommodate only 21 characters. Strings longer than 21 characters are truncated.

The fulfillment.card_personalization.carrier object

Note: Use this carrier object if your fulfillment provider is Arroweye Solutions.

Name Type Required? Description Allowable Values
template_id string No Specifies the card carrier template to use. A card carrier template ID.
logo_file string No Specifies an image to display on the card carrier. 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 No Specifies a thumbnail-sized rendering of the image specified in the logo_file field. Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
message_file string No Specifies a text file containing a custom message to print on the card carrier. 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

Name Type Required? Description Allowable Values
card object No Specifies personalized images that appear on the card.
carrier object No Specifies personalized images and text that appear on the card carrier (if your fulfillment provider is Perfect Plastic Printing or Oberthur Technologies).
signature.name string No Specifies a PNG image of the card holder's signature. 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 No Specifies a PNG image to display in the return-address window of envelopes used for sending cards to card holders. 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

Name Type Required? Description Allowable Values
name string No Specifies a PNG image to display on the card. 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 No Specifies the color of the image displayed on the card. Contains the name of the color and must match one of the provider's predefined colors.

The fulfillment.card_personalization.images.carrier object

Note: Use this carrier object if your fulfillment provider is Perfect Plastic Printing or Oberthur Technologies.

Name Type Required? Description Allowable Values
name string No Specifies a PNG image to display on the card carrier. Contains the name of the image file and must match the file you send to your fulfillment provider.

Must end in .png.
message_1 string No Specifies a custom message that appears on the card carrier. 60 char max

The metadata object

Name Type Required? Description Allowable Values
customer_defined_name_01
customer_defined_name_02

...

customer_defined_name_20

(255 char max per name)
string No 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
  }

Up to 20 name-value pairs.

255 char max per name; 255 char max per value

Sample request body

{
"user_token": "my_user_03"
}

Sample response body

{
"created_time": "2017-02-14T18:48:10Z",
"last_modified_time": "2017-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 line 1 text"
},
"name_line_2": {
"value": "my line 2 text"
}
},
"images": {
"card": {
"name": "my_card_logo.png",
"thermal_color": "Black"
},
"carrier": {
"name": "my_carrier_logo.png",
"message_1": "my message"
},
"signature": {
"name": "my_signature.png"
},
"carrier_return_window": {
"name": "my_return_address_image.png"
}
}
}
},
"instrument_type": "PHYSICAL_MSR",
"metadata": {
"key1":"value1"
}
}


List cards for user

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

List cards associated with a specific user.

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

URL path parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the user whose cards you want to list. Existing user token.

Issue a GET to /users to retrieve user tokens.

Sample response body

{
"count": 3,
"start_index": 0,
"end_index": 2,
"is_more": false,
"data": [
{
"created_time": "2016-10-24T21:23:31Z",
"last_modified_time": "2017-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 don't want to use this card, so suspend it.",
"expedite": false,
"fulfillment_status": "ISSUED",
"instrument_type": "PHYSICAL_MSR"
},
{
"created_time": "2016-12-28T18:31:23Z",
"last_modified_time": "2016-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": "2016-11-03T21:55:08Z",
"last_modified_time": "2016-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"
}
]
}


Retrieve card by PAN

Action: POST
Endpoint: /cards/getbypan

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

Body field details

Name Type Required? Description Allowable Values
pan string Yes The PAN of the card whose information you want to retrieve. 16 char max.

Issue a GET to /cards/{token}/showpan to retrieve the PAN for a specific card.
cvv_number string No The three digit card verification value (CVV2) included on the back of the card.

This value is not updateable.
3 char max
expiration string No Card expiration date. mmyy

Sample request body

{
"pan": "5454545454545454"
}

Sample response body

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


Show card PAN

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

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.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the card whose PAN you want to retrieve. Existing card token.

Issue a GET to /cards/user/{token} to retrieve existing card tokens for a specific user.

Query parameters

Name Type Required? Description Allowable Values
show_cvv_number boolean Yes Set to "true" to display the full CVV2 number in the response. true | false

Sample response body

{
"created_time": "2016-12-28T18:31:23Z",
"last_modified_time": "2017-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"
}


Retrieve card by barcode

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

Retrieve a card by its barcode.

This endpoint supports field filtering and object expansion.

URL path parameters

Name Type Required? Description Allowable Values
barcode string Yes The barcode of the card to retrieve. Existing barcode

Sample response body

{
"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": "2016-02-29T23:59:59Z",
"pin_is_set": "false",
"expedite": false,
"fulfillment_status": "DELIVERED",
"instrument_type": "PHYSICAL_MSR"
}


List cards by last four digits of PAN

Action: GET
Endpoint: /cards

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

Name Type Required? Description Allowable Values
last_four string Yes The last four digits of the PAN of the card you want to locate. 4-digit string

Sample response body

{
"count": 1,
"start_index": 0,
"end_index": 0,
"is_more": false,
"data": [
{
"created_time": "2016-12-28T18:31:23Z",
"last_modified_time": "2017-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"
}
]
}


Create onboarding card

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

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

Name Type Required? Description Allowable Values
merchant_token string Yes Identifies the merchant for whom you are creating the card. Existing merchant token.

Issue a GET to /merchants to retrieve existing merchant tokens.

Body field details

Name Type Required? Description Allowable Values
card_product_token string Yes 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.
Existing card product token.

Perform a GET on /cardproducts to retrieve card product tokens.
expedite boolean No 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 Oberthur Technologies. For other fulfillment providers, set this field to false.

Note: Contact Marqeta Customer Success for information regarding the cost of expedited service.
true | false;

Default: false

Sample request body

{
"card_product_token": "blue_cardproduct"
}

Sample response body

{
"created_time": "2017-02-16T00:27:21Z",
"last_modified_time": "2017-02-16T00:27:21Z",
"token": "hairyshats_token",
"user_token": "hairyshats_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"
}


Retrieve onboarding card

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

Retrieve a specific merchant onboarding card. This endpoint supports field filtering and object expansion.

URL path parameters

Name Type Required? Description Allowable Values
merchant_token string Yes Identifies the merchant whose card you want to retrieve. Existing merchant token.

Issue a GET to /merchants to retrieve existing merchant tokens.

Sample response body

{
"created_time": "2017-02-16T00:27:21Z",
"last_modified_time": "2017-02-16T00:27:21Z",
"token": "hairyshats_token",
"user_token": "hairyshats_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"
}


Show onboarding card PAN

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

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.

URL path parameters

Name Type Required? Description Allowable Values
merchant_token string Yes Identifies the merchant whose card you want to retrieve. Existing merchant token.

Issue a GET to /merchants to retrieve existing merchant tokens.

Query parameters

Name Type Required? Description Allowable Values
show_cvv_number boolean Yes Set to "true" to display the full CVV2 number in the response. true | false

Sample response body

{
"created_time": "2017-02-16T00:27:21Z",
"last_modified_time": "2017-02-16T00:42:32Z",
"token": "hairyshats_token",
"user_token": "hairyshats_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"
}


Create card transition

Action: POST
Endpoint: /cardtransitions

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

Name Type Required? Description Allowable Values
token string No 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.
36 char max
card_token string Yes Identifies the card whose state will transition. Existing card token.

Issue a GET to /cards/user/{token} to retrieve card tokens for a specific user.
state string Yes Specifies the new state. ACTIVE | SUSPENDED | TERMINATED
channel string Yes The mechanism by which the transaction was initiated. API | IVR | FRAUD | ADMIN | SYSTEM | UNSUPPORTED
reason string No Additional information about the state change. 255 char max
reason_code string Yes A standard code describing the reason for the transition. See "The reason_code field" section.
validations object No Contains information about the user.

The reason_code field

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.

The validations object

Name Type Required? Description
user object No Contains information about the user.

The validations.user object

Name Type Required? Description Allowable Values
birth_date string No The birthdate of the user associated with this card. yyyy-MM-dd
phone string No The phone number of the user associated with this card. 1234567890, or 123-456-7890
ssn string No The Social Security number of the user associated with this card. 255 char max

The type field (response)

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 re-instated from a suspended state
state.suspended Card was suspended
state.terminated Card was terminated
fulfillment.delivered Card was delivered by card shipping provider
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)

The card transition response contains a fulfillment_status field that provides status information about the card in regards 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
DELIVERED Card delivered by shipping provider
DIGITALLY_PRESENTED Card digitally presented using the /cards/{token}/showpan API; does not affect the delivery of physical cards.

The validations.user object (response)

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

{
"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"
}
}
}

Sample response body

{
"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": "2016-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"
}
}
}


Retrieve card transition

Action: GET
Endpoint: /cardtransitions/{token}

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

URL path parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the card transition to retrieve. Existing card transition token.

Issue a GET to /cardtransitions/card/{token} to retrieve card transition tokens for a specific card.

The type field (response)

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 re-instated from a suspended state
state.suspended Card was suspended
state.terminated Card was terminated
fulfillment.delivered Card was delivered by card shipping provider
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)

The card transition response contains a fulfillment_status field that provides status information about the card in regards 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
DELIVERED Card delivered by shipping provider
DIGITALLY_PRESENTED Card digitally presented using the /cards/{token}/showpan API; does not affect the delivery of physical cards.

The validations.user object (response)

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

{
"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": "2016-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"
}
}
}


List transitions for card

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

List transitions for a specific card. This endpoint supports field filtering and pagination.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the card whose state change information you want to retrieve. Existing card token.

Issue a GET to /cards/user/{token} to retrieve card tokens for a specific user.

The type field (response)

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 re-instated from a suspended state
state.suspended Card was suspended
state.terminated Card was terminated
fulfillment.delivered Card was delivered by card shipping provider
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)

The card transition response contains a fulfillment_status field that provides status information about the card in regards 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
DELIVERED Card delivered by shipping provider
DIGITALLY_PRESENTED Card digitally presented using the /cards/{token}/showpan API; does not affect the delivery of physical cards.

The validations.user object (response)

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

{
"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 don't 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": "2017-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": "2016-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"
}
}
}
]
}


Create PIN control token

Action: POST
Endpoint: /pins/controltoken

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.

Body field details

Name Type Required? Description Allowable Values
card_token string Yes Identifies the card for which you want to generate a control token. Existing card token.

Issue a GET to /cards/user/{token} to retrieve card tokens for a specific user.

Sample request body

{
"card_token": "my_card"
}

Sample response body

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


Create or update PIN

Action: PUT
Endpoint: /pins

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.

Note: You cannot retrieve an already existing PIN. If the PIN has been lost, you must either update the card's PIN or create a new card and PIN.

Body field details

Name Type Required? Description Allowable Values
control_token string Yes The unique value generated as a result of issuing a POST request to the /pins/controltoken endpoint. This value cannot be updated. Existing control token
pin string Yes The 4-digit number to associate with the card. 4 char max

Sample request body

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

Sample response body

HTTP response code 204