Skip to main content
A purchase is one order from one merchant, made for one user with that user’s key. Sapiom checks it against the user’s budget and your spending limits, and every response says what to do next. When the purchase is approved, your code pays in the merchant’s checkout with a placeholder card, and Sapiom Browser Pay sends the real card in its place. There are two kinds of checkout: UCP checkout, and any checkout page your agent drives in a browser. They follow the same path, and differ in who builds the cart, who states the total, and where the order is confirmed.

With Sapiom Browser Pay

The user’s saved card pays.

UCP merchant ucp_checkout

The merchant’s checkout states the items and total.

Budget and limitsSecurity code, no budget onlyAgent pays

Any other merchant browser_checkout

Your agent states what it’s buying.

Agent statesBudget and limitsSecurity code, no budget onlyAgent pays

Pick the checkout type

Check whether the merchant supports UCP:

Create the purchase

Send an Idempotency-Key. Always send purchase.merchant.name and countryCode. A total over what the budget has left returns 400 budget_insufficient. Store the purchase id, its idempotency key and the last version you read. After a crash or a timeout, they let you read the same purchase or resend the same request, instead of buying twice. For UCP checkout, send the merchant’s line items; Sapiom opens the merchant’s checkout and the merchant states the total. For browser checkout, your agent fills in the checkout page first, then sends the items and the total it reads there.

Follow nextAction

Every response has a nextAction. Its type is wait, buyer_security_code (only without a budget), approval or payment_ready. Stop when its actor is human. Read the purchase. maxWaitSeconds (up to 25) holds the call open until something changes since your last version:

Which credential goes

Sapiom chooses the credential once, when it creates the purchase. It sends a network agentic token when the card has a budget its network verified, the total is in USD, and the purchase names the merchant and its country. Otherwise it sends the card number, with the security code saved with the budget. Both draw on the same budget, and your code doesn’t change.

Pay in the browser

At payment_ready, your code pays in the merchant’s checkout, in a browser it controls. Sapiom Browser Pay relays it; the merchant receives the real credential. Sapiom Browser Pay connects to the browser over the Chrome DevTools Protocol (CDP), so you need the browser’s CDP URL. Your browser provider gives you one: Anchor, Kernel, Browserbase, Browser Use, or a local browser for development. Start the browser before you send the user a confirmation link: the placeholder card works for about an hour after the user confirms. Install the SDK:
For UCP checkout, open nextAction.continueUrl once and pay in that tab. Opening it again starts a new, empty checkout.

Get the placeholder card

Read the purchase. The placeholder card is in payment.placeholder, and the card’s billing country and postal code are in payment.billing:

Attach Sapiom Browser Pay

Attach to the browser before you type any card field:

Fill in and submit

Fill the card fields with fillCard. It finds them in every frame, including Shopify’s card vault and Stripe Elements, and types only into fields a person could see, so it skips decoy fields. Fill the billing fields with payment.billing, submit, then detach:
Sapiom Browser Pay can pay a checkout that POSTs the card form to the merchant’s own HTTPS origin, with the placeholder once in the body. It can’t pay forms that encrypt the card in the page, such as Adyen’s. Sapiom Browser Pay reports one of four events: relayed, relayed_unfulfilled, refused or failed. Once the card is handed over, the purchase reads completed. Then confirm the order.

Change or cancel

UCP: replace the checkout with the full, changed checkout. Browser: cancel and create a new one.

From the agent (MCP)

An agent on the MCP server follows the same steps with sapiom_request_transaction, sapiom_get_transaction, sapiom_update_transaction and sapiom_cancel_transaction. See the MCP tools reference.