> ## 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.
> Agents call the hosted MCP tools at https://api.sapiom.ai/v1/mcp. Backends call the REST API at https://api.sapiom.ai/v1. Both take the key in an x-api-key header.
> Never ask a buyer for a card number, expiry date or CVV in chat. Buyers enter card details only on Sapiom's hosted pages.
> Follow the nextAction in each transaction result. Action links are secrets for the intended buyer only.
> Use one idempotencyKey per transaction. After a timeout, retry with the same key. Never start a new transaction to escape an uncertain outcome.
> Report an order as placed only when order.outcome is confirmed. If it is unknown, stop and hand off to a person.

# Sapiom Pay API overview

> Base URLs, keys, permissions and idempotency for the Sapiom Pay REST API, MCP tools and Browser Pay SDK.

Sapiom Pay has three surfaces. They share the same keys and data.

| Surface | Used by | Endpoint | Reference |
| - | - | - | - |
| REST API | Your backend | `https://api.sapiom.ai/v1` | [REST endpoints](#rest-endpoints) |
| MCP tools | Your agent | `https://api.sapiom.ai/v1/mcp` | [MCP tools](https://docs.sapiom.ai/api-reference/mcp-tools.md) |
| Browser Pay SDK | Your browser worker | `npm install @sapiom/browser-pay` | [Browser Pay SDK](https://docs.sapiom.ai/api-reference/browser-pay-sdk.md) |

## Authentication

Send a key in the `x-api-key` header on every REST request and MCP connection:

```bash theme={null}
curl https://api.sapiom.ai/v1/payment-cards -H "x-api-key: $SAPIOM_BUYER_KEY"
```

| Key | Where it comes from | Use it for |
| - | - | - |
| Platform key | [Request access](https://docs.sapiom.ai/request-access.md) | Creating buyers and buyer keys. Keep it in your backend. |
| Buyer key | `POST /v1/tenants/{tenantId}/api-keys` | Everything you do for one user: cards, transactions and Browser Pay |

Every request made with a buyer key is limited to that buyer's cards and transactions. Keys are shown once, as `plainKey` in the creation response.

Branding endpoints are the exception. They need a signed-in dashboard user. See [Brand hosted pages](https://docs.sapiom.ai/cards/brand-hosted-pages.md).

## Permissions

| Permission | Allows | Held by |
| - | - | - |
| `org.tenants.write` | Create buyers and buyer keys | Platform key |
| `org.transactions.write` | Save and remove cards, request, update and cancel transactions | Buyer key |
| `org.transactions.read` | Read cards, setup links, merchants and transactions | Buyer key |

## Retries and idempotency

Transactions, updates and cancellations each take an `idempotencyKey`, so you can retry safely without buying twice. See [Keep the same idempotency key](https://docs.sapiom.ai/transactions/authorize.md#keep-the-same-idempotency-key). Setup links take no key; each call creates a new link.

## REST endpoints

Each group has a page per endpoint, with its fields and examples.

| Group | Endpoints | Key |
| - | - | - |
| [Buyers](https://docs.sapiom.ai/api-reference/buyers/create-a-buyer.md) | Create, list and delete buyers, and create buyer keys | Platform key |
| [Cards](https://docs.sapiom.ai/api-reference/cards/create-a-setup-link.md) | Setup links, and list, read, set default and remove cards | Buyer key |
| [Spending limits](https://docs.sapiom.ai/api-reference/spending-limits/get-spending-limits.md) | Read and set a card's spending limits | Platform key |
| [Merchants](https://docs.sapiom.ai/api-reference/merchants/check-a-merchant.md) | Check whether Sapiom can buy from a merchant | Buyer key |
| [Transactions](https://docs.sapiom.ai/api-reference/transactions/create-a-transaction.md) | Create a transaction, then open, read, replace, cancel and refresh its checkout | Buyer key |
| [Browser checkout](https://docs.sapiom.ai/api-reference/browser-checkout/list-placeholder-cards.md) | Placeholder cards, relay profiles and the relay Browser Pay uses | Buyer key |


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