Create Card

Action: POST
Endpoint: /cards

To create a card, send a POST request to the /cards endpoint and include the card details in JSON format in the body of the request. When you create any Marqeta resource, the system associates a token for referencing that resource. You can create your own token using any alpha-numeric characters, 36 chars max. If you do not include a token value, one is generated automatically.

When creating a card, you must pass in the user_token of the card holder and the card_product_token for the respective resource. Therefore, you must create users and card products before you can create cards.

As a result of the POST to /cards, Marqeta 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 by default is not visible in the response. Issue a GET on /cards/getbypan to retrieve the cvv_number value. Alternatively, optional query parameters are provided to show both PAN and CVV 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.

Note: Newly created cards are inactive by default; cards must be explicitly activated (see the Create Card Transition section on this page for details).

Issue a POST to /pins/controltoken to set the card PIN if the program requires PIN numbers (for example, for EMV cards); this will update the pin_is_set field to true (see the "Create or Update PIN" section on this page for details).

Query Parameters

Name Type Required? Description Allowable Values
show_pan boolean No True shows PAN in the response. true | false

Default: false
show_cvv_number boolean No True shows CVV 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 Re-assigns the PAN and PIN from another card to this card. Input the card token of the card whose PAN and PIN you want to re-assign. The newly issued card will have a different expiration date and CVV number than the old card. 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 same-day processing and shipping of the card.

Note: Contact Marqeta Customer Success for information regarding the cost of using this expedited service. This option is available only for cards that are fulfilled by Perfect Plastic Printing.
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.

expiration_offset

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) for which cards of this cardproduct type are valid. In other words, cards expire "unit x value" 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 Feb 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

fulfillment

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.

fulfillment.shipping

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 zip 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 zip 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 method. Values allowed depend on your fulfillment provider.

Perfect Plastic Printing:
USPS_REGULAR | FEDEX_EXPEDITED

Arroweye Solutions:
USPS_REGULAR | UPS_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

fulfillment.shipping.return_address & recipient_address

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
zip string No ZIP 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

fulfillment.card_personalization

Name Type Required? Description
text object No This field's value is a Map object that contains an array of string-Map pairs. Each of the inner Map objects contains a field named value that takes a personalized string that will be printed on the card. The exact syntax is flexible but should look similar to this:

"text": {
"name_line_1": {
"value": "my_personalized_text_printed_on_card"
},
"name_line_2": {
"value": "more_personalized_text_printed_on_card"
},
"custom_field_10": {
"value": "and_more_personalized_text_printed_on_card"
},
"custom_field_11": {
"value": "and_yet_more_personalized_text_printed_on_card"
}

The name_line_1 and name_line_2 field names are literal. Do not change their spelling. The custom_field_10 and custom_field_11 field names are descriptive. You can substitute any names you like for these field names. You can also include any number of custom field names.

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. A card can transition from ACTIVE to SUSPENDED and back to ACTIVE again.

This state can result from card suspension by Marqeta, Marqeta customer, or the card holder.
TERMINATED The card is permanently non-functional and cannot transition to any other state.

This state can result from card termination by Marqeta, Marqeta customer, or the card holder.

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.

Sample Request Body

{
"token": "mytestcard01",
"user_token": "my_user_01",
"fulfillment": {
"card_personalization": {
"text": {
"custom_field_11": {
"value": "my_custom_text11",
"required": false
},
"custom_field_10": {
"value": "my_custom_text10",
"required": true
},
"name_line_1": {
"value": "my_name",
"required": true
},
"name_line_2": {
"value": "my_company",
"required": true
}
}
}
},
"card_product_token": "red_cardproduct"
}

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": {
"custom_field_11": {
"value": "my_custom_text11",
"required": false
},
"custom_field_10": {
"value": "my_custom_text10",
"required": true
},
"name_line_1": {
"value": "my_name",
"required": true
},
"name_line_2": {
"value": "my_company",
"required": true
}
}
}
},
"instrument_type": "PHYSICAL_MSR"
}


