Skip to main content
Your agent builds the cart the way it already does: in a real browser, on the merchant’s own website. Agentcard does not change how the agent shops. It attaches to the browser and waits for the moment the checkout form sends the card to the payment processor. There is one rule: attach before the agent reaches the payment form. The SDK has to be watching when the page tries to send the card.

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.
Your agent keeps control of the browser during approval and afterward.

Install

You need your Agentcard 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

string
required
The Agentcard user whose vaulted card pays.
string
required
Shown on the approval screen. Pass what the user would recognize.
number | string
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.
string
ISO 4217 code for amount. Required with it.
function
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:
A store’s call to register a service worker then returns nothing, and no worker starts in the session. A service worker sends the page’s requests itself, and Playwright cannot pause a request a service worker sends. The card request is one of them. attachToPlaywright refuses a page whose context already runs a store’s service worker and throws:
Playwright’s own 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.

Don’t want a browser?

Agentcard’s Commerce SDK builds the cart and completes the checkout for you on the merchants it covers (Amazon, Walmart, Target, DoorDash, and more). No browser to run, same passkey approval for the user.