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

> ## Agent Instructions
> Agentcard is for companies whose agent buys for their users. Pick one path: the opencommerce SDK (@agent-cards/commerce-sdk) gives your agent one buy tool that finds the product, builds the cart, gets the user's approval and places the order at real stores; the Agentcard SDK (@agent-cards/sdk) pays with the user's own card when your agent already shops in a browser (Browser Use, Kernel, Browserbase, Anchor or Notte); the Purchase API (POST /buy) does the same purchase flow over plain HTTP in any language; Issuing gives the agent its own card.
> Start with `npx agent-cards init` in the app's folder (Node 22 or later). No invite is needed: it creates your Agentcard account if you don't have one, installs the opencommerce SDK and puts the credentials in the env file, kept out of git. From a coding agent, run `npx agent-cards init --print --categories all --implementation tool --wallet vault --skip-install` to get the setup steps to apply yourself.
> Vault is by invitation: request it at https://agentcard.com/get-started?utm_source=docs&utm_medium=llms&utm_campaign=agent-instructions. opencommerce needs no invite.
> Never ask a user for a card number, expiry date or CVV in chat. Send them the Vault link; they add their card on Agentcard's page, and the agent never sees the number.
> Every purchase is approved by the user, with a passkey or Face ID, or by an auto-approval they granted. An approval covers one merchant and one exact total. If the total changes, ask again. When a result says the user already said yes, don't ask again.
> `init` writes PRODUCTION credentials, which place real orders, so test in sandbox first. For opencommerce, run `npx agent-cards credentials --mode sandbox` and put the two lines it prints in place of the production ones in the env file `init` wrote, because that command only prints them; sandbox then runs the whole flow against real stores and stops before payment, so no order is placed and nobody is charged. For Vault and Issuing, sandbox credentials issue test cards that no real merchant accepts; try the checkout against shop.agentcard.sh, a test store on Stripe test mode.
> Tell the user an order is placed only after Agentcard reports it placed.
> Vault is free up to 5,000 users (https://agentcard.com/pricing). opencommerce takes 1% of each completed order. Full docs in one file: https://docs.agentcard.com/llms-full.txt

# Test a purchase in the sandbox

> Run every step of a purchase against real stores, from the search to the shopper's approval, with no order placed and nothing charged.

Run a whole purchase before you spend any money. The sandbox, Agentcard's test mode, searches real stores, builds real carts at the stores' real prices, and stops at payment. No order is placed and nobody is charged.

## Get sandbox credentials

Sandbox credentials are a second client ID and client secret for your company. Copy them with Agentcard's command-line tool:

```bash theme={null}
npx agent-cards credentials --mode sandbox
```

Every call made with sandbox credentials runs in the sandbox. Nothing else changes: the address, the calls and the tools stay the same.

> [tab] SDK
>
> Put the two lines in place of the production ones in your env file, `.env.local` for Next.js and `.env` otherwise:
>
> ```text theme={null}
> AGENTCARD_CLIENT_ID=your_client_id
> AGENTCARD_CLIENT_SECRET=your_client_secret
> ```
>
> After the client's first call, `agentcard.sandbox` reads `true`.

> [tab] MCP
>
> Send the sandbox pair in the `Authorization` header, as [Connect to the Commerce MCP server](https://docs.agentcard.com/commerce-mcp/index.md#authenticate-with-your-commerce-sdk-credentials) shows. Call [`get_account`](https://docs.agentcard.com/commerce-mcp/tools/get_account) to check which credentials the server sees:
>
> ```json theme={null}
> {
>   "tool": "get_account",
>   "arguments": {}
> }
> ```
>
> ```json theme={null}
> {
>   "client_id": "94ae25b9-306a-427b-b717-ff2d3b0ea53f",
>   "sandbox": true
> }
> ```

> [tab] API
>
> Exchange them for an access token as [Get an access token](https://docs.agentcard.com/purchase-api/http.md#get-an-access-token) shows. The answer says `"sandbox": true`:
>
> ```json theme={null}
> {
>   "access_token": "...",
>   "token_type": "Bearer",
>   "expires_in": 3600,
>   "scope": "api",
>   "sandbox": true
> }
> ```

## Run a purchase end to end

Send the same calls you send in live mode. Any new shopper id works: Agentcard adds the shopper on their first request. Ask for something, pick a product, and answer each question Agentcard asks, such as the address. When the cart is ready, `next_action` reads `confirm`.

Confirm the cart, and the sandbox stops at payment. The purchase ends `declined` with `decline_code` set to `sandbox_mode`, which means your run worked. Everything before it is what a live shopper sees.

A store can price the tax only at the confirm. Then the first confirm comes back with a new total instead of paying, as it would in live mode, and you confirm again.

> [tab] SDK
>
> Run the walkthrough that ships with the package. It connects a test shopper, asks for a restaurant table, picks one and confirms it, with no model involved:
>
> ```bash theme={null}
> AGENTCARD_CLIENT_ID=your_client_id AGENTCARD_CLIENT_SECRET=your_client_secret node node_modules/@agent-cards/commerce-sdk/examples/walkthrough.mjs
> ```
>
> The sandbox refuses the booking itself, so the last answer is `declined` with `decline_code: sandbox_unavailable`, and the run ends with:
>
> ```text theme={null}
> walkthrough passed
> ```
>
> Then send your own agent "two packs of AA batteries from Amazon" as a test shopper, and look for product cards, a short reply and a cart. The buy tool's answer to the shopper's yes reads `status: 'declined'` and `decline_code: 'sandbox_mode'`.

> [tab] MCP
>
> This run bought a pack of batteries at Amazon for a test shopper. The second `buy` picked the product and gave the address in one message. The third sent the shopper's yes with `confirm: true`, and answered:
>
> ```json theme={null}
> {
>   "status": "declined",
>   "reply": "I couldn't place the order. This connection is in test mode, so it can't pay a real store, and Amazon didn't take the order. Nothing was charged. ...",
>   "next_action": null,
>   "links": [],
>   "conversation_id": "conv_3a421f4b8b01ed02f8d71bb6",
>   "order_id": null,
>   "decline_code": "sandbox_mode",
>   "error_code": null,
>   ...
> }
> ```

> [tab] API
>
> This run bought a pack of batteries at Amazon for a test shopper, `docs-guide-refusals-1`:
>
> ```bash theme={null}
> curl https://api.agentcard.sh/buy \
>   -H "Authorization: Bearer $AGENTCARD_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{ "ask": "a pack of AA batteries from amazon", "external_user_id": "docs-guide-refusals-1" }'
> ```
>
> The answer lists real products at Amazon's real prices in `catalog`. After the pick, the address and the phone number, the cart is ready:
>
> ```json theme={null}
> {
>   "status": "needs_input",
>   "reply": "Got it, it ships to 1 Ferry Plz, San Francisco, CA 94111. Say yes to place the order.",
>   "next_action": "confirm",
>   "cart": { "merchant": "retail", "merchant_name": "Amazon", "totalCents": 1024, "totalIsEstimate": true, "hash": "ad9cdf1a1a5037ab", ... }
> }
> ```
>
> Confirm with the cart's `hash`, a short code that names this exact cart at this price. In this run Amazon then priced the tax, so the first confirm came back with a new total, \$11.12, and a new hash. Confirming the new hash stopped at payment:
>
> ```json theme={null}
> {
>   "conversation_id": "conv_ddaaf96c052893b13209e6c9",
>   "status": "declined",
>   "reply": "I couldn't place the order. This connection is in test mode, and test mode can't pay a real store like Amazon. Nothing was charged. ...",
>   "decline_code": "sandbox_mode",
>   "charge_status": "none",
>   "cart": { "totalCents": 1112, "hash": "55952914e74b3539", ... }
> }
> ```

## Save a test card

Some stores are bought through their own checkout page, which Agentcard fills in. There the shopper pays with a card saved in the Vault, Agentcard's page where the shopper saves their card and approves a payment, so a sandbox shopper needs a test card first. A confirm at such a store for a shopper with no test card is refused with `test_card_missing`, and the store keeps the cart:

```text theme={null}
409
{"error":"This is a test checkout, and it needs a test card on file for this shopper, which there isn't. The cart at duralexusa.com is still held at $28.36, and nothing was charged.","code":"test_card_missing","conversation_id":"conv_2186d756abba3ae376fc6446"}
```

Make a Vault link for the same shopper and open it. The Vault asks for a code to connect the shopper, and in the sandbox that code is always `111111`. Save any of [Stripe's published test cards](https://docs.stripe.com/testing). Then send the same confirm again while the store still keeps the cart.

> [tab] SDK
>
> The buy tool's call fails with the refusal's message, which your model reads. The error's `cause` holds the `AgentcardApiError`, whose `code` is `test_card_missing`. Make the Vault link with `mintVaultLink()`:
>
> ```ts sandbox.ts theme={null}
> const link = await agentcard.mintVaultLink({ externalUserId: shopper.id });
> // link.url: the Vault page where the test shopper saves a card
> ```

> [tab] MCP
>
> The refusal arrives in the tool result as `{ "error": { "code", "message", "retryable" } }`, with `code` set to `test_card_missing`. No MCP tool makes a Vault link on request. Make one with the API's `POST /api/v2/vault_sessions`, as the API tab shows, with your `shopper_id` as `external_user_id`. Your client ID and secret get the access token for it.

> [tab] API
>
> Create a Vault link for the shopper:
>
> ```bash theme={null}
> curl https://api.agentcard.sh/api/v2/vault_sessions \
>   -H "Authorization: Bearer $AGENTCARD_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{ "external_user_id": "docs-guide-sandbox-1" }'
> ```
>
> ```json theme={null}
> {
>   "object": "vault_session",
>   "id": "vs_e2cbe34138b910293acb515e",
>   "external_user_id": "docs-guide-sandbox-1",
>   "url": "https://vault.agentcard.sh/v?vs=vs_e2cbe34138b910293acb515e...",
>   "expires_at": "2026-11-20T21:05:12.107Z",
>   "test_mode": true,
>   ...
> }
> ```
>
> Open `url`. [Create a vault session](https://docs.agentcard.com/api-reference/vault/sessions-create.md) documents the call in full.

## Approve a test payment

With a test card saved, the confirm asks the shopper to approve the payment on the Vault's approval page. Open the page and approve. Then send the same confirm again, and the answer says the approval went through and the card was never sent to the store. No order exists and nothing is charged.

> [tab] SDK
>
> The buy tool's answer reads `status: 'approval_sent'` and hands `sendLink` a link whose `kind` is `approval`. After the shopper approves, the next answer carries `decline_code: 'sandbox_mode'`.

> [tab] MCP
>
> The `buy` result reads `status: "approval_sent"`, and `links` holds a link whose `kind` is `approval`. After the shopper approves, the next result carries `decline_code: "sandbox_mode"`.

> [tab] API
>
> The answer carries `approval_url`, the page where the shopper approves:
>
> ```json theme={null}
> {
>   "status": "declined",
>   "reply": "Approve the payment on your device: https://vault.agentcard.sh/... Your purchase is in sandbox mode, so nothing is charged and no order is placed.",
>   "decline_code": "vault_approval_required",
>   "approval_url": "https://vault.agentcard.sh/...",
>   "approval_expires_at": "..."
> }
> ```
>
> After the shopper approves, the same confirm answers:
>
> ```json theme={null}
> {
>   "status": "approved_not_charged",
>   "reply": "Approved. Not charged: this is a sandbox purchase, so the card was never sent to the store.",
>   "decline_code": "sandbox_mode",
>   "payment_source": { "source": "vault", "brand": null, "last4": null },
>   "authorization_id": "..."
> }
> ```
>
> `approved_not_charged` means your run worked at a store's own checkout.

## Choose how a confirm ends

Add `sandbox_outcome` to a sandbox confirm to see how your app handles each way a purchase can end, before any live order. Set it to `placed`, `failed` or `delayed`:

```bash theme={null}
curl https://api.agentcard.sh/buy \
  -H "Authorization: Bearer $AGENTCARD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "conv_ddaaf96c052893b13209e6c9",
    "external_user_id": "docs-guide-refusals-1",
    "confirm": "55952914e74b3539",
    "sandbox_outcome": "placed"
  }'
```

The confirm ends the purchase at once, with no approval link for the shopper. No store receives the order, no card is made and nothing is charged. Your server still gets the order events a live order sends, marked `livemode: false`.

| `sandbox_outcome` | What the confirm answers | What your server gets |
| - | - | - |
| `placed` | `status: "order_placed"`, with an `order_id` that starts with `sbx_`. | `order.placed` with the cart's lines. |
| `failed` | `status: "declined"` with `decline_code: "items_unavailable"`, and a `reply` that names the cart's lines. | `order.failed` with `charge_status: "none"`. |
| `delayed` | `status: "declined"` with `decline_code: "order_placing"`, `charge_status: "none"` and no next step. | `order.placed` between 30 and 90 seconds later. |

A `delayed` confirm reads `declined` only because no order exists yet. Don't ask the shopper again: `order.placed` follows.

A placed order reads back like a live one, in the conversation's `orders` and from `GET /buy/orders/{order_id}`, as [Read where an order is](https://docs.agentcard.com/commerce-sdk/guides/approving-a-purchase.md#read-where-an-order-is) shows.

A delayed order answers with `reply` set to:

```text theme={null}
This simulated sandbox order is being placed. order.placed reaches your webhook in about a minute. Nothing was charged, and no store received it.
```

Wait for `order.placed`, then read the conversation again: the order is there.

A confirm with `sandbox_outcome` is refused in three cases, and nothing is charged in any of them:

| `code` | Why | What to do next |
| - | - | - |
| `sandbox_only` | The request came with live credentials. A live confirm always places a real order. | Confirm without `sandbox_outcome`, or switch to sandbox credentials. |
| `sandbox_outcome_unsupported` | The confirm names several carts, or a cart at a store's own checkout page. | Confirm one cart at a time, or confirm without `sandbox_outcome`. |
| `sandbox_outcome_unavailable` | Agentcard has turned the option off for your company. | Confirm without `sandbox_outcome`. |

A request with live credentials is refused like this:

```text theme={null}
403
{"error":"sandbox_only","code":"sandbox_only","message":"sandbox_outcome works only in sandbox mode, and this app is in production mode. Confirm without it to place a live order; nothing was charged."}
```

A confirm that names several carts is refused:

```bash theme={null}
curl https://api.agentcard.sh/buy \
  -H "Authorization: Bearer $AGENTCARD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "conv_ddaaf96c052893b13209e6c9",
    "external_user_id": "docs-guide-refusals-1",
    "confirm": ["55952914e74b3539", "ad9cdf1a1a5037ab"],
    "sandbox_outcome": "placed"
  }'
```

```text theme={null}
400
{"error":"sandbox_outcome covers one cart: confirm a single cart's hash, or true, with it. Nothing was charged.","code":"sandbox_outcome_unsupported"}
```

A confirm of one cart at a store's own checkout page is refused with the same code:

```text theme={null}
400
{"error":"sandbox_outcome doesn't cover a cart checked out on the store's own site yet. Confirm without it; nothing was charged.","code":"sandbox_outcome_unsupported","conversation_id":"conv_2186d756abba3ae376fc6446"}
```

Where Agentcard has turned the option off for your company, the same confirm is refused before any cart is read:

```text theme={null}
400
{"error":"sandbox_outcome_unavailable","code":"sandbox_outcome_unavailable","message":"sandbox_outcome isn't available for this app yet. Confirm without it; nothing was charged."}
```

## Know what differs from live

| In the sandbox | In live mode |
| - | - |
| Searches, carts and totals come from the real stores. | The same. |
| A cart at a store's own checkout is read up to the store's final total. | The same, and Agentcard then pays. |
| A confirm ends with `decline_code: sandbox_mode`, unless it names a `sandbox_outcome`. | A confirm places the order, and `status` reads `order_placed`. |
| A restaurant table is refused with `decline_code: sandbox_unavailable`, so no real table is held. | The table is booked. |
| Without `sandbox_outcome`, no order exists and your server gets no order events, the requests Agentcard sends it as an order is placed or fails. With it, your server gets the events in [Choose how a confirm ends](#choose-how-a-confirm-ends). | Each order sends `order.placed` with its `order_id`. |
| The Vault's code is always `111111`, and the shopper saves a Stripe test card. | The shopper gets a real code and saves a real card. |
| Stripe Link pays nothing: every Link confirm is refused with `link_payment_unavailable`. | Link pays where [Pay with Stripe Link](https://docs.agentcard.com/purchase-api/link-seal.md) says it can. |
| Test shoppers belong to the sandbox only. | Live shoppers are separate, so each one starts again. |

## Go live

Swap your sandbox client ID and secret for live ones, and keep every call the same. Your test shoppers do not carry over: each live shopper starts with their first request, and the first confirm they approve places a real order and charges their card. Test the full flow with your own card first.

Before your first live order, choose Go live in the dashboard's banner, and choose how to pay Agentcard's fee of 1% of each live purchase. [Read a refusal](https://docs.agentcard.com/opencommerce/guides/reading-a-refusal.md) lists every error you can meet on the way.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.