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

# Quickstart: set up your first buyer

> Create a buyer for a test user, save a card for them, and connect your agent as that buyer. No transaction is made.

In a few minutes you will set up one buyer end to end: create the buyer, save a card for them, and connect an agent that acts as them. No transaction is made.

The setup steps, API URLs and MCP URL are the same in sandbox and production. Your key selects the environment. Sandbox buyers, keys and cards are separate from production.

**You need:**

* A platform key that can create buyers (`org.tenants.write`). [Create one in the dashboard](https://docs.sapiom.ai/buyers/platform-keys.md). For a test run, use a [sandbox platform key](https://docs.sapiom.ai/sandbox.md#get-a-key).
* An agent client that can connect to remote MCP servers. The examples use Claude Code.

Set `SAPIOM_PLATFORM_KEY` to your saved platform key:

```bash theme={null}
# Replace the example with your saved platform key.
export SAPIOM_PLATFORM_KEY="sk_test_..." # Sandbox
# export SAPIOM_PLATFORM_KEY="sk_live_..." # Production
```

**1. Create a buyer**

A buyer represents one of your users. Use your own ID for that user as `externalId`:

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

Save the `id` from the response as `BUYER_ID`.

**2. Create a key for the buyer**

```bash theme={null}
curl "https://api.sapiom.ai/v1/tenants/$BUYER_ID/api-keys" \
  -H "x-api-key: $SAPIOM_PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"test-user-1"}'
```

Save `plainKey` from the response as `SAPIOM_BUYER_KEY`. It is shown only once.

```bash theme={null}
# Sandbox: sk_test_...; production: sk_live_...
# Replace the example with plainKey from this response.
export SAPIOM_BUYER_KEY="<returned plainKey>"
```

**3. Save a card for the buyer**

Create a setup link with the buyer's key:

```bash theme={null}
curl https://api.sapiom.ai/v1/payment-cards/setup-links \
  -H "x-api-key: $SAPIOM_BUYER_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

Open the `url` from the response. In sandbox, use an approved [test card](https://docs.sapiom.ai/sandbox.md#save-a-test-card). In production, send the link to your user to save their card.

**4. Connect your agent as the buyer**

```bash theme={null}
# Use the buyer key for the environment you selected.
claude mcp add --transport http sapiom https://api.sapiom.ai/v1/mcp/pay \
  --header "x-api-key: $SAPIOM_BUYER_KEY"
```

Ask your agent: **"List my Sapiom payment methods."** It shows the card you just saved, with its brand and last four digits.

**5. Check a merchant**

For a sandbox check, use `sapiom-test-store.myshopify.com` as the store's domain.

Ask your agent: **"Can Sapiom buy from shop.example?"**, with a real store's domain. The answer is `supported`, `unsupported` or `unknown`. `supported` means the store offers UCP checkout. Otherwise your agent can use browser checkout, if [Browser Pay can pay](https://docs.sapiom.ai/transactions/browser-pay#which-checkouts-browser-pay-can-pay) it.

You now have a buyer with a saved card and an agent that acts for that buyer. In production, your agent switches keys for each user it serves. See [Connect your agent](https://docs.sapiom.ai/buyers/connect-agent.md).

## Next steps

> [card] [Authorize a transaction](https://docs.sapiom.ai/transactions/authorize.md)
>
> Send a merchant checkout and get the buyer's approval.

> [card] [Manage buyers](https://docs.sapiom.ai/buyers/create-buyers.md)
>
> Set up buyers for real users in production.


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