> ## Documentation Index
> Fetch the complete documentation index at: https://www.marqeta.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Core API Quick Start

> Use this Quick Start to start learning how the Marqeta platform works by simulating transactions in your sandbox.

export const EndpointCard = ({method = "API", title, children, href, arrow = true}) => {
  const METHOD_STYLES = {
    GET: {
      bg: "mint-bg-green-400/20 dark:mint-bg-green-400/20",
      text: "mint-text-green-700 dark:mint-text-green-400",
      border: "mint-border-green-300 dark:mint-border-green-700"
    },
    POST: {
      bg: "mint-bg-blue-400/20 dark:mint-bg-blue-400/20",
      text: "mint-text-blue-700 dark:mint-text-blue-400"
    },
    PUT: {
      bg: "mint-bg-yellow-400/20 dark:mint-bg-yellow-400/20",
      text: "mint-text-yellow-700 dark:mint-text-yellow-400"
    },
    PATCH: {
      bg: "mint-bg-orange-400/20 dark:mint-bg-orange-400/20",
      text: "mint-text-orange-700 dark:mint-text-orange-400"
    },
    DELETE: {
      bg: "mint-bg-red-400/20 dark:mint-bg-red-400/20",
      text: "mint-text-red-700 dark:mint-text-red-400"
    },
    API: {
      bg: "mint-bg-black",
      text: "mint-text-white"
    }
  };
  const MethodBadge = ({method}) => {
    const style = METHOD_STYLES[method?.toUpperCase()] ?? METHOD_STYLES.GET;
    return <span className={`
          method-pill rounded-lg font-semibold px-1.5 py-0.5 text-xs leading-5 ${style.bg} ${style.text}`}>
        {method?.toUpperCase()}
      </span>;
  };
  const content = <div className="group flex items-center gap-4 border border-gray-200 dark:border-gray-700 rounded-xl p-5 hover:border-gray-400 dark:hover:border-gray-500 hover:shadow-md transition-all cursor-pointer">
      {}
      <div className="shrink-0">
        <MethodBadge method={method} />
      </div>
      {}
      <div className="flex-1 min-w-0">
        <p className="font-semibold text-gray-900 dark:text-white text-sm leading-snug">{title}</p>
        {children && <p className="mt-1 text-sm text-gray-500 dark:text-gray-400 line-clamp-2">{children}</p>}
      </div>
    </div>;
  if (!href) return content;
  return <a href={href} className="block no-underline border-b-0 mb-2">
      {content}
    </a>;
};

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

<Note>
  **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.
</Note>

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.

<h2 id="_step_1_create_assets">
  Step 1 — Create assets
</h2>

<h3 id="_create_an_account">
  Create an account
</h3>

