Choose a browser
The SDK attaches to any Playwright Chromium page, which means it works with:- KERNEL: connect over
cdp_ws_url. KERNEL also ships a native Agentcard integration that needs no SDK. Pick one per checkout. - Browserbase: connect over the session’s
connectUrl. - Browser Use: connect over the browser’s
cdpUrl. - Anchor: get the connected Playwright browser with
const { browser } = await createBrowser(); attach to its first page. - Notte: connect over the session’s
cdpUrl(). - Any CDP browser: supply its CDP URL.
Install
client_id and client_secret on your server, and the user_id of the person whose card will pay (from Adding a card).
Attach to the page
Your hint at the amount: an integer in the currency’s smallest unit (2306 for $23.06), or a decimal string in normal units (
"23.06"). Pass with currency. Caps use the amount the processor charges. Send amount to have a purchase judged the moment your agent opens it.Called with the approval link the moment the payment pauses. Deliver it to the user in your own thread or app.
Block service workers
Add the init script to the context before your agent opens the store, as the sample above does:attachToPlaywright refuses a page whose context already runs a store’s service worker and throws:
serviceWorkers: 'block' option does the same job, but only on a context you create with browser.newContext(). A cloud browser such as Browserbase, KERNEL, Anchor, Browser Use or Notte hands you a default context it already made, and a new context has none of the session’s saved logins. The init script blocks service workers on the context you already have.
Add the script before the first navigation. attachToPlaywright checks for service workers only when you attach, so a worker a store starts later goes unnoticed, and the SDK cannot pause the card request.
Most stores load and check out as usual with service workers blocked. The store’s offline pages and push prompts stay off for the session, and a store that runs its third-party tags through Partytown runs them on the page instead of in a worker.
A store whose page waits for its service worker to start, through navigator.serviceWorker.ready, waits forever with the block on. Check out on a store like that through CDP with serviceWorkers: 'bypass', which lets the worker start and still pauses the card request.
A saved browser profile keeps the service workers an earlier session started, and the script cannot remove them. Start checkout sessions without a saved profile, or attach through CDP with serviceWorkers: 'bypass', as Your own browser shows. attachToPlaywright ignores the serviceWorkers option, so bypass needs attachToCdp.
Two things that break attachment
- Service workers. Block them before the store’s first page loads, as Block service workers shows.
- Attaching too late. If the agent has already submitted the payment form, there is nothing to pause. Attach right after you get the page, before navigation.