Retrieve Card

Action: GET
Endpoint: /cards/{token}

To retrieve a specific card, issue a GET request to the /cards/{token} endpoint. Include the token path parameter to specify the card to return.

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": {
"custom_field_11": {
"value": "my_custom_text11",
"required": false
},
"custom_field_10": {
"value": "my_custom_text10",
"required": true
},
"name_line_1": {
"value": "my_name",
"required": true
},
"name_line_2": {
"value": "my_company",
"required": true
}
}
}
},
"instrument_type": "PHYSICAL_MSR"
}


Update Card

Action: PUT
Endpoint: /cards/{token}

You can update an unactivated card in order to associate it with a different user. Send a PUT request to the /cards/{token} endpoint and include the card token as a path parameter to indicate the card to update. Include the new user_token in JSON format in the body of the request.

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 Yes 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 same-day processing and shipping of the card.

Note: Contact Marqeta Customer Success for information regarding the cost of using this expedited service. This option is available only for cards that are fulfilled by Perfect Plastic Printing.
true | false;

Default: false
fulfillment object No Determines physical characteristics of a card and shipment information.

fulfillment

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.

fulfillment.shipping

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 zip 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 zip 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 method . Values allowed depend on your fulfillment provider.

Perfect Plastic Printing:
USPS_REGULAR | FEDEX_EXPEDITED

Arroweye Solutions:
USPS_REGULAR | UPS_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

fulfillment.shipping.return_address & recipient_address

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
zip string No ZIP 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

fulfillment.card_personalization

Name Type Required? Description
text object No This field's value is a Map object that contains an array of string-Map pairs. Each of the inner Map objects contains a field named value that takes a personalized string that will be printed on the card. The exact syntax is flexible but should look similar to this:

"text": {
"name_line_1": {
"value": "my_personalized_text_printed_on_card"
},
"name_line_2": {
"value": "more_personalized_text_printed_on_card"
},
"custom_field_10": {
"value": "and_more_personalized_text_printed_on_card"
},
"custom_field_11": {
"value": "and_yet_more_personalized_text_printed_on_card"
}

The name_line_1 and name_line_2 field names are literal. Do not change their spelling. The custom_field_10 and custom_field_11 field names are descriptive. You can substitute any names you like for these field names. You can also include any number of custom field names.

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",
"zip": "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",
"zip": "00112",
"country": "USA",
"phone": "345-123-9876",
"first_name": "Big",
"last_name": "Bird"
}
},
"card_personalization": {
"text": {
"custom_field_11": {
"value": "my_custom_text11",
"required": false
},
"custom_field_10": {
"value": "my_custom_text10",
"required": true
},
"name_line_1": {
"value": "my_name",
"required": true
},
"name_line_2": {
"value": "my_company",
"required": true
}
}
}
},
"instrument_type": "PHYSICAL_MSR"
}


List Cards for User

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

To list cards associated with a specific cardholder, issue a GET request to the /cards/user/{token} endpoint. Include the token path parameter to indicate the user whose cards you want to list.

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

Returns 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 Parameters

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

To retrieve a card resource that displays the entire PAN (credit card number), send a GET request to the /cards/{token}/showpan endpoint. This value is not fully visible on the card resource returned by GET /cards/{token} for security reasons. Include the token path parameter to specify the card to return.

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 CVV 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}

To retrieve a card identified by its barcode, issue a GET request to the /cards/barcode/{barcode} endpoint. Include the barcode path parameter to specify the 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

Returns 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}

To create a merchant on-boarding card, send a POST request to the cards/merchant/{merchant_token} endpoint and include the merchant_token path parameter to specify the merchant. Include the card product token in JSON format in the body of the request. A token for the card cannot be set, 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, Marqeta 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}, Marqeta 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 expedite processing and shipping of the card.

Note: Contact Marqeta Customer Success for information regarding the cost of using this expedited service. This option is available only for cards that are fulfilled by Perfect Plastic Printing.
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}