Click the sign-up link to create an account on the Marqeta platform: [https://auth.marqeta.com/create-account](https://auth.marqeta.com/create-account)

As part of creating your account on Marqeta.com, you will also create a sandbox and a user.

<h3 id="_create_a_sandbox">
  Create a sandbox
</h3>

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](https://app.marqeta.com/development). Your personal API keys and a cURL to try out the sandbox are provided here.

<h3 id="_create_a_user">
  Create a user
</h3>

The JSON-formatted code sample below creates a simple user by omitting most request fields. See the [Users](/core-api/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 JSON lines wrap theme={null}
{
  "first_name": "Marqeta",
  "last_name": "User"
}
```

<Tip>
  **Tip**
  If you prefer, you can use the [cURL equivalent](/developer-guides/core-api-quick-start/#_create_a_user_2) from the [Sample cURLs](/developer-guides/core-api-quick-start/#_sample_curls) section instead of sending your request in the widget below.
</Tip>

<Steps>
  <Step>
    Copy the preceding code.
  </Step>

  <Step>
    Click the **POST /users** widget below.
  </Step>

  <Step>
    In the widget, click the **Send request** tab.
  </Step>

  <Step>
    Paste the code into the **Request body** field, replacing any existing sample code already there.
  </Step>

  <Step>
    Click the **Send request** button.
  </Step>

  <Step>
    Scroll down further to the **Response body** field, find the response’s `token` field, and copy it to a text file.
  </Step>
</Steps>

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

{/* <EndpointCard
href="/core-api/users/postUsers"
title="Creates a user"
path="/users"
method="post"
/> */}

<h2 id="_step_2_get_a_card_product_token">
  Step 2 — Get a card product token
</h2>

A card product defines the general characteristics and behavior of the cards that are generated from it. See the [Card Products](/core-api/card-products/) API reference page for more about the `/cardproducts` endpoint.

<Tip>
  **Tip**
  If you prefer, you can use the [cURL equivalent](/developer-guides/core-api-quick-start/#_create_a_card_product) from the [Sample cURLs](/developer-guides/core-api-quick-start/#_sample_curls) section instead of sending your request in the widget below.
</Tip>

<Steps>
  <Step>
    Click the **GET /cardproducts** widget below.
  </Step>

  <Step>
    In the widget, click the **Send request** tab.
  </Step>

  <Step>
    Click the **Send request** button.
  </Step>

  <Step>
    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.
  </Step>
</Steps>

{/* <EndpointCard
href="/core-api/card-products/getCardproducts"
title="Lists all card products"
path="/cardproducts"
method="get"
/> */}

<h3 id="_create_a_card">
  Create a card
</h3>

Cards inherit the characteristics of the card products from which they are generated and are owned by users. See the [Cards](/core-api/cards/) API reference page for more about the `/cards` endpoint.

The JSON-formatted code sample below is a request that creates a [single-use](/developer-guides/about-cards/#_single_vs_multi_use_cards) card that will become active immediately upon creation.

```json JSON lines wrap theme={null}
{
  "user_token": "**USER TOKEN**",
  "card_product_token": "**CARD PRODUCT TOKEN**"
}
```

<Tip>
  **Tip**
  If you prefer, you can use the [cURL equivalent](/developer-guides/core-api-quick-start/#_create_a_card_2) from the [Sample cURLs](/developer-guides/core-api-quick-start/#_sample_curls) section instead of sending your request in the widget below.
</Tip>

<Steps>
  <Step>
    Copy the preceding code.
  </Step>

  <Step>
    Click the **POST /cards** widget below.
  </Step>

  <Step>
    In the widget, click the **Send request** tab.
  </Step>

  <Step>
    Paste the code into the **Request body** field, replacing any existing sample code already there.
  </Step>

  <Step>
    Replace the value of the `user_token` field with the token of the user you created previously.
  </Step>

  <Step>
    Replace the value of the `card_product_token` field with the token of the card product you created previously.
  </Step>

  <Step>
    Click the **Send request** button.
  </Step>

  <Step>
    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>
</Steps>

<Note>
  **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](/developer-guides/about-cards/#_the_card_lifecycle).
</Note>

{/* <EndpointCard
href="/core-api/cards/postCards"
title="Creates a card"
path="/cards"
method="post"
/> */}

<h2 id="_step_3_transact">
  Step 3 — Transact
</h2>

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](/core-api/simulations-card-transactions/#authorization_event) for more about the `/simulations/cardtransactions/authorization` endpoint.

<Note>
  **Note**
  You don’t have to explicitly fund the card before transacting because the sandbox environment includes a [Just-in-Time Funding source](/developer-guides/about-jit-funding/). 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](#_create_a_gpa_order_to_fund_a_user_account).
</Note>

```json JSON lines wrap theme={null}
{
  "amount": "10",
  "card_token": "**CARD TOKEN FROM PREVIOUS STEP**",
  "card_acceptor": {
    "mid": "123456890"
  },
  "network": "VISA"
}
```

<Steps>
  <Step>
    Add the preceding code to the [simulate a transaction cURL](/developer-guides/core-api-quick-start/#_simulate_a_transaction) from the [Sample cURLs](/developer-guides/core-api-quick-start/#_sample_curls) section below.
  </Step>

  <Step>
    Before executing the cURL, remember to replace the value of the `card_token` field with the token of the card you created earlier.
  </Step>
</Steps>

<h3 id="_transaction_timeline_tool">
  Transaction Timeline tool
</h3>

You can view the transaction you just simulated above using the interactive [Transaction Timeline](https://app.marqeta.com/development/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](https://app.marqeta.com/development/transaction-timeline), see the [Developer Tools](/developer-guides/developer-tools/) guide.

<h2 id="_next_steps">
  Next steps
</h2>

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.

<h3 id="_add_a_webhook">
  Add a webhook
</h3>

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](/developer-guides/control-center-dashboard/#_developer_tools).

* 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](/developer-guides/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/](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 JSON lines wrap theme={null}
{
  "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**"
  }
}
```

<Steps>
  <Step>
    Copy the preceding code.
  </Step>

  <Step>
    Create the authorization using **POST /simulations/cardtransactions/authorization**.
  </Step>

  <Step>
    Paste the code into the **Request body** field, replacing any existing sample code already there.
  </Step>

  <Step>
    Replace the value of the `card_token` field with the token of the card you created previously.
  </Step>

  <Step>
    Replace the value of the `webhook.endpoint` field with a valid URL for receiving HTTP requests.
  </Step>

  <Step>
    Replace the values of the `username` and `password` fields with valid credentials for accessing the receiving endpoint.
    If you are using [https://beeceptor.com](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).
  </Step>
</Steps>

<h3 id="_create_spend_controls">
  Create spend controls
</h3>

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

<h4 id="_create_an_authorization_control">
  Create an authorization control
</h4>

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 JSON lines wrap theme={null}
{
  "name": "No Donuts",
  "association": {
    "card_product_token": "**CARD PRODUCT TOKEN FROM PREVIOUS STEP**"
  },
  "merchant_scope": {
    "mid": "252824676910001"
  },
  "active": true
}
```

<Steps>
  <Step>
    Copy the preceding code.
  </Step>

  <Step>
    Click the **POST /authcontrols** widget below.
  </Step>

  <Step>
    In the widget, click the **Send request** tab.
  </Step>

  <Step>
    Paste the code into the **Request body** field, replacing any existing sample code already there.
  </Step>

  <Step>
    Click the **Send request** button.
  </Step>
</Steps>

{/* <EndpointCard
href="/core-api/authorization-controls/postAuthcontrols"
title="Creates an auth control exception"
path="/authcontrols"
method="post"
/> */}

<h4 id="_create_a_velocity_control">
  Create a velocity control
</h4>

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 JSON lines wrap theme={null}
{
  "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
}
```

<Steps>
  <Step>
    Copy the preceding code.
  </Step>

  <Step>
    Click the **POST /velocitycontrols** widget below.
  </Step>

  <Step>
    In the widget, click the **Send request** tab.
  </Step>

  <Step>
    Paste the code into the **Request body** field, replacing any existing sample code already there.
  </Step>

  <Step>
    Click the **Send request** button.
  </Step>
</Steps>

{/* <EndpointCard
href="/core-api/velocity-controls/postVelocitycontrols"
title="Creates a velocity control"
path="/velocitycontrols"
method="post"
/> */}

<h2 id="_api_keys">
  API keys
</h2>

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](https://app.marqeta.com/development):

<Frame>
  <img src="https://mintcdn.com/marqeta-b295cded/Zl4-OzNLF5XRh78N/images/docs/developer-guides/core-api-quick-start/quickstart_1.png?fit=max&auto=format&n=Zl4-OzNLF5XRh78N&q=85&s=47da7bb75bd2f5848b62b97e5004d252" alt="API keys in the Dashboard" width="755" height="417" data-path="images/docs/developer-guides/core-api-quick-start/quickstart_1.png" />
</Frame>

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](#_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](/developer-guides/developer-tools/).

<h2 id="_sample_curls">
  Sample cURLs
</h2>

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](#_api_keys) for more information.

<h3 id="_create_a_card_product">
  Create a card product
</h3>

Save the token returned in the response for later use.

```sh cURL lines wrap theme={null}
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"
```

<h3 id="_create_a_program_funding_source">
  Create a program funding source
</h3>

Save the token returned in the response for later use.

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

<h3 id="_create_a_user_2">
  Create a user
</h3>

Save the token returned in the response for later use.

```sh cURL lines wrap theme={null}
curl -i \
-X POST \
-H 'Content-type: application/json' \
--user *username*:*password* \
-d '{ }' \
"https://sandbox-api.marqeta.com/v3/users"
```

<h3 id="_create_a_card_2">
  Create a card
</h3>

Save the token returned in the response for later use.

```sh cURL lines wrap theme={null}
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"
```

<h3 id="_simulate_a_transaction">
  Simulate a transaction
</h3>

<Note>
  **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.
</Note>

```sh cURL lines wrap theme={null}
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"
```

<h3 id="_create_an_authorization_control_2">
  Create an authorization control
</h3>

```sh cURL lines wrap theme={null}
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"
```

<h3 id="_create_a_velocity_control_2">
  Create a velocity control
</h3>

```sh cURL lines wrap theme={null}
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"
```

<h3 id="_create_a_gpa_order_to_fund_a_user_account">
  Create a GPA order to fund a user account
</h3>

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](https://app.marqeta.com/development).

The sample below is a request that creates a \$1000 `gpaorder`.

```sh cURL lines wrap theme={null}
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"
```