> ## 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 is for platforms whose agent shops for many users. Each user has their own Sapiom user key and saved cards.
> Use the user's key for every call made on that user's behalf. Never use one user'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 environment with its own users and cards, at the same addresses. Use test card numbers only there.
> Never ask a user for a card number, expiry date or CVV in chat. Users 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. Send each one only to the person `nextAction.actor` names.
> 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.

# How an agent pays

> Three parts of your product work together on every purchase.

An agent that buys with Sapiom has three parts. Each holds a key and does one job.

| Part | Holds | Does |
| - | - | - |
| Your backend | Your platform key, and a user key for each user | Creates Sapiom users and keys, and gives the agent one user's key per session |
| Your agent | One user's key | Asks to buy, follows `nextAction`, and sends the user any link they need to act on |
| Your payment code | The same user key | Runs beside the agent's browser, attaches Sapiom Browser Pay, fills in the placeholder card and submits checkout |

A purchase moves through them in order:

1. Your agent creates the purchase, with the [MCP tools](https://docs.sapiom.ai/api-reference/mcp-tools.md) or the [REST API](https://docs.sapiom.ai/transactions/make-a-purchase).
2. Sapiom checks the budget and your spending limits. Inside the budget, nothing is asked.
3. At `payment_ready`, your payment code takes over the agent's [browser](https://docs.sapiom.ai/transactions/make-a-purchase#pay-in-the-browser) and pays.
4. Sapiom Browser Pay swaps in the real card on its way to the merchant.
5. Your agent [confirms the order](https://docs.sapiom.ai/transactions/confirm-and-recover.md) and tells the user.

## Keep the placeholder card out of the model

The placeholder card works only for this purchase, but it's still card data. Don't put it in your agent's prompt or logs. At `payment_ready`, the MCP transaction tools return `payment.placeholder` to whoever called them, so give your agent a tool that runs your payment code, and let that code read the placeholder itself.

```typescript theme={null}
// A tool your agent calls at payment_ready. It returns only the outcome.
async function payAtCheckout(transactionId: string) {
  const placeholder = await readPlaceholder(transactionId); // GET /v1/transactions/{id}
  const result = await payInBrowser(placeholder);           // Sapiom Browser Pay and fillCard
  return { paid: result.ok };
}
```

See [Make a purchase](https://docs.sapiom.ai/transactions/make-a-purchase#pay-in-the-browser) for the payment code.


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