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

# Local browser

> Pay at checkout in a browser on your own machine while you develop and test.

Use a local browser to develop and test on your own machine. For production, use a hosted browser: [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) or [Browser Use](https://docs.sapiom.ai/transactions/browsers/browser-use.md).

Sapiom Browser Pay needs a Chromium-based browser with a Chrome DevTools Protocol (CDP) port. You pass the port's URL to `attachInterceptor`.

## Start a browser

Let your code open Playwright's Chromium with a CDP port:

```bash theme={null}
npm install playwright @sapiom/browser-pay@^0.7.0
npx playwright install chromium   # Playwright needs Node.js 20+
```

Then launch it from your code:

```js theme={null}
import { chromium } from "playwright";

// A visible window: some merchants show a captcha to headless browsers.
const browser = await chromium.launch({ headless: false, args: ["--remote-debugging-port=9222"] });
const cdpUrl = "http://127.0.0.1:9222";
```

Or start Chrome yourself with a CDP port and a separate profile, then connect your driver to it:

```bash theme={null}
# macOS. Chrome opens a CDP port only for a profile other than your default one.
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --remote-debugging-port=9222 --user-data-dir="$(mktemp -d)"
```

## Attach Sapiom Browser Pay

Pass `cdpUrl` to [`attachInterceptor`](https://docs.sapiom.ai/transactions/make-a-purchase#attach-sapiom-browser-pay), and drive the checkout in the same browser.

## Close the browser

The CDP port controls the whole browser, so keep it on `127.0.0.1`. After checkout settles, detach and close the browser:

```js theme={null}
await handle.detach();
await browser.close();
```


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