> ## 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 card data is handled

> Who sees a saved card, how the real card reaches the merchant, and what that means for your PCI scope.

Card numbers never touch your systems. Buyers type them into fields hosted by a PCI-compliant card vault, and your browser worker pays with a placeholder card.

## Who sees what

| Party | Sees |
| - | - |
| Your backend, agent and browser worker | The card's brand, last four digits and expiry. During a transaction, a placeholder card. |
| Sapiom | A reference to the vaulted card, its brand, last four digits and expiry, and the buyer's email. Never the card number. |
| The card vault | The card number and expiry, encrypted. |
| The merchant's payment processor | The real card, at payment. |

## Saving a card

* The buyer enters the card on a [Sapiom-hosted setup page](https://docs.sapiom.ai/cards/vault-a-card.md). Its card fields belong to the vault, so the number goes straight there.
* Sapiom records the buyer's consent, with the exact terms they agreed to.
* There's no API for sending a card number to Sapiom.

## Paying with a placeholder

* A placeholder is a random card number, expiry and CVC in the card's brand. It works for one transaction at one merchant and expires with it.
* [Browser Pay](https://docs.sapiom.ai/transactions/browser-pay.md) sends the checkout's payment request to Sapiom's relay. The relay checks the merchant, the total and the authorization. Then the vault puts the real card into the request and sends it to the processor. Sapiom's servers never see the real number.
* Each placeholder is relayed at most once. Without the relay, it's just a random card number.

## Your PCI scope

Card numbers and security codes never enter your systems. Your assessor confirms which PCI DSS requirements still apply to you.


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