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

# Webhooks

> Get notified when a buyer saves a card or a transaction needs attention, instead of polling.

**Webhooks are in early access.** [Request access](https://docs.sapiom.ai/request-access.md) to try them. Until you have access, read the setup link (`GET /v1/payment-cards/setup-links/{linkId}`) or the transaction (`sapiom_get_transaction`) to check for changes.

You'll register one HTTPS endpoint with your platform key, and it will receive events for all your buyers. Each event names the buyer and the card or transaction it's about.

| Event | When |
| - | - |
| `setup_link.completed` | A buyer saved a card. |
| `setup_link.expired` | A setup link expired, or the buyer canceled. |
| `card.removed` | A card was removed. |
| `transaction.action_required` | The buyer needs to act, such as confirming their security code. Includes the link. |
| `transaction.payment_ready` | Your browser worker can finish checkout. |
| `transaction.payment_submitted` | The card was sent to the merchant's payment processor. |
| `transaction.order_confirmed` | The merchant confirmed the order. |
| `transaction.order_unknown` | The order's outcome is unknown. [Reconcile it](https://docs.sapiom.ai/transactions/confirm-and-recover.md) before doing anything else. |
| `transaction.closed` | The transaction ended without an order. Includes the reason. |

Deliveries will be signed and retried, and can arrive more than once or out of order. Treat each one as a signal, and read the card or transaction for its current state.


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