Basic Concepts

The fundamental purpose of the Marqeta API is to issue payment cards and customize card behavior. In a production environment, cards are used to pay merchants for goods and services. When such a purchase occurs, the transaction is routed over a payment card network to Marqeta for approval. However, because the sandbox environment is not connected to an actual payment card network, transactions are simulated.

The API uses objects to represent various concepts. For example, a payment card is represented by a card object and a card holder is represented by a user object. You create a new object, such as a card or user, by making a call to the appropriate API endpoint.

A card is an example of a first-class object, in which the object name occupies the first node in the endpoint URL (in this case, /cards). First-class objects are generally the most important objects on the Marqeta platform and include cards, users, gpaorders (used to load funds into a user account), and fundingsources (the source of funds from which a gpaorder draws). Refer to the Summary of Resources to see how the most fundamental API objects interrelate.

The Marqeta API is RESTful, meaning that it uses HTTP verbs (POST, PUT, GET) to perform functions on objects. Specifically, POST is used to create an object, PUT to update an object, and GET to retrieve an object. For example, to create a new user object you would send a POST request to /users.

POST and PUT requests usually require data to be passed in the message body in order to define the attributes of the object being created or updated. This data must be in JSON format.


Step 1 — Get Access

Create Account

Create an account on Marqeta.com to get access to the shared API sandbox. Note that this is a shared environment; don't populate it with personal data that you don't want others to see.

Link: https://www.marqeta.com/users/sign_up

The API Explorer

After logging in to your account, you can use the built-in, browser-based API Explorer to interact with the Marqeta API.

Link: https://www.marqeta.com/api-explorer.

This page also includes embedded API Explorer widgets that let you send requests to specific API endpoints. You must sign in to your account for these widgets to appear on the page.

Note: The API documentation is available under "API DOCS > REFERENCE DOCS" in the API Explorer's menu bar.

API Keys

If you prefer to interact with the API using your own client application or by executing cURLs (rather than by using the API Explorer), you will need valid API keys. These consist of an application token, a master access token, and the base URL of the shared sandbox environment. These are listed near the top of the API Explorer:

For each API request, use the application token as the username, the master access token as the password, and the base URL as a prefix to your endpoint URL. Sample cURLs are provided in the last section on this page. Those samples have already concatenated the URL for you, but you will need to replace *username* with the application token and *password* with the master access token.

The API keys are provided automatically if you use the API Explorer.


Step 2 — Create Objects

In this step you will create the four basic objects you need to conduct a transaction: a card product, a funding source, a user, and a card.

  • A card product defines a set of card properties that control the characteristics and behavior of cards associated with that card product. You can think of a card product somewhat as a template from which you generate cards. However, cards are dynamically associated with their card product throughout their lives and are affected by updates to the card product's properties. Every card is generated from and associated with a card product. You must have at least one card product in order to conduct transactions. In the sandbox environment you will create the card product yourself. However, in production scenarios, Marqeta creates card products on the customer's behalf.
  • Funding sources enable access to funds outside of the Marqeta platform and facilitate the movement of funds into a user account. In order to conduct a transaction, a user must have sufficient account funds. Multiple users can share the same funding source. In the sandbox environment you will create the funding source yourself. However, in production scenarios, Marqeta creates funding sources on its customer's behalf. Marqeta supports several types of funding sources. For this exercise, you will use the easiest type to create — a program funding source.
  • Users represent the owners of cards. Each user can own only one active card. Each user is automatically provided with a general purpose account (GPA) for funding the transactions conducted with that card. (You can create other types of user funding accounts, but for this exercise you will use the GPA.)
  • Cards are generated from and associated with a card product and are owned by users. A user requires an active card in order to conduct a transaction. Cards do not hold funds themselves, but act as access devices to the funds in user accounts.

Create a card product

The following code box provides a JSON-formatted message body for creating a card product. Note that this card product is defined such that cards generated from it are activated upon issue, eliminating the need to explicitly activate the cards before use.

{
"start_date": "2017-01-01",
"name": "Example Card Product",
"config": {
"fulfillment": {
"payment_instrument":"VIRTUAL_PAN"
},
"poi": {
"ecommerce": true
},
"card_life_cycle": {
"activate_upon_issue": true
}
}
}

