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

> ## Agent Instructions
> Sapiom Pay is for platforms whose agent shops for many end users. Each end user is a buyer with their own Sapiom key and saved cards.
> Use the buyer's key for every call made on that buyer's behalf. Never use one buyer's key for another user, and never give the agent the platform key.
> Backends call the REST API at https://api.sapiom.ai/v1. Agents can also call the hosted MCP tools at https://api.sapiom.ai/v1/mcp/pay. Both take the key in an x-api-key header.
> Keys that start with sk_test_ reach the sandbox, a separate test environment with its own buyers and cards, at the same addresses. Use test card numbers only there.
> Never ask a buyer for a card number, expiry date or CVV in chat. Buyers enter card details only on Sapiom's hosted pages.
> Check the merchant before buying. Use purchase.type ucp_checkout only when the merchant check returns supported. Otherwise use browser_checkout.
> Follow the nextAction in each transaction result. Action links are secrets for the intended buyer only.
> Use one idempotency key per transaction. Resume an unanswered create with the same request and key. If a UCP update or cancellation is uncertain, stop and hand off to a person. If a browser cancellation is uncertain, read the transaction and resend the same cancellation, with the same key, only if it is not closed. Never start a new transaction to escape an uncertain outcome.
> For a ucp_checkout purchase, report an order as placed only when order.outcome is confirmed; if it is unknown, stop and hand off to a person. A browser_checkout purchase has no order confirmation (order is null): confirm the order on the merchant's page.

# Test your Sapiom Pay integration in the sandbox

> The Sapiom sandbox enables you to test a Sapiom Pay integration using test keys, test cards, and a test store. The API is the same as in production.

## Get access

Sapiom Pay is still in early access (EA), so the sandbox is only enabled per organization. After you sign up at [app.sapiom.ai/signup](https://app.sapiom.ai/signup), reach out to your Sapiom contact, and we'll enable it for your org.

## Enter Sandbox 🤘

From [app.sapiom.ai](https://app.sapiom.ai), open the account menu at the bottom of the sidebar and click **Open sandbox**. This will take you to the sandbox state. *Note: Since we're still in early access, there's no direct indication, but if you click the account menu again, the open sandbox icon will be gone.*

![The Sapiom account menu with Settings, Dark mode, Help and Open sandbox, with Open sandbox circled](https://mintcdn.com/sapiom-1f975ca2/q6wuBi6kpSnAblqN/images/open-sandbox-menu.png?fit=max\&auto=format\&n=q6wuBi6kpSnAblqN\&q=85\&s=238e07a2ac9150dcbe6ebbb300ce89ad)

Open sandbox in the account menu

## Get a Key

From the sandbox, open [Developers → API keys](https://app.sapiom.ai/dashboard/developers/api-keys) and then click **Create key**. Give it a name, and click **Create**. Copy the key (it only appears once) and then save it securely.

Below, we call it `SAPIOM_SANDBOX_PLATFORM_KEY`. You can create as many of these as you would like.

## Create a sandbox buyer

The sandbox and production platforms have the same entry point, so the base URLs are all the same. Simply use the SK test key instead of your production key. Any Sapiom links returned in responses will be for sandbox pages as well.

> [tab] REST API
>
> ```bash theme={null}
> curl https://api.sapiom.ai/v1/tenants \
>   -H "x-api-key: $SAPIOM_SANDBOX_PLATFORM_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"name":"Test user","externalId":"test-user-1"}'
> ```

> [tab] MCP
>
> Connect your agent with a sandbox buyer key:
>
> ```bash theme={null}
> claude mcp add --transport http sapiom https://api.sapiom.ai/v1/mcp/pay \
>   --header "x-api-key: $SAPIOM_SANDBOX_BUYER_KEY"
> ```

> [tab] Browser Pay SDK
>
> Pass the sandbox buyer key as `apiKey`. Keep `baseUrl` as `https://api.sapiom.ai`.
>
> ```ts theme={null}
> import { httpPaymentRelay } from "@sapiom/browser-pay";
>
> const relay = httpPaymentRelay({
>   baseUrl: "https://api.sapiom.ai",
>   apiKey: process.env.SAPIOM_SANDBOX_BUYER_KEY!, // sk_test_...
>   transactionId,
> });
> ```

The response is the new sandbox buyer. To get its scoped buyer key, see [Manage buyers](https://docs.sapiom.ai/buyers/create-buyers.md).

## Save a test card

Create a [setup link](https://docs.sapiom.ai/cards/vault-a-card.md) with a sandbox buyer key, open it, and save this test card:

| Field | Value |
| - | - |
| Card number | `4242 4242 4242 4242` |
| Expiry | Any future date |
| Security code | `123` |

On any security code approval page, also use `123` as the security code.

## Make a test purchase

Buy from Sapiom's test store, `https://sapiom-test-store.myshopify.com`. It supports UCP checkout, so checking it with a sandbox buyer key returns `supported`:

```bash theme={null}
curl -G https://api.sapiom.ai/v1/transaction-compatibility \
  -H "x-api-key: $SAPIOM_SANDBOX_BUYER_KEY" \
  -d domain=sapiom-test-store.myshopify.com
```

Then follow [Authorize a transaction](https://docs.sapiom.ai/transactions/authorize.md) with a `ucp_checkout` purchase and `"merchant": { "origin": "https://sapiom-test-store.myshopify.com" }`. The order is placed with the store's test payments, so no money moves.


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