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

## The integration in brief

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.** Your agent sends the merchant's checkout with that user's key.
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.md) 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 from merchants that support the Universal Commerce Protocol (UCP), a standard for letting agents check out. More checkout types are coming soon.

## Start building

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

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

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

> **[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.