> ## 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 Pay is for platforms whose agent shops for many end users. Each end user is a buyer with their own Sapiom key and saved cards.
> Use the buyer's key for every call made on that buyer's behalf. Never use one buyer'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 test environment with its own buyers and cards, at the same addresses. Use test card numbers only there.
> Never ask a buyer for a card number, expiry date or CVV in chat. Buyers 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 for the intended buyer only.
> 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.

# Use Browser Pay with Browser Use

> Resolve a Browser Use browser's CDP URL to a WebSocket URL for Browser Pay, then stop the browser when checkout ends.

Browser Pay connects to the Browser Use browser your worker drives through a CDP WebSocket URL. Browser Use returns `cdpUrl`, which can be an HTTPS address, so resolve it first. If you already have a browser, start at [Resolve the WebSocket URL](#resolve-the-websocket-url).

## Create a browser

[Create a browser session](https://docs.browser-use.com/cloud/api-v2/browsers/create-browser-session) with your Browser Use API key. This starts a browser in your Browser Use account. It does not create a Sapiom transaction.

```typescript theme={null}
const response = await fetch("https://api.browser-use.com/api/v2/browsers", {
  method: "POST",
  headers: {
    "X-Browser-Use-API-Key": process.env.BROWSER_USE_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ timeout: 5 }),
});
if (!response.ok) throw new Error(`Browser Use HTTP ${response.status}`);
const session = await response.json();
const sessionId: string = session.id;
```

`timeout` is in minutes. Make it long enough for the whole checkout.

## Resolve the WebSocket URL

An HTTPS `cdpUrl` serves the WebSocket URL at `/json/version`. Browser Pay does not do this lookup for you:

```typescript theme={null}
async function toWebSocketUrl(cdpUrl: string): Promise<string> {
  const url = new URL(cdpUrl);
  if (url.protocol === "wss:") return cdpUrl;
  url.pathname = url.pathname.replace(/\/?$/, "/json/version");
  const res = await fetch(url);
  if (!res.ok) throw new Error(`CDP discovery HTTP ${res.status}`);
  const { webSocketDebuggerUrl } = await res.json();
  return webSocketDebuggerUrl;
}

const cdpUrl = await toWebSocketUrl(session.cdpUrl);
```

Pass `cdpUrl` to [`attachInterceptor`](https://docs.sapiom.ai/transactions/browser-pay#attach-browser-pay-then-fill-the-form), and connect your driver to the same URL. Do not pass `liveUrl`; it is for watching the browser.

## Stop the browser

After checkout settles, call `handle.detach()`, close your driver, and [stop the browser](https://docs.browser-use.com/cloud/api-v2/browsers/update-browser-session):

```typescript theme={null}
await fetch(`https://api.browser-use.com/api/v2/browsers/${sessionId}`, {
  method: "PATCH",
  headers: {
    "X-Browser-Use-API-Key": process.env.BROWSER_USE_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ action: "stop" }),
});
```


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