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

# How Sapiom Pay works

> Who does what in a Sapiom Pay transaction, why Sapiom needs checkout details before releasing a card, and how the real card reaches checkout.

Six parties take part in a transaction. The real card number only ever passes between Sapiom and the merchant's payment processor.

## Who does what

| Party | Role |
| - | - |
| Your backend | Creates a buyer and buyer key for each user, stores the keys, and refreshes checkouts when asked. |
| Your agent | Shops for one buyer at a time, using that buyer's key. |
| Buyer | Your user. Saves a card once, then approves each transaction. |
| Browser session | Your code that runs the merchant's checkout in a browser, with [Browser Pay](https://docs.sapiom.ai/transactions/browser-pay.md) attached. |
| Sapiom | Stores each buyer's cards, checks each transaction, and sends the real card to checkout. |
| Merchant | Sets prices and totals, and owns the order. |

Each buyer's cards and transactions are visible only with that buyer's key.

## A transaction

1. **Request.** Your agent sends the merchant's checkout and the buyer's card ID. Sapiom opens the checkout with the merchant.
2. **Check.** Sapiom checks the transaction against your spending limits and any approval rules.
3. **Approve.** The buyer approves on a hosted page that shows the merchant, items and total.
4. **Pay.** A browser session fills checkout with a placeholder, which is relayed and replaced securely through Sapiom.
5. **Confirm the order.** Sapiom reports the order as `confirmed` once the merchant says checkout is complete.

## Why Sapiom needs checkout details first

Sapiom releases a card only for a specific checkout. Before paying, it knows the merchant, items, total and currency. That lets Sapiom:

* check the transaction against your limits
* show the buyer exactly what they are approving
* tie the placeholder card to that one transaction
* return the decision and its reasons with each transaction

Today, checkout details come from UCP checkouts. More checkout types are coming.


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