Your own browser

You don’t need a browser provider. If your agent drives its own Chromium, locally or on your infrastructure, the Vault attaches to it the same way it attaches to KERNEL or Browserbase. There are three levels, depending on how much of the browser you control. You need a user with a card in the Vault first. See Adding a card.

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.

npm i @agent-cards/checkout@0.3.0 playwright

import { chromium } from 'playwright';
import { VaultClient, attachToPlaywright } from '@agent-cards/checkout';

const browser = await chromium.launch({ headless: true });
const context = await browser.newContext({ serviceWorkers: 'block' });
const page = await context.newPage();

const vault = new VaultClient({
  clientId: process.env.AGENTCARD_CLIENT_ID!,
  clientSecret: process.env.AGENTCARD_CLIENT_SECRET!,
});
await vault.syncRegistry();

const checkout = await attachToPlaywright(page, {
  vault,
  user: 'usr_8f3k2m',
  merchant: 'shop.example.com',
  amountCents: 2306,
  currency: 'usd',
  onApprovalUrl: (url) => sendToUser(url),
});

// Now let the agent shop.
await page.goto('https://shop.example.com');

A remote Chromium works too: replace chromium.launch() with chromium.connectOverCDP(yourCdpUrl).

Level 2: You speak CDP directly

Not on Playwright? The SDK also exposes attachToCdp. Give it a browser-level, session-aware CDP connection wrapped in its two-method CdpLike interface (send a command, subscribe to events). The SDK needs the browser level, not a single page session, because card fields live in cross-origin iframes that are separate CDP targets and it attaches to each one.

import { VaultClient, attachToCdp } from '@agent-cards/checkout';

const checkout = await attachToCdp(myCdpConnection, {
  vault,
  user: 'usr_8f3k2m',
  merchant: 'shop.example.com',
  amountCents: 2306,
  currency: 'usd',
  onApprovalUrl: (url) => sendToUser(url),
});

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:

curl -X POST https://api.agentcard.sh/api/v2/checkout/authorizations \
  -H "Authorization: Bearer $ORG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user": "usr_8f3k2m",
    "merchant": "shop.example.com",
    "amount_cents": 2306,
    "currency": "usd",
    "psp": "stripe",
    "request": {
      "url": "https://api.stripe.com/v1/tokens",
      "method": "POST",
      "headers": { "content-type": "application/x-www-form-urlencoded" },
      "body": "card[number]=4242424242424242&..."
    }
  }'

The response carries 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-origin set to the paused request’s own Origin header, plus access-control-allow-credentials: true, or the page rejects it. The SDK exports withCorsHeaders for this.
Recognized processors only. GET /v2/checkout/recognizers lists the processor endpoints Agentcard can complete. Pause those, and leave everything else untouched.

Whichever level you pick, the rest of the flow is identical: placeholder card, Face ID approval, real card swapped in, confirm with the merchant. Follow the Vault Quickstart from step 4, or read Completing a purchase.

Getting started

Vault

Issuing

Level 1: You use Playwright

Level 2: You speak CDP directly

Level 3: You do your own interception

Next

​Level 1: You use Playwright

​Level 2: You speak CDP directly

​Level 3: You do your own interception

​Next

Level 1: You use Playwright

Level 2: You speak CDP directly

Level 3: You do your own interception

Next