DOCS

New!

/

5 minute read

November 5, 2019

Core API Quick Start

This page shows how to start simulating transactions in the Marqeta sandbox. After completing these steps, you will know how to:

  • Access the sandbox

  • Create the objects to use in transactions: a card product, a funding source, a user, and a card

  • Fund your user’s account

  • Simulate a transaction

  • Set up and receive a webhook notification about a transaction

For a general introduction to the Marqeta platform, see Platform Features Overview.

To understand how the Marqeta Core API works, see the Introduction to the Core API.

Step 1 — Get access

Create account

Create an account on Marqeta.com and get access to the sandbox.

API Explorer

When you log in to your account, you can use the API Explorer in your browser to interact with the Core API.

This page also includes embedded API Explorer widgets that let you send requests to specific API endpoints. When you sign in, these widgets will appear on the page.

Step 2 — Create objects

In this step, create the objects you need to conduct a transaction:

  • A card product defines the general characteristics and behavior of the cards that are generated from it. You can learn more about them here: Card Products.

  • Funding sources give a user account access to funds. Learn more: Account Holder Funding Sources.

  • Users represent the owners of cards. Each user automatically owns a general purpose account (GPA) that funds the user’s transactions. Learn more: Users.

  • Cards inherit the characteristics of the card products from which they are generated, and are owned by users. Learn more: Cards.

Create a card product

The JSON-formatted code sample below is a request that creates a card product configured so that cards generated from it are activated upon issue.

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

Is this helpful?

To create a card product:

  1. Copy the preceding code.

  2. Click the POST /cardproducts widget below.

  3. In the widget, click Try it out.

  4. Paste the code into the body field.

  5. Click the Execute button.

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

Click the widget below to use the API Explorer. The widget appears only when you are signed in.

Develop Now!

Sign in and use your sandbox to access the API Explorer

Create a program funding source

The JSON-formatted code sample below is a request that creates a program funding source.

{
    "name": "Program Funding"
}

Is this helpful?

To create a program funding source:

  1. Copy the preceding code.

  2. Click the POST /fundingsources/program widget below.

  3. In the widget, click Try it out.

  4. Paste the code into the body field.

  5. Click the Execute button.

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

Develop Now!

Sign in and use your sandbox to access the API Explorer

Create a user

The JSON-formatted code sample below is a request that creates a generic user.

{}

Is this helpful?

To create a user:

  1. Copy the preceding code.

  2. Click the POST /users widget below.

  3. In the widget, click Try it out.

  4. Paste the code into the body field.

  5. Click the Execute button.

  6. Scroll down further to the Response body field and find the response’s token field, and copy it into a text file. You will need this token later when you create a card, fund the user account, and conduct transactions.

Develop Now!

Sign in and use your sandbox to access the API Explorer

Create a card

The JSON-formatted code sample below is a request that creates a card that will become active immediately upon creation.

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

Is this helpful?

To create a card:

  1. Copy the preceding code.

  2. Click the POST /cards widget below.

  3. In the widget, click Try it out.

  4. Paste the code into the body field.

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

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

  7. Click the Execute button.

  8. 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 conduct transactions.

Develop Now!

Sign in and use your sandbox to access the API Explorer

Step 3 — Fund the user account

In this step, you load $1000 into the GPA of your user by creating a gpaorder object. You will need the user and program funding source tokens you created earlier.

The JSON-formatted code sample below is a request that creates a $1000 gpaorder.

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

Is this helpful?

To fund a user’s GPA:

  1. Copy the preceding code.

  2. Click the POST /gpaorders widget below.

  3. In the widget, click Try it out.

  4. Paste the code into the body field.

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

  6. Replace the value of the funding_source_token field with the token of the program funding source you created earlier.

  7. Click the Execute button.

Develop Now!

Sign in and use your sandbox to access the API Explorer

Step 4 — Transact

In this step you simulate an authorization transaction for $10. The sample request includes the required merchant ID number (MID). You will need the card token.

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

Is this helpful?

To simulate an authorization transaction:

  1. Copy the preceding code.

  2. Click the POST /simulate/authorization widget below.

  3. In the widget, click Try it out.

  4. Paste the code into the body field.

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

  6. Click the Execute button.

Develop Now!

Sign in and use your sandbox to access the API Explorer

Step 5 — 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.

Note
This simulated transaction is initiated by an API call, and will receive a response that is identical to the webhook notification. 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, set up webhooks. Learn about setting up webhooks: Webhooks Overview.

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://beeceptor.com/console/marqeta-test").

As before, a MID is provided in the mid field, and you must 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**",
    "webhook": {
      "endpoint": "**URL FOR RECEIVING NOTIFICATIONS**",
      "username": "**MY USER NAME**",
      "password": "**MY PASSWORD**"
    }
}

Is this helpful?

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. In the widget, click Try it out.

  4. Paste the code into the body field.

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

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

  7. Replace the values of the username and password fields with valid credentials for accessing the receiving endpoint.

  8. If you are using https://beeceptor.com to receive the notification, you can leave these fields as they are (values are required but can be any string).

  9. Click the Execute button.

API keys

If you prefer to explore the API using your own client application or by executing cURLs, instead of using the API Explorer, you need valid API keys. These consist of an application token, a master access token, and the base URL of the sandbox environment. They are listed near the top of the API Explorer:

API Explorer

Is this helpful?

In 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. See below for sample cURLs of all the requests used in this quickstart.

Sample cURLs

If you prefer to make the API calls in this quickstart by executing cURLs, use the sample cURLs in this section.

Replace username and password in the samples with valid credentials. See API Keys for information.

Create a card product

curl -i \
-X POST \
-H "Content-type: application/json" \
--user *username*:*password* \
-d "{
  "start_date": "2019-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

Is this helpful?

Create a program funding source

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

Is this helpful?

Create a user

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

Is this helpful?

Create a card

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

Is this helpful?

Fund the user account

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

Is this helpful?

Simulate a transaction

Note
Omit the webhook object if you do not want to receive an event notification.
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/v3/simulate/authorization

Is this helpful?

Have any feedback on this page?

If you feel we can do anything better, please let our team know.

We strive for the best possible developer experience.