Core API Quick Start

This page shows you how to simulate transactions in your sandbox on the Marqeta platform.

Note
After launching your card program in production, Marqeta will handle some of the operations described in this tutorial. Consult your Marqeta representative before trying these steps in production.

Use this tutorial to learn how to:

Access the sandbox.
Create the objects you use in sandbox transactions: a card product, a user, and a card.
Simulate a transaction.
Set up and receive a webhook notification about a simulated transaction.
Access your API credentials.

Step 1 — Create assets

Create an account

Click the sign-up link to create an account on the Marqeta platform: https://auth.marqeta.com/ As part of creating your account on Marqeta.com, you will also create a sandbox and a user.

Create a sandbox

After you have created your account and signed in again, you are ready to create the sandbox where you can simulate transactions on the Marqeta platform. Click Create sandbox. You will receive an email when your sandbox is ready. The sandbox creation page refreshes to display your Dashboard. Your personal API keys and a cURL to try out the sandbox are provided here.

Create a user

The JSON-formatted code sample below creates a simple user by omitting most request fields. See the Users API reference page for more about the /users endpoint. Save the user token returned in the response, since you will need it to create a card.

JSON

{
  "first_name": "Marqeta",
  "last_name": "User"
}

Tip
If you prefer, you can use the cURL equivalent from the Sample cURLs section instead of sending your request in the widget below.

Copy the preceding code.

Click the POST /users widget below.

In the widget, click the Send request tab.

Paste the code into the Request body field, replacing any existing sample code already there.

Click the Send request button.

Scroll down further to the Response body field, find the response’s token field, and copy it to a text file.

The interactive widgets appear only when you are signed in to the Marqeta platform.

Step 2 — Get a card product token

A card product defines the general characteristics and behavior of the cards that are generated from it. See the Card Products API reference page for more about the /cardproducts endpoint.

Tip
If you prefer, you can use the cURL equivalent from the Sample cURLs section instead of sending your request in the widget below.

Click the GET /cardproducts widget below.

In the widget, click the Send request tab.

Click the Send request button.

Scroll down further to the Response body field and find the response’s token field for the card product named “Reloadable Card”. Copy the token to a text file so you have it available later on when creating a card.

Create a card

Cards inherit the characteristics of the card products from which they are generated and are owned by users. See the Cards API reference page for more about the /cards endpoint. The JSON-formatted code sample below is a request that creates a single-use card that will become active immediately upon creation.

JSON

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

Tip
If you prefer, you can use the cURL equivalent from the Sample cURLs section instead of sending your request in the widget below.

Copy the preceding code.

Click the POST /cards widget below.

In the widget, click the Send request tab.

Paste the code into the Request body field, replacing any existing sample code already there.

Replace the value of the user_token field with the token of the user you created previously.

Replace the value of the card_product_token field with the token of the card product you created previously.

Click the Send request button.

Scroll down further to the Response body field, find the response’s token field, and copy it to a text file. You will need this token later when you simulate transactions.

Note
If you make the above POST request to the /cards endpoint more than once, only the last card you create will be active. The state of any card you had previously created is automatically transitioned to TERMINATED.For information about card states, see The card lifecycle.

Step 3 — Transact

In this step, you simulate the authorization of a $10 transaction. The sample request includes the required merchant ID number (MID). You will need the card token you created in the previous step. See Simulate authorization for more about the /simulations/cardtransactions/authorization endpoint.

Note
You don’t have to explicitly fund the card before transacting because the sandbox environment includes a Just-in-Time Funding source. The card you created in the previous step is automatically associated with this JIT Funding source.To simulate funding a card by pushing to your user’s general purpose account (GPA) instead, see the sample cURL for Create a GPA order to fund a user account.

JSON

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

Add the preceding code to the simulate a transaction cURL from the Sample cURLs section below.

Before executing the cURL, remember to replace the value of the card_token field with the token of the card you created earlier.

Transaction Timeline tool

