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

> Get a Browserbase session's CDP WebSocket URL for Browser Pay, then release the session when checkout ends.

Browser Pay connects to the Browserbase session your worker drives through its CDP WebSocket URL, `connectUrl`. If you already have a session, use its `connectUrl` and go to [Attach Browser Pay](https://docs.sapiom.ai/transactions/browser-pay#attach-browser-pay-then-fill-the-form).

## Create a session

[Create a session](https://docs.browserbase.com/reference/api/create-a-session) with your Browserbase API key. This starts a browser in your Browserbase account. It does not create a Sapiom transaction.

```typescript theme={null}
const response = await fetch("https://api.browserbase.com/v1/sessions", {
  method: "POST",
  headers: {
    "X-BB-API-Key": process.env.BROWSERBASE_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ timeout: 300 }),
});
if (!response.ok) throw new Error(`Browserbase HTTP ${response.status}`);
const session = await response.json();
const sessionId: string = session.id;
const cdpUrl: string = session.connectUrl;
```

`timeout` is the session's maximum length in seconds. Make it long enough for the whole checkout.

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.

## Release the session

After checkout settles, call `handle.detach()`, close your driver, and [request release](https://docs.browserbase.com/reference/api/update-a-session):

```typescript theme={null}
await fetch(`https://api.browserbase.com/v1/sessions/${sessionId}`, {
  method: "POST",
  headers: {
    "X-BB-API-Key": process.env.BROWSERBASE_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ status: "REQUEST_RELEASE" }),
});
```

The session ends when its `status` is `COMPLETED`.


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