> ## 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. # Integration checklist > What your integration stores, compares and does at each step of a purchase. A failed checkout must not block the buyer or pay twice. Use this checklist when you build or review an integration that buys with Sapiom. Each item links to the page that explains it. ## Store for each purchase | Value | Why | | - | - | | Transaction `id` | Every later step uses it. | | Your `Idempotency-Key` | To resume an unanswered create with the identical request. See [Keep the same idempotency key](https://docs.sapiom.ai/transactions/authorize.md#keep-the-same-idempotency-key). | | Last `version` | To wait for the next change with `since`. | | Last `nextAction` | Your agent acts on it. Do not keep a separate payment state that can disagree with it. | ## Get the approval when your browser worker is ready The placeholder card works for about one hour after the buyer approves. Start the browser worker first. Then send the buyer the approval link. See [Get the placeholder card](https://docs.sapiom.ai/transactions/browser-pay#get-the-placeholder-card). ## Compare the right values | Compare | With | Do not compare | | - | - | - | | The origin of the page that has the card form | `merchant.origin` | `continueUrl` with `merchant.origin`. The host of `continueUrl` can be different. | | The total on the page, as the page shows it | The total that the buyer approved | Minor units from MCP `totals` with the page text. Convert them first. | ## Know if the card was sent Only the transaction tells you if the card was sent. Read it after any failure. | The transaction reads | The card was sent? | Do this | | - | - | - | | `payment_ready` | No | Pay with this transaction. If the browser session ended, start a new one. See [If the browser session ends before you submit](https://docs.sapiom.ai/transactions/browser-pay#if-the-browser-session-ends-before-you-submit). | | `wait` | Follow `reason` | Read again after `retryAfterSeconds`. | | `blocked` with `reason: payment_ended` | No | Cancel the transaction. Create a new transaction if the buyer still wants it. | | `payment_submitted` | Possibly | Do not pay again. [Confirm the order](https://docs.sapiom.ai/transactions/confirm-and-recover.md). | | `none`, with `order.outcome: confirmed` | Yes | The UCP order is complete. [Show the order confirmation](https://docs.sapiom.ai/transactions/confirm-and-recover.md#show-the-order-confirmation). | | `closed` | See `message` | Follow `message`. | Do not mark a purchase as sent in your own records before the transaction reads `payment_submitted` or `order.outcome: confirmed`. A read shows the current state only. A UCP order can be confirmed before your agent sees `payment_submitted`. A failure before your worker submits the form does not send the card. Do not record it as uncertain. ## Fill the card with code Fill the card fields with your browser driver. Keep placeholder values out of your AI model's prompt and out of logs. See [Fill the card fields](https://docs.sapiom.ai/transactions/browser-pay#fill-the-card-fields). ## Recover | Situation | Do this | | - | - | | The create request got no answer | Send the identical request with the same key. | | The browser session ended before the card form was submitted | Read the transaction and follow the table above. | | The placeholder expired | The transaction reads `blocked` with `reason: payment_ended`. Cancel it and create a new one. | | A UCP purchase reads `payment_submitted`, and the order is not confirmed | Do not buy again. Refresh the checkout and read the transaction. See [Show the order confirmation](https://docs.sapiom.ai/transactions/confirm-and-recover.md#show-the-order-confirmation). If the order does not confirm, tell the buyer to check with the merchant. | | A browser purchase reads `payment_submitted` | Do not buy again. The merchant's page is the only confirmation. Tell the buyer what the page showed. | All other cases are in [Recover without buying twice](https://docs.sapiom.ai/transactions/confirm-and-recover.md#recover-without-buying-twice). ## Test before you go live Make the purchases in [Sandbox](https://docs.sapiom.ai/sandbox.md) with the test card. Test these failures too: * Stop the browser session after the approval and before you submit. Your agent must read `payment_ready` and pay in a new session. * Wait more than one hour after the approval. Your agent must read `payment_ended`, cancel, and create a new transaction. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.