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

Creating a card automatically generates a PAN and sets the last_four field to the last 4 digits of the PAN. By default, the pin_is_set field is set to false and the expiration_offset object is configured to expire the card at the end of the current month plus four years.

Card creation also generates the cvv_number, which by default is not visible in the response. To retrieve the cvv_number value, use the optional query parameters to show both PAN and CVV number in the response (or issue a GET request to /cards/getbypan). 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: 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).

Issue 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

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 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 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 CVV 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 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.
activation_actions object No Defines actions to execute when the card is activated. The fields in this object are mutually exclusive.

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

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

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

The fulfillment.card_personalization object

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.
images object No Defines the images that appear on the card and card carrier.

The fulfillment.card_personalization.images object

Note: You must make prior arrangements with Marqeta to make use of this functionality.

Name Type Required? Description
card.name string No Specifies the image displayed on the card. This field contains the name of the image file and must match the file you send to your fulfillment provider.

The structure within the card_personalization object should look as follows, where my_card_image.png is the name of your image file:

 "images": {
     "card": {
         "name": "my_card_image.png"
      }
  }
card.thermal_color string No Specifies the color of the image displayed on the card. This field contains the name of the color, which must match one of the provider's predefined colors. Default: UG_BLACK.

If no image is provided, the color will be ignored.

The structure within the card_personalization object should look as follows, where my_card_image.png is the name of your image file:

 "images": {
     "card": {
         "name": "my_card_image.png"
         "thermal_color": "UG_BLACK"
      }
  }
carrier.name string No Specifies the image displayed on the card carrier. This field contains the name of the image file and must match the file you send to your fulfillment provider.

The structure within the card_personalization object should look as follows, where my_carrier_image.png is the name of your image file:

 "images": {
     "carrier": {
         "name": "my_carrier_image.png"
      }
  }
carrier.message_1 string No Specifies the custom message that appears on the card carrier. 60 char max.
carrier_return_window.name string No Specifies the image displayed in the return-address window of envelopes used for sending cards to card holders. This field contains the name of the image file and must match the file you send to your fulfillment provider.

The structure within the card_personalization object should look as follows, where my_return_address.png is the name of your image file:

 "images": {
     "carrier_return_window": {
         "name": "my_return_address.png"
      }
  }

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.

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.

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

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

The fulfillment.card_personalization object

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.
images object No Defines the images that appear on the card and card carrier.

The fulfillment.card_personalization.images object

Note: You must make prior arrangements with Marqeta to make use of this functionality.

Name Type Required? Description
card.name string No Specifies the image displayed on the card. This field contains the name of the image file and must match the file you send to your fulfillment provider.

The structure within the card_personalization object should look as follows, where my_card_image.png is the name of your image file:

 "images": {
     "card": {
         "name": "my_card_image.png"
      }
  }
card.thermal_color string No Specifies the color of the image displayed on the card. This field contains the name of the color, which must match one of the provider's predefined colors. Default: UG_BLACK.

If no image is provided, the color will be ignored.

The structure within the card_personalization object should look as follows, where my_card_image.png is the name of your image file:

 "images": {
     "card": {
         "name": "my_card_image.png"
         "thermal_color": "UG_BLACK"
      }
  }
carrier.name string No Specifies the image displayed on the card carrier. This field contains the name of the image file and must match the file you send to your fulfillment provider.

The structure within the card_personalization object should look as follows, where my_carrier_image.png is the name of your image file:

 "images": {
     "carrier": {
         "name": "my_carrier_image.png"
      }
  }
carrier.message_1 string No Specifies the custom message that appears on the card carrier. 60 char max.
carrier_return_window.name string No Specifies the image displayed in the return-address window of envelopes used for sending cards to card holders. This field contains the name of the image file and must match the file you send to your fulfillment provider.

The structure within the card_personalization object should look as follows, where my_return_address.png is the name of your image file:

 "images": {
     "carrier_return_window": {
         "name": "my_return_address.png"
      }
  }

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 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 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 activate, suspend, or terminate a card, send a POST request to the /cardtransitions endpoint and include the card_token, the new 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. 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

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

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

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

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

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

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

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

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

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