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
Copy section link
Create an account
Copy section link
Click the sign-up link below 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
Copy section link
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
Copy section link
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.
-
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.
-
Click the Send request button.
-
Scroll down further to the Response body field, find the response’s
tokenfield, 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
Copy section link
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.
-
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
tokenfield 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
Copy section link
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.
-
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_tokenfield with the token of the user you created previously. -
Replace the value of the
card_product_tokenfield 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
tokenfield, and copy it to a text file. You will need this token later when you simulate transactions.
Note
If you make the abovePOST 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
Copy section link
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.
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.
-
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 bodyfield. -
Replace the value of the
card_tokenfield with the token of the card you created earlier. -
Click the Send request button.
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 section of the Dashboard Overview and Quick Start.
Next steps
Copy section link
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
Copy section link
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 API Explorer to create and view your webhook. You also have the option of creating and managing webhooks using the Developer Tools UI in Marqeta Dashboard. For more information about working with webhooks in 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.
-
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 bodyfield. -
Replace the value of the
card_tokenfield with the token of the card you created previously. -
Replace the value of the
webhook.endpointfield with a valid URL for receiving HTTP requests. -
Replace the values of the
usernameandpasswordfields 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
Copy section link
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
Copy section link
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.
-
Copy the preceding code.
-
Click the POST /authcontrols widget below.
-
In the widget, click the Send request tab.
-
Paste the code into the
Request bodyfield. -
Click the Send request button.
Create a velocity control
Copy section link
The velocity control resource is a spend control that limits how much and how frequently a user or a card product can spend funds.
-
Copy the preceding code.
-
Click the POST /velocitycontrols widget below.
-
In the widget, click the Send request tab.
-
Paste the code into the
Request bodyfield. -
Click the Send request button.
API keys
Copy section link
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:
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.
Sample cURLs
Copy section link
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
Copy section link
Save the token returned in the response for later use.
Create a program funding source
Copy section link
Save the token returned in the response for later use.
Create a user
Copy section link
Save the token returned in the response for later use.
Create a card
Copy section link
Save the token returned in the response for later use.
Simulate a transaction
Copy section link
Note
Omit thewebhook object if you do not want to receive an event notification. Save the token returned in the response for later use.
Create a GPA order to fund a user account
Copy section link
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.