Level 1: You use Playwright
Attach to your Playwright page. This is the same code as every other browser, with your own launch instead of a provider’s.chromium.launch() with chromium.connectOverCDP(yourCdpUrl).
Level 2: You speak CDP directly
PassattachToCdp your browser-level CDP connection and the session id of the tab your agent checks out in. When your agent submits the placeholder card in that tab, the SDK pauses the request to the payment processor and calls onApprovalUrl with the link the user opens to approve.
CdpLike type the SDK exports: a send(method, params, sessionId) that resolves with the command’s result and rejects on a CDP error, and an on(handler) that receives every event with the session id it came from. Attach to the tab with flatten: true, as the sample does, so each command and event carries that session id.
Open the checkout tab in a fresh browser context, as the sample does with Target.createBrowserContext. An extension page or a service worker in the tab’s context can send the card to the payment processor in a request the SDK cannot pause, so attachToCdp refuses that context and throws:
Target.closeTarget. If your code created the tab’s context, dispose it with Target.disposeBrowserContext. Then open the checkout again with the sample’s three Target calls.
A store that runs a service worker of its own needs serviceWorkers: 'bypass'. Replace the attachToCdp call in the sample with one that passes it:
bypass, the SDK accepts a service worker that already runs and one the store starts after you attach. The store’s service workers keep running but serve none of the page’s requests, so the store’s offline pages stay off, and a store that runs its third-party tags through Partytown runs them on the page instead. bypass needs @agent-cards/sdk 0.23.20 or later.
Without bypass, a store can register a service worker after you attach. attachToCdp has already returned by then, so nothing throws. The checkout stops instead, and checkout.getState() returns:
serviceWorkers: 'bypass' to check out on a store like that, or check out through Level 1, where Playwright’s serviceWorkers: 'block' stops the store from registering a service worker.
Level 3: You do your own interception
If you already intercept network requests in your browser, skip the SDK and make the authorization call yourself. When your agent submits the placeholder card and you see the request to the payment processor, pause it and send it to Agentcard:approvalUrl to send the user. Poll GET /v2/checkout/authorizations/:id until it is approved, then fulfill the paused request with the processor response from the authorization. Two things to get right:
- CORS. Stripe and most processors are called cross-origin. Your fulfilled response must carry
access-control-allow-originset to the paused request’s ownOriginheader, plusaccess-control-allow-credentials: true, or the page rejects it. The SDK exportswithCorsHeadersfor this. - Recognized processors only.
GET /v2/checkout/recognizerslists the processor endpoints Agentcard can complete. Pause those, and leave everything else untouched.
line_items, the subtotal, shipping and tax, and ship_to. The approval page lists the products and where the order ships, labelled as sent by your company, and the user still approves amount. Create a checkout authorization lists the fields.