Sapiom Pay API overview - Sapiom Pay

Sapiom Pay has three surfaces. They share the same keys and data.

Surface	Used by	Endpoint	Reference
REST API	Your backend	`https://api.sapiom.ai/v1`	REST endpoints
MCP tools	Your agent	`https://api.sapiom.ai/v1/mcp`	MCP tools
Browser Pay SDK	Your browser worker	`npm install @sapiom/browser-pay`	Browser Pay SDK

Authentication

Send a key in the x-api-key header on every REST request and MCP connection:

curl https://api.sapiom.ai/v1/payment-cards -H "x-api-key: $SAPIOM_BUYER_KEY"

Key	Where it comes from	Use it for
Platform key	Request access	Creating buyers and buyer keys. Keep it in your backend.
Buyer key	`POST /v1/tenants/{tenantId}/api-keys`	Everything you do for one user: cards, transactions and Browser Pay

Every request made with a buyer key is limited to that buyer’s cards and transactions. Keys are shown once, as plainKey in the creation response. Branding endpoints are the exception. They need a signed-in dashboard user. See Brand hosted pages.

Permissions

Permission	Allows	Held by
`org.tenants.write`	Create buyers and buyer keys	Platform key
`org.transactions.write`	Save and remove cards, request, update and cancel transactions	Buyer key
`org.transactions.read`	Read cards, setup links, merchants and transactions	Buyer key

Retries and idempotency

Transactions, updates and cancellations each take an idempotencyKey, so you can retry safely without buying twice. See Keep the same idempotency key. Setup links take no key; each call creates a new link.

REST endpoints

Each group has a page per endpoint, with its fields and examples.

Group	Endpoints	Key
Buyers	Create, list and delete buyers, and create buyer keys	Platform key
Cards	Setup links, and list, read, set default and remove cards	Buyer key
Spending limits	Read and set a card’s spending limits	Platform key
Merchants	Check whether Sapiom can buy from a merchant	Buyer key
Transactions	Create a transaction, then open, read, replace, cancel and refresh its checkout	Buyer key
Browser checkout	Placeholder cards, relay profiles and the relay Browser Pay uses	Buyer key