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 anIdempotency-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.
- UCP checkout
- Browser checkout
Follow nextAction
Every response has anextAction. 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
Atpayment_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:
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 inpayment.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 withfillCard. 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:
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 withsapiom_request_transaction, sapiom_get_transaction, sapiom_update_transaction and sapiom_cancel_transaction. See the MCP tools reference.