To create a card product:

  1. Copy the preceding code.
  2. Click the "POST /cardproducts" widget below.
  3. Scroll down to the "Body" field and paste the code into that field.
  4. Click the "Submit Request" button.
  5. Scroll down further to the "Response Body" field and take note of the response's "token" field.
    You will need this token later when you create a card.
    Tip: As an alternative to letting the API generate a token, you can specify the token yourself in the request by including a token field.

Click the following widget to expand the API Explorer (You must sign in to your sandbox account for the widget to appear):

Create a program funding source

The following code box provides a JSON-formatted message body for creating a program funding source.

{
"name": "Program Funding"
}

To create a program funding source:

  1. Copy the preceding code.
  2. Click the "POST /fundingsources/program" widget below.
  3. Scroll down to the "Body" field and paste the code into that field.
  4. Click the "Submit Request" button.
  5. Scroll down further to the "Response Body" field and take note of the response's "token" field.
    You will need this token later when you fund the user account.
    Tip: As an alternative to letting the API generate a token, you can specify the token yourself in the request by including a token field.

Create a user

The following code box provides a JSON-formatted message body for creating a user. Although user objects can be defined with many data fields, this exercise creates a simple, default user by omitting all request fields.

{}

To create a user:

  1. Copy the preceding code.
  2. Click the "POST /users" widget below.
  3. Scroll down to the "Body" field and paste the code into that field.
  4. Click the "Submit Request" button.
  5. Scroll down further to the "Response Body" field and take note of the response's "token" field.
    You will need this token later when you create a card, fund the user account, and conduct transactions.
    Tip: As an alternative to letting the API generate a token, you can specify the token yourself in the request by including a token field.

Create a card

The following code box provides a JSON-formatted message body for creating a card. Note that this card will be active upon issue because of the card product's configuration.

{
"user_token": "**USER TOKEN FROM PREVIOUS STEP**",
"card_product_token": "**CARD PRODUCT TOKEN FROM PREVIOUS STEP**"
}

To create a card:

  1. Copy the preceding code.
  2. Click the "POST /cards" widget below.
  3. Scroll down to the "Body" field and paste the code into that field.
  4. Replace the value of the "user_token" field with the token of the user you created previously.
  5. Replace the value of the "card_product_token" field with the token of the card product you created previously.
  6. Click the "Submit Request" button.
  7. Scroll down further to the "Response Body" field and take note of the response's "token" field.
    You will need this token later when you conduct transactions.
    Tip: As an alternative to letting the API generate a token, you can specify the token yourself in the request by including a token field.


Step 3 — Fund User Account

In this step you will load $1000 into the general purpose account (GPA) of the user you created in the previous step. To do this you will create a gpaorder object. You will need both the user token and program funding source token from the previous step to do so.

The following code box provides a JSON-formatted message body for creating a $1000 gpaorder.

{
"user_token": "**USER TOKEN FROM PREVIOUS STEP**",
"amount": "1000",
"currency_code": "USD",
"funding_source_token": "**PROGRAM FUNDING SOURCE TOKEN FROM PREVIOUS STEP**"
}

To fund a user's GPA:

  1. Copy the preceding code.
  2. Click the "POST /gpaorders" widget below.
  3. Scroll down to the "Body" field and paste the code into that field.
  4. Replace the value of the "user_token" field with the token of the user you created previously.
  5. Replace the value of the "funding_source_token" field with the token of the program funding source you created previously.
  6. Click the "Submit Request" button.

Step 4 — Transact

In this step you will simulate an authorization transaction for $10. A merchant ID number (MID) is required and is provided in the mid field. You will need the token of the card you created previously.

{
"amount": "10",
"mid": "123456890",
"card_token": "**CARD TOKEN FROM PREVIOUS STEP**"
}

To simulate an authorization transaction:

  1. Copy the preceding code.
  2. Click the "POST /simulate/authorization" widget below.
  3. Scroll down to the "Body" field and paste the code into that field.
  4. Replace the value of the "card_token" field with the token of the card you created previously.
  5. Click the "Submit Request" button.

Step 5 — Add a Webhook

In this step will you simulate another authorization transaction, but this time with a webhook added to the request. The webhook instructs the Marqeta platform to push an event notification of the transaction to a specified URL.

Note: Because this simulated transaction is initiated by way of an API call, you will receive an API response that is identical to the content of the webhook notification. However, in a production environment transactions are initiated by merchants from outside the Marqeta environment and not by way of an API call. The only way to receive notification of transactions as they occur in a production environment is by way of webhooks. For more information about webhooks, see Webhooks Overview.