You can view the transaction you just simulated above using the interactive Transaction Timeline tool. The Transaction Timeline provides a graphical, intuitive representation of how individual transactions impact each other, as well as how they affect the account balance. All public sandbox accounts with the Developer role include access to the Transaction Timeline. For more information about viewing transaction activity in the Transaction Timeline, see the Developer Tools guide.

Next steps

This section shows how you can use webhooks to create and receive notifications, as well as how to add spend controls to a user or card product.

Add a webhook

In this step, you simulate another authorization transaction, 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. This simulated transaction is initiated by an API call and will receive a response that is identical to the webhook notification.

In a sandbox environment, you can use the Developer Tools UI in the Marqeta Dashboard to create and view your webhook. For more information about working with webhooks in the Marqeta Dashboard, see Manage your webhooks.
In a production environment, transactions are initiated by merchants from outside the Marqeta environment, and not by an API call. To receive notifications about events in production, you should set up webhooks. Learn about setting up webhooks in the About Webhooks.

In order to receive and inspect the event notification, provide a URL that can accept the notification. Beeceptor provides a free online service that lets you receive and inspect HTTP requests. To use this service, go to https://beeceptor.com/, create an endpoint for receiving requests, and copy its URL into the body of your transaction request, for example: "endpoint": "https://marqeta-test.free.beeceptor.com/". You must replace the value of the card_token field with the token of the card you created.

JSON

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

Copy the preceding code.

Create the authorization using POST /simulations/cardtransactions/authorization.

Paste the code into the Request body field, replacing any existing sample code already there.

Replace the value of the card_token field with the token of the card you created previously.

Replace the value of the webhook.endpoint field with a valid URL for receiving HTTP requests.

Replace the values of the username and password fields with valid credentials for accessing the receiving endpoint.
If you are using https://beeceptor.com to receive the notification, you can leave these fields as they are (values are required for these fields, but can be any string).

Create spend controls

With the Marqeta platform, you can control a user’s spending based on:

Where the user spends (individual merchants or merchant categories)
How much the user spends (transaction amounts and frequency of spending)
How much the user spends with a specified merchant or merchant category

Create an authorization control

The authorization control resource is a spend control on a card product or a user. Authorization controls can either allow spending only at specified merchants, or block spending at specified merchants.

JSON

{
  "name": "No Donuts",
  "association": {
    "card_product_token": "**CARD PRODUCT TOKEN FROM PREVIOUS STEP**"
  },
  "merchant_scope": {
    "mid": "252824676910001"
  },
  "active": true
}

Copy the preceding code.

Click the POST /authcontrols widget below.

In the widget, click the Send request tab.

Paste the code into the Request body field, replacing any existing sample code already there.

Click the Send request button.

Create a velocity control

The velocity control resource is a spend control that limits how much and how frequently a user or a card product can spend funds.

JSON

{
  "name": "100 Daily Spend Limit",
  "association": {
    "card_product_token": "**CARD PRODUCT TOKEN FROM PREVIOUS STEP**"
  },
  "usage_limit": 100,
  "currency_code": "USD",
  "amount_limit": 100,
  "velocity_window": "DAY",
  "active": true
}

Copy the preceding code.

Click the POST /velocitycontrols widget below.

In the widget, click the Send request tab.

Paste the code into the Request body field, replacing any existing sample code already there.

Click the Send request button.

API keys

You need valid API keys if you want to explore the API using your own client application or by executing cURLs. Keys consist of an application token, an admin access token, and the base URL of the sandbox environment. They are listed in your Dashboard:

When making basic auth requests to the Marqeta platform, implement the API keys per the table below:

Key Name	Usage
Application token	Your username.
Admin access token	Your password.
Base URL	Prefix this value to your endpoint URL.

See Sample cURLs for examples of all the requests used in this quick start. For more information about other tools available to help you develop your application, see Developer Tools.

Sample cURLs

If you prefer to make the API calls in this quick start by executing cURLs, use the sample cURLs in this section. Replace username and password in the samples with valid credentials. See API Keys for more information.

