Sapiom
Satu kunci API memberikan agen akses ke 80+ alat: pencarian web, pencarian mendalam, otomatisasi peramban, tangkapan layar, 400+ model LLM, pembuatan gambar, teks-ke-ucapan, efek suara, dan verifikasi telepon. Bayar sesuai pemakaian dengan pengelolaan pengeluaran yang terintegrasi.
Dokumentasi
Agent Instructions
Sapiom 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.actornames. 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.
Agent purchases with Sapiom
Give your agent the ability to securely make purchases on behalf of your users.
Sapiom enables your agents to autonomously make purchases for your users. Agents can pretty much do everything they need on the web, but financial infrastructure is still largely walled off. Sapiom is your gate through the wall: your agent can prompt your users to securely add a card and a budget for the next 30 days. Within that budget, your agent will be able to make purchases on its own.
The card number is vaulted, and neither you nor your agent nor Sapiom ever sees it. Sapiom strictly guards cardholder information. The basic flow is that your agent asks to buy, Sapiom checks the budget and spending limits, and then Sapiom executes the payment.
Inside of one high-level flow, there are many types of online payment variations: UCP and other protocols, multi-currency, and many combinations between merchant payment processors and user cards. Sapiom provides a next action at each point of the payment route to handle every error or edge case.
How it works
Once The user adds a card and sets a budget for the next 30 days. Then, for each purchase:
-
1
Request Your agent sends what it's buying. `transactionId` -
2
Check Budget and your spending limits. Without a budget, the user enters their security code. ↻ Repeats: wait, approval `nextAction` -
3
Pay Sapiom Browser Pay swaps the placeholder for the real card. `payment_ready` -
4
Completed Sapiom sent the card. Confirm the order with the merchant. `completed`
Cancel until your agent pays
POST …/cancel
- Request. Your agent sends the merchant, the items and the total, with the user's key.
- Check. Sapiom checks the purchase against the user's budget and your spending limits. Without a budget, the user enters their security code on a hosted page. Your agent follows
nextActionuntil the purchase ispayment_ready. - Pay. Your agent fills checkout with a placeholder card. Sapiom sends the real card to the merchant's payment processor.
- Completed. The purchase reads
completed. Confirm the order with the merchant.
Until your agent pays, it can cancel the purchase.
Who is involved
| Party | Role |
|---|---|
| You | Create a Sapiom user and a user key for each of your users, and keep the keys on your backend. |
| Your agent | Buys for one user at a time, with that user's key. |
| The user | Adds a card and sets a budget on pages that show your brand. |
| The merchant | Sets the prices and the total, and owns the order. |
| Sapiom | Keeps each user's cards, checks each purchase, and sends the real card to checkout. |
Each user's cards and purchases are visible only with that user's key.
Start here
[card] First purchase
Make one purchase end to end in the sandbox.
[card] Sandbox
Test cards, a test merchant, and no real money.
[card] Set up your platform
Get your platform key, then a user and a user key for each of your users.
[card] Card data and security
Where the card number goes, and who can see it.
This documentation is built and hosted on Mintlify, a developer documentation platform.