Marqeta.com
Support
/
10 minute read
December 23, 2020

Core API Quick Start

This page shows you how to start simulating 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 funding source, a user, and a card.

  • Fund your sandbox user’s account.

  • Simulate a transaction.

  • Set up and receive a webhook notification about a simulated transaction.

  • Access your API credentials.

To learn how money moves via the Marqeta platform, see the Money Movement Overview. Its Concepts section defines some common concepts in payment card programs.

For a summary of Marqeta platform features, see the Platform Features Overview.

Step 1 — Create assets

Create an account

Click the sign-up link below to create an account on the Marqeta platform: https://www.marqeta.com/users/sign_up

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 the "Hello, World!" code are provided here.

Create a user

Run the "Hello, World!" code in your Dashboard to create a user. Save the user token returned in the response, since you will need it to create a card.

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 guide for more about the

/cardproducts
endpoint.

  • 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, and copy it into a text file. You will need this token later when you create a card.

The interactive widgets appear only when you are signed in.

Create a card

Cards inherit the characteristics of the card products from which they are generated, and are owned by users. See the Cards guide for more about the

/cards
endpoint.

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

Copied

Is this helpful?

Yes
No
  • 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.

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

Step 3 — Fund the user account

In this step, you load $1000 into the general purpose account (GPA) of your user by creating a

gpaorder
object. You will need your user token and the program funding source token, both available in your Dashboard.

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

gpaorder
.

Copied

Is this helpful?

Yes
No
  • Copy the preceding code.

  • Click the POST /gpaorders widget below.

  • In the widget, click the Send request tab.

  • Paste the code into the

    Request body
    field.

  • Replace the value of the

    user_token
    field with the token of the user you created earlier.

  • Click the Send request button.

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

Copied

Is this helpful?

Yes
No
  • Copy the preceding code.

  • Click the POST /simulate/authorization widget below.

  • In the widget, click the Send request tab.

  • Paste the code into the

    Request body
    field.

  • Replace the value of the

    card_token
    field with the token of the card you created earlier.

  • Click the Send request button.

Next steps

This section shows how you can use webhooks to create and receive notifications, as well as how to add spending 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.

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, you should set up webhooks. Learn about setting up webhooks in the 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://marqeta-test.free.beeceptor.com/"
.

You must replace the value of the

card_token
field with the token of the card you created.

Copied

Is this helpful?

Yes
No
  • Copy the preceding code.

  • Click the POST /simulate/authorization widget in the previous section.

  • In the widget, click the Send request tab.

  • Paste the code into the

    Request body
    field.

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

  • Click the Send request button.

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.

Copied

Is this helpful?

Yes
No
  • 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.

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

Copied

Is this helpful?

Yes
No
  • 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.

  • Click the Send request button.

API keys

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

API keys in the Dashboard

Is this helpful?

Yes
No

In each API request, use the application token as the username, the admin 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 quick start.

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

Create a card product

Save the token returned in the response for later use.

Copied

Is this helpful?

Yes
No
Create a program funding source

Save the token returned in the response for later use.

Copied

Is this helpful?

Yes
No
Create a user

Save the token returned in the response for later use.

Copied

Is this helpful?

Yes
No
Create a card

Save the token returned in the response for later use.

Copied

Is this helpful?

Yes
No
Fund the user account

Save the token returned in the response for later use.

Copied

Is this helpful?

Yes
No
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.
Copied

Is this helpful?

Yes
No
Create an authorization control
Copied

Is this helpful?

Yes
No
Create a velocity control
Copied

Is this helpful?

Yes
No

Feedback on this page?

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