In order to receive and inspect the event notification, you will need to provide a URL that can accept the notification. (Runscope provides a free online service that lets you receive and inspect HTTP requests. To use this service, go to http://requestb.in, create a bin for receiving requests, and copy its URL into the body of your transaction request, for example: "endpoint": "http://requestb.in/t73gn0t7").

As before, a MID is provided in the mid field, and you will need to replace the value of the card_token field with the token of the card you created previously.

{
"amount": "10",
"mid": "123456890",
"card_token": "**CARD TOKEN FROM PREVIOUS STEP**",
"webhook": {
"endpoint": "**URL FOR RECEIVING NOTIFICATIONS**",
"username": "**MY USER NAME**",
"password": "**MY PASSWORD**"
}
}

To simulate an authorization transaction with an added webhook:

  1. Copy the preceding code.
  2. Click the "POST /simulate/authorization" widget in the previous section.
  3. Scroll down to the "Body" field and paste the code into that field.
  4. Replace the value of the "card_token" field with the token of the card you created previously.
  5. Replace the value of the "webhook.endpoint" field with a valid URL for receiving HTTP requests.
  6. Replace the values of the "username" and "password" fields with valid credentials for accessing the receiving endpoint.
    If you are using http://requestb.in to receive the notification, you can leave these fields as they are (values are required but can be any string).
  7. Click the "Submit Request" button.

Sample cURLs

For those who prefer to interact with the API by executing cURLs, this section provides sample cURLs that correspond to the API calls described earlier on this page. Sample cURLs are included for creating a card product, a funding source, a user, and a card, as well as for funding the user account and conducting an authorization transaction.

You will need to replace *username* and *password* in the samples with valid credentials. For more information on this topic, refer to the section on this page entitled, "API KEYS".

Create a cardproduct

//Save the token returned in the response
curl -i \
-X POST \
-H 'Content-type: application/json' \
--user *username*:*password* \
-d '{
"start_date": "2016-01-01",
"name": "Example Card Product",
"config": {
"fulfillment": {
"payment_instrument":"VIRTUAL_PAN"
},
"poi": {
"ecommerce": true
},
"card_life_cycle": {
"activate_upon_issue": true
}
}
}' \
https://shared-sandbox-api.marqeta.com/v3/cardproducts


Create a program funding source

//Save the token returned in the response
curl -i \
-X POST \
-H 'Content-type: application/json' \
--user *username*:*password* \
-d '{
"name": "Program Funding"
}' \
https://shared-sandbox-api.marqeta.com/v3/fundingsources/program


Create a user

//Save the token returned in the response
curl -i \
-X POST \
-H 'Content-type: application/json' \
--user *username*:*password* \
-d '{ }' \
https://shared-sandbox-api.marqeta.com/v3/users


Create a card

//Save the token in the response
curl -i \
-X POST \
-H 'Content-type: application/json' \
--user *username*:*password* \
-d '{
"user_token": "**USER TOKEN FROM PREVIOUS STEP**",
"card_product_token": "**CARD PRODUCT TOKEN FROM PREVIOUS STEP**"
}' \
https://shared-sandbox-api.marqeta.com/v3/cards?show_cvv_number=true&show_pan=true


Fund the user account

//Save the token in the response
curl -i \
-X POST \
-H 'Content-type: application/json' \
--user *username*:*password* \
-d '{
"user_token": "**USER TOKEN FROM PREVIOUS STEP**",
"amount": "1000",
"currency_code": "USD",
"funding_source_token": "**PROGRAM FUNDING SOURCE TOKEN FROM PREVIOUS STEP**"
}' \
https://shared-sandbox-api.marqeta.com/v3/gpaorders


Simulate a transaction

Note: Omit the webhook object if you do not want to receive an event notification.

//Save the token in the response
curl -i \
-X POST \
-H 'Content-type: application/json' \
--user *username*:*password* \
-d '{
"amount": "10",
"mid": "123456890",
"card_token": "**CARD TOKEN FROM PREVIOUS STEP**",
"webhook": {
"endpoint": "**URL FOR RECEIVING NOTIFICATIONS**",
"username": "**MY USER NAME**",
"password": "**MY PASSWORD**"
}
}' \
https://shared-sandbox-api.marqeta.com/simulate/authorization