To retrieve a card for a specific merchant, issue a GET request to the /cards/merchant/{merchant_token} endpoint. Include the merchant_token path parameter to specify the card to return.

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

To retrieve a merchant onboarding card resource that displays the entire PAN (payment card number), send a GET request to the /cards/merchant/{merchant_token}/showpan endpoint. This value is not fully visible on the card resource returned by GET /cards/merchant/{token} for security reasons. Include the merchant_token path parameter to specify the card to return.

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

To change the state of a card, send a POST request to the /cardtransitions endpoint and include the card_token, state, and other details in JSON format in the body of the request. When you create any Marqeta resource, the system associates a token for referencing that resource. You can create your own token using any alpha-numeric characters, 36 chars max. If you do not include a token value, one is generated automatically.

Note that in IVR situations, you can send a POST to /cards/getbypan to retrieve the card token, which can then be used in the POST to /cardtransitions request.

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.

Note: A user can be associated with only one ACTIVE card at a time. Activating a card automatically terminates any currently ACTIVE card.
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
validations object No Contains information about the user.
expedite boolean No Set to "true" to expedite processing and shipping of the card.

Note: Contact Marqeta Customer Success for information regarding the cost of using this expedited service. This option is available only for cards that are fulfilled by Perfect Plastic Printing.
true | false;

Default: false

validations

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

validations.user

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

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
fulfillment.issued Card was created/issued
state.activated Card was activated
state.suspended Card was suspended
state.reinstated Card was re-instated from a suspended state
state.terminated Card was terminated
fulfillment.ordered Card was ordered by card fulfillment provider
fulfillment.rejected Card was rejected by card fulfillment provider
fulfillment.shipped Card was shipped by card fulfillment provider
fulfillment.delivered Card was delivered by card shipping provider
fulfillment.digitally_presented Card was digitally presented using the /cards/{token}/showpan endpoint

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

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.",
"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.",
"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}

To retrieve a particular card transition, issue a GET request to the /cardtransitions/{token} endpoint. Include the token path parameter to specify the transition to return.

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.

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
fulfillment.issued Card was created/issued
state.activated Card was activated
state.suspended Card was suspended
state.reinstated Card was re-instated from a suspended state
state.terminated Card was terminated
fulfillment.ordered Card was ordered by card fulfillment provider
fulfillment.rejected Card was rejected by card fulfillment provider
fulfillment.shipped Card was shipped by card fulfillment provider
fulfillment.delivered Card was delivered by card shipping provider
fulfillment.digitally_presented Card was digitally presented using the /cards/{token}/showpan endpoint

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

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.",
"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}

To retrieve card state change information for a specific card, issue a GET request to the /cardtransitions/card/{token} endpoint. Include the token path parameter to specify the card to return.

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.

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
fulfillment.issued Card was created/issued
state.activated Card was activated
state.suspended Card was suspended
state.reinstated Card was re-instated from a suspended state
state.terminated Card was terminated
fulfillment.ordered Card was ordered by card fulfillment provider
fulfillment.rejected Card was rejected by card fulfillment provider
fulfillment.shipped Card was shipped by card fulfillment provider
fulfillment.delivered Card was delivered by card shipping provider
fulfillment.digitally_presented Card was digitally presented using the /cards/{token}/showpan endpoint

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

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.",
"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.",
"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 or Update PIN

Creating a PIN is a two-step process. First you create the control token that is required to create the PIN, and then you create the PIN itself. 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.

Step 1

Action: POST
Endpoint: /pins/controltoken

To create a control token necessary for creating a PIN, send a POST request to the /pins/controltoken endpoint and include the card_token in JSON format in the body of the request.

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

Step 2

Action: PUT
Endpoint: /pins

To create the actual PIN (or update an existing PIN), send a PUT request to the /pins endpoint, and include the control_token value (created above) and the pin in JSON format in the body of the request.

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