> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sapiom.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## 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.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.

# Make a purchase

> Buy one thing for one user, from request to the card at checkout.

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.&#x20;

With Sapiom Browser PayThe user's saved card pays.

UCP merchant `ucp_checkout`The merchant's checkout states the items and total.

Budget and limits

Security code, no budget only

Agent pays

Any other merchant `browser_checkout`Your agent states what it's buying.

Agent states

Budget and limits

Security code, no budget only

Agent pays

## Pick the checkout type

Check whether the merchant supports UCP:

```bash theme={null}
# "supported" → create a ucp_checkout purchase; anything else → browser_checkout.
curl -G https://api.sapiom.ai/v1/transaction-compatibility \
  -H "x-api-key: $SAPIOM_USER_KEY" \
  -d domain=shop.example
```

## 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.&#x20;

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.

> [tab] UCP checkout
>
> ```bash theme={null}
> curl -X POST https://api.sapiom.ai/v1/transactions \
>   -H "x-api-key: $SAPIOM_USER_KEY" -H "Idempotency-Key: order-7f3a" \
>   -H "Content-Type: application/json" -d '{
>   "purchase": {"type":"ucp_checkout","merchant":{"origin":"https://shop.example","name":"Example Shop","countryCode":"US"},
>     "checkout":{"currency":"USD","line_items":[{"item":{"id":"gid://shopify/ProductVariant/1234567890"},"quantity":1}]}},
>   "funding": {"source":"external_card"},
>   "shipping": {"address":{"first_name":"Jane","last_name":"Doe","street_address":"1 Market St","address_locality":"San Francisco","address_region":"CA","postal_code":"94105","address_country":"US"},"contact":{"email":"jane@example.com"}}
> }'  # save the transaction "id" from the response
> ```

> [tab] Browser checkout
>
> ```bash theme={null}
> curl -X POST https://api.sapiom.ai/v1/transactions \
>   -H "x-api-key: $SAPIOM_USER_KEY" -H "Idempotency-Key: order-9c21" \
>   -H "Content-Type: application/json" -d '{
>   "purchase": {"type":"browser_checkout","merchant":{"origin":"https://store.example","name":"Example Store","countryCode":"US"},
>     "total":{"amount":"54.18","currency":"USD"},"pageUrl":"https://store.example/checkout",
>     "claimedLineItems":[{"title":"Trail running shoes, size 10","quantity":1,"unitAmount":"48.00"}]},
>   "funding": {"source":"external_card"}
> }'  # save the transaction "id" from the response
> ```

## 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`.&#x20;

Read the purchase. `maxWaitSeconds` (up to 25) holds the call open until something changes since your last `version`:

```bash theme={null}
curl -G "https://api.sapiom.ai/v1/transactions/$TRANSACTION_ID" \
  -H "x-api-key: $SAPIOM_USER_KEY" \
  -d maxWaitSeconds=20 \
  -d since="$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.&#x20;

## 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](https://docs.sapiom.ai/transactions/browsers/anchor.md), [Kernel](https://docs.sapiom.ai/transactions/browsers/kernel.md), [Browserbase](https://docs.sapiom.ai/transactions/browsers/browserbase.md), [Browser Use](https://docs.sapiom.ai/transactions/browsers/browser-use.md), or a [local browser](https://docs.sapiom.ai/transactions/browsers/local.md) 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. &#x20;

Install the SDK:

```bash theme={null}
npm install @sapiom/browser-pay@^0.7.0
```

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`:

```typescript theme={null}
const transaction = await fetch(`https://api.sapiom.ai/v1/transactions/${transactionId}`, {
  headers: { "x-api-key": userKey },
}).then((res) => res.json());
if (transaction.nextAction.type !== "payment_ready") throw new Error(transaction.nextAction.type);
const placeholder = transaction.payment.placeholder;
```

### Attach Sapiom Browser Pay

Attach to the browser before you type any card field:

```typescript theme={null}
import { attachInterceptor, httpPaymentRelay } from "@sapiom/browser-pay";

const handle = await attachInterceptor(cdpUrl, {
  relay: httpPaymentRelay({ baseUrl: "https://api.sapiom.ai", apiKey: userKey, transactionId }),
  placeholder: { number: placeholder.number, injectionRef: placeholder.injectionRef },
  // At a Shopify checkout, also pass profileId: "shopify-card-vault".
});
```

### 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:

```typescript theme={null}
import { fillCard } from "@sapiom/browser-pay";

const filled = await fillCard(page, placeholder); // page: your Playwright page
if (!filled.ok) throw new Error(`Card fields not filled: ${filled.missing.join(", ")}`);
// Submit the checkout form, then:
await handle.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](https://docs.sapiom.ai/transactions/confirm-and-recover.md).

## Change or cancel

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

```bash theme={null}
# UCP: send the whole changed checkout, with a new Idempotency-Key.
curl -X PUT "https://api.sapiom.ai/v1/transactions/$TRANSACTION_ID/ucp/checkout" \
  -H "x-api-key: $SAPIOM_USER_KEY" -H "Idempotency-Key: order-7f3a-2" \
  -H "Content-Type: application/json" -d @checkout.json
# Browser: cancel, then create a new purchase.
curl -X POST "https://api.sapiom.ai/v1/transactions/$TRANSACTION_ID/cancel" \
  -H "x-api-key: $SAPIOM_USER_KEY" -H "Idempotency-Key: cancel-7f3a"
```

## 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](https://docs.sapiom.ai/api-reference/mcp-tools.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.