Sapiom

Agent Instructions

Sapiom Pay is for platforms whose agent shops for many users. Each user has their own Sapiom user key and saved cards. Use the user's key for every call made on that user's behalf. Never use one user'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 environment with its own users and cards, at the same addresses. Use test card numbers only there. Never ask a user for a card number, expiry date or CVV in chat. Users 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. Send each one only to the person nextAction.actor names. 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.

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 user's securely vaulted card. The user adds their card once on a hosted page. For each transaction, Sapiom checks what is being bought and who it is from, asks the user 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 users, create a user key (quickstart steps 1 and 2), then paste this into an agent that supports remote MCP servers:

Connect to the Sapiom MCP server at https://api.sapiom.ai/v1/mcp/pay over Streamable HTTP,
sending the header "x-api-key: <SAPIOM_USER_KEY>". Then list this user's saved Sapiom
cards to confirm the connection works, or create a setup link if there are none.

Integrate

1. Create a Sapiom user for each of your users. Your backend creates the user and its user key.
2. Save their card. The user adds their card once, on a hosted page that shows your brand.
3. Request a transaction. With that user's key, you send the merchant's UCP checkout or, for any other merchant, the total your agent read from its checkout page.
4. The user confirms the purchase. They enter their security code 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 SDK swaps in the real card.
6. Confirm the order. Tell the user once the merchant confirms it.

How it works explains each step.

What works today

Sapiom Pay buys at any checkout Browser Pay can pay. The merchant doesn't need the Universal Commerce Protocol (UCP). Outside UCP, your agent states the items and total, and the merchant's page is the only order confirmation. See Checkout paths.

Start building

[card] Quickstart

Create a user, save a card and connect your agent.

[card] How it works

Who does what in a transaction.

[card] Authorize a transaction

Turn a merchant checkout into an approved payment.

[card] API reference

REST endpoints, MCP tools and the Browser Pay SDK.

This documentation is built and hosted on Mintlify, a developer documentation platform.