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

# Sapiom Pay for agents

> Give every user of your agent their own card vault. Sapiom authorizes each transaction and fills the card into checkout without the agent seeing it.

Sapiom Pay enables your AI agent to buy from merchants with a buyer's securely vaulted card. The buyer adds their card once on a hosted page. For each transaction, Sapiom checks what is being bought and who it is from, asks the buyer to confirm, and then fills the card into checkout. Your agent never sees the real card details.

To try the tools as one of your buyers, create a buyer key ([quickstart](https://docs.sapiom.ai/quickstart.md) steps 1 and 2), then paste this into an agent that supports remote MCP servers:

```text theme={null}
Connect to the Sapiom MCP server at https://api.sapiom.ai/v1/mcp/pay over Streamable HTTP,
sending the header "x-api-key: <SAPIOM_BUYER_KEY>". Then list this buyer's Sapiom
payment methods to confirm the connection works, or create a setup link if there are none.
```

## Integrate

1. **Create a buyer for each user.** Your backend creates a buyer and its key.
2. **Save their card.** The user adds their card once, on a hosted page that shows your brand.
3. **Request a transaction.** With that user's key, you send the merchant's UCP checkout or, for any other merchant, the total your agent read from its checkout page.
4. **The user approves.** They approve on a hosted page that shows what they are buying.
5. **Pay.** Your browser worker fills checkout with a placeholder card, and the Sapiom [Browser Pay](https://docs.sapiom.ai/transactions/browser-pay) SDK swaps in the real card.
6. **Confirm the order.** Tell the user once the merchant confirms it.

[How it works](https://docs.sapiom.ai/how-it-works.md) explains each step.

## What works today

Sapiom Pay buys at any checkout [Browser Pay can pay](https://docs.sapiom.ai/transactions/browser-pay#which-checkouts-browser-pay-can-pay). The merchant doesn't need the Universal Commerce Protocol (UCP). Outside UCP, your agent states the items and total, and the merchant's page is the only order confirmation. See [Checkout paths](https://docs.sapiom.ai/how-it-works.md#checkout-paths).

## Start building

> [card] [Quickstart](https://docs.sapiom.ai/quickstart.md)
>
> Create a buyer, save a card and connect your agent.

> [card] [How it works](https://docs.sapiom.ai/how-it-works.md)
>
> Who does what in a transaction.

> [card] [Authorize a transaction](https://docs.sapiom.ai/transactions/authorize.md)
>
> Turn a merchant checkout into an approved payment.

> [card] [API reference](https://docs.sapiom.ai/api-reference/overview.md)
>
> REST endpoints, MCP tools and the Browser Pay SDK.


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