Create a card product

Save the token returned in the response for later use.

cURL

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

Create a program funding source

Save the token returned in the response for later use.

cURL

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

Create a user

Save the token returned in the response for later use.

cURL

curl -i \
-X POST \
-H 'Content-type: application/json' \
--user *username*:*password* \
-d '{ }' \
"https://sandbox-api.marqeta.com/v3/users"

Create a card

Save the token returned in the response for later use.

cURL

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://sandbox-api.marqeta.com/v3/cards?show_cvv_number=true&show_pan=true"

Simulate a transaction

Note
Omit the webhook object if you do not want to receive an event notification.
Save the token returned in the response for later use.

cURL

curl -i \
-X POST \
-H 'Content-type: application/json' \
--user *username*:*password* \
-d '{
     "amount": "10",
     "card_token": "**CARD TOKEN FROM PREVIOUS STEP**",
     "card_acceptor": {
      "mid": "123456890"
      },
     "network": "VISA",
     "webhook": {
            "endpoint": "**URL FOR RECEIVING NOTIFICATIONS**",
            "username": "**MY USER NAME**",
            "password": "**MY PASSWORD**"
          }
     }' \
"https://sandbox-api.marqeta.com/v3/simulations/cardtransactions/authorization"

Create an authorization control

cURL

curl -X POST \
  -H 'Content-Type: application/json' \
  -u *username*:*password* \
  -d '{
        "name": "No Donuts",
        "association": {
          "card_product_token": "**CARD PRODUCT TOKEN FROM PREVIOUS STEP**"
        },
        "merchant_scope": {
          "mid": "252824676910001"
        },
        "active": true
      }'
"https://sandbox-api.marqeta.com/v3/authcontrols"

Create a velocity control

cURL

curl -X POST \
  -H 'Content-type: application/json' \
  -u *username*:*password* \
  -d '{
      "name": "100 Daily Spend Limit",
      "association": {
        "card_product_token": "**CARD PRODUCT TOKEN FROM PREVIOUS STEP**"
      },
      "usage_limit": 100,
      "currency_code": "USD",
      "amount_limit": 100,
      "velocity_window": "DAY",
      "active": true
    }'
"https://sandbox-api.marqeta.com/v3/velocitycontrols"

Create a GPA order to fund a user account

Use this cURL to load $1000 into the general purpose account (GPA) of your user by creating a gpaorder object. The funding_source_token identifies the funding source to use for this transaction; this is how you can access funds outside of the Marqeta platform. You must configure at least one funding source in order to transact in a production environment. Your program funding source token is available in your Dashboard. The sample below is a request that creates a $1000 gpaorder.

cURL

curl -i \
-X POST \
-H 'Content-type: application/json' \
--user *username*:*password* \
-d '{
      "user_token": "**USER TOKEN FROM TUTORIAL ABOVE**",
      "amount": "1000.00",
      "currency_code": "USD",
      "funding_source_token": "sandbox_program_funding"
    }' \
"https://sandbox-api.marqeta.com/v3/gpaorders"

Guides

​Step 1 — Create assets

​Create an account

​Create a sandbox

​Create a user

​Step 2 — Get a card product token

​Create a card

​Step 3 — Transact

​Transaction Timeline tool

​Next steps

​Add a webhook

​Create spend controls

​Create an authorization control

​Create a velocity control

​API keys

​Sample cURLs

​Create a card product

​Create a program funding source

​Create a user

​Create a card

​Simulate a transaction

​Create an authorization control

​Create a velocity control

​Create a GPA order to fund a user account

Step 1 — Create assets

Create an account

Create a sandbox

Create a user

Step 2 — Get a card product token

Create a card

Step 3 — Transact

Transaction Timeline tool

Next steps

Add a webhook

Create spend controls

Create an authorization control

Create a velocity control

API keys

Sample cURLs

Create a card product

Create a program funding source

Create a user

Create a card

Simulate a transaction

Create an authorization control

Create a velocity control

Create a GPA order to fund a user account