@agent-cards/sdk 0.20.0

package/README.md

@@ -0,0 +1,864 @@
+# @agent-cards/sdk
+
+Agentcard's SDK: one client, `Agentcard`, with two modules. The directory in the monorepo is still `packages/checkout`; the package on npm is `@agent-cards/sdk`. `@agent-cards/checkout` is its older name and re-exports this package, entry for entry. `@agent-cards/voice` is the phone package, not an alias of this one.
+
+| Module | What it does |
+|---|---|
+| `agentcard.checkout` | Pauses a browser purchase's card request, has the cardholder approve it, and replays the processor's answer; creates a purchase directly; the recognisers and the request builders |
+| `agentcard.voice` | Connects a person's card to your product once; approves a purchase by voice inside it: the key word, the stream, the result; reads a returning person; revokes a connection |
+
+Card data never enters your process, your logs or your network: your server holds a placeholder card and a token, and the person's device supplies the real card.
+
+## Install
+
+```bash
+npm i @agent-cards/sdk
+```
+
+Node 22 or any runtime with `fetch`, `WebSocket` and WebCrypto. Zero runtime dependencies. One base URL, `https://api.agentcard.sh`; sandbox and live are decided by your credentials.
+
+## Hello world
+
+A person connects their card to your app once, then approves a purchase by voice. Six lines, against a sandbox client.
+
+```js
+import { Agentcard } from '@agent-cards/sdk';
+
+const agentcard = new Agentcard({ clientId: process.env.AGENTCARD_CLIENT_ID, clientSecret: process.env.AGENTCARD_CLIENT_SECRET, voice: { approval: 'sheet', returnUrl: 'yourapp://connected' } });
+
+const link = await agentcard.voice.connect();                                   // the app opens link.url in its sheet
+const person = await agentcard.voice.completeConnect(returnLink);               // the link the sheet came back with
+const purchase = await agentcard.voice.authorizations.create({ user_id: person.user_id, merchant: 'Coffee', amount: 1250, currency: 'usd', request: 'sandbox' });
+const { card, cards } = purchase;                                                // the card that pays and why; cards are the others, for authorizations.setCard(purchase.id, id)
+const result = await agentcard.voice.awaitResult(purchase.id);                  // { status: 'approved', approved_with: 'voice' }
+```
+
+The app opens `purchase.approval_url` in its sheet for the approval (see `@agent-cards/voice`). Sandbox and live are decided by the credentials: the token exchange names the client's mode and the client reads it (`agentcard.sandbox`), so nothing here says which one this is. `request: 'sandbox'` is the first-run form: it names no processor, the sandbox completes it as a sandbox charge, and only a sandbox client may send it. At go-live the credentials change and the request becomes the processor's own card request: one a browser purchase paused on, or one `agentcard.checkout.requests.build(...)` made for your order. `voice.returnUrl` is exactly one of the redirect links registered on your client. `readme.test.mjs` runs this block against a stub on every test run.
+
+### A returning person
+
+Store `person.user_id`. On a later launch ask what they already have, and open the Vault only for what is missing.
+
+```js
+const who = await agentcard.voice.people.get(storedUserId);          // { user_id, card, voice: ['en'], rule, passkey }
+if (!who.card || !who.voice.includes('en')) {
+  const link = await agentcard.voice.connect({ voice: 'required' }); // the Vault shows only the missing step
+}
+```
+
+`connection_not_found` means the person never connected through your client (or disconnected): treat them as new.
+
+### Approving inside your app
+
+`voice: { approval: 'sheet' }`: the person approves on Agentcard's page, opened in your app for one moment; `purchase.approval_url` (or `voice.approvals.approvalUrl(id)`) is the link. `voice: { approval: 'in_app' }`: hold-to-talk in your app, judged on the phone and by Agentcard, signed by a key in your app. The server then mints the key word as one sealed bundle the app forwards unread:
+
+```js
+const bundle = await agentcard.voice.challengeForHost(purchase.id, { lang: 'es' });   // to the app's VoiceHost.approve, unread
+const reg = await agentcard.voice.appKeys.register(key, { user_id: person.user_id });  // the key the app's frame minted; reg.credential goes back to the phone
+```
+
+One choice per business, not per purchase; there is no default, and a client built without `voice` has every `voice.*` verb throw `missing_approval_posture`.
+
+### The card that pays
+
+Under the person's smart routing (on unless they turned it off in the Vault) the card that earns the most for the purchase pays when your create pins none, and every read names it: `purchase.card` is `{ id, name, last4, brand, reason }`, the reason the recommendation's sentence for it, null when your create pinned the card (`card_id`) or the person chose another. `purchase.cards` lists every card the person could pay with instead, each with `recommended` and the recommendation's reason where it scored the card. The key word line names the card and the reason before the word ("Paying 34 dollars and 99 cents to Epicdrops with your Sapphire, three times the points on shopping. Please say your secure passphrase, …"), and the bundle carries `card` so the app shows it beside the word: hearing the card, then speaking the passphrase, is the confirmation. "Another card", spoken or tapped, is `voice.authorizations.setCard(purchase.id, card.id)` before the approval; ask for the key word after it, so the line names the card that will pay. Once the purchase is decided the call answers `already_finalized`.
+
+### Where the key word goes
+
+`challengeForHost(id, { delivery })` names where the key word goes, and the bundle carries both of Agentcard's lines either way: `say` with the word in it, `say_private` pointing at the screen. `delivery: 'screen'`: the app shows `word`, speaks `say_private`, and the word never leaves the phone as sound. `delivery: 'spoken'`: the app speaks `say`, or plays `audio_url` (`audio_delivery` says which form it carries), so a purchase completes with no look at the screen; the word stays on the screen as well. `voice.challenge` takes the same option.
+
+The choice is yours, and it has a cost. Spoken through the loudspeaker, a nearby recorder hears the fresh word before the person has said it. Over headphones or the earpiece it stays with them. The app half reads the audio route (this package cannot) and names it on the streamed answer as `channel`; the `@agent-cards/voice` README says how the reference app reads it.
+
+### A bot with no screen
+
+A messaging bot or an agent with no screen in front of the person sends `link.url` or `purchase.approval_url` as a text itself; the person opens it on their phone. Leave `return_url` out on such a connect: the Vault ends on "Connected", the link polls (`grant: 'poll'`), and `voice.awaitConnected(link.session_id)` reads the result.
+
+### Languages
+
+A language is a BCP 47 tag, and the list Agentcard speaks is data: `await agentcard.voice.languages()` reads it (`[{ tag: 'en', name: 'English' }, { tag: 'es', name: 'Español' }]`), and every call that names a `lang` checks the tag against it first, refusing one not on the list with `unsupported_language` before anything is sent. A language added on Agentcard's side needs no new release of this package.
+
+### Reading, without waiting
+
+`voice.awaitResult`, `voice.awaitConnected` and `voice.actions.awaitDone` wait. For one read with no wait, from a handler that answers a poll: `voice.authorizations.get(id)`, `voice.sessions.get(session_id)`, `voice.actions.get(session_id)`. Every read waits out the API's `slow_down` for you. Passing `timeout_ms: 0` to an await verb is not a read; use the read verbs.
+
+### Webhooks
+
+Agentcard signs every delivery. Verify against the raw bytes and branch on `type`:
+
+```js
+import { verifyWebhook, isCheckoutAuthorizationEvent } from '@agent-cards/sdk';
+
+const event = await verifyWebhook(rawBody, req.headers['agentcard-signature'], [process.env.WEBHOOK_SECRET, process.env.WEBHOOK_SECRET_PREVIOUS]);
+if (isCheckoutAuthorizationEvent(event) && event.type === 'checkout_authorization.approved') markPaid(event.data.id);
+```
+
+More than one secret is accepted, so a secret rotates without a missed event; a stale timestamp, a malformed header and a wrong signature each throw an `AgentcardError` with its own code. The event unions are `CheckoutAuthorizationEvent` (`checkout_authorization.*`) and `VaultEvent` (`vault.*`); an event of a type this release does not name arrives as `OtherEvent`, so branch on `type` and read `data` yourself.
+
+## Complete a purchase you already approved
+
+`agentcard.buy` is Agentcard's Purchase API from the same client: it finds the merchant, builds the cart and places the order for a person you connected. When the person already approved the purchase by voice, the confirm names that approval, and the API places against it and asks them for nothing a second time. Same `agentcard` and `user_id` as the hello world.
+
+```js
+const purchase = await agentcard.voice.authorizations.create({ user_id, merchant: 'Coffee', amount: 650, currency: 'usd', request: 'sandbox' });
+const result = await agentcard.voice.awaitResult(purchase.id);                                          // { status: 'approved', approved_with: 'voice' }
+const turn = await agentcard.buy.ask({ user_id, ask: 'a flat white from Coffee to my desk' });          // { status: 'needs_input', cart: { hash, totalCents, items } }
+const placed = await agentcard.buy.confirm({ user_id, conversation_id: turn.conversation_id, confirm: turn.cart.hash, authorization_id: purchase.id });
+const state = await agentcard.buy.conversation({ user_id, conversation_id: turn.conversation_id });     // { turn_in_progress: false, orders: [{ order_id }] }
+if (placed.status !== 'order_placed') console.log(placed.status, placed.decline_code);                  // 'declined' names why; 'needs_input' is a question, not a failure
+```
+
+Every call names `user_id`; a person not connected to your client is refused with `user_not_connected`. `buy.ask` answers one turn: `status` is `needs_input` (a question, or a cart waiting for its confirm), `order_placed`, `partially_placed` (several carts, some placed; each one's outcome is in `placements`) or `declined` (with `decline_code`). Read `turn.cart.hash` and never the prose; a cart that changed since its hash was issued refuses the confirm with `cart_changed`, and the fresh carts ride on the error. `buy.confirm` with `authorization_id` places against the approval the person gave: one that is not approved, is for another purchase, or already paid an order is refused with `authorization_not_approved`, `authorization_mismatch` or `authorization_spent`, and nothing is charged; the answer carries `authorization_id` back. Without it the confirm runs as before, with `payment_source: 'vault'` for the person's own card. A turn runs against live merchants, so this call waits up to 130 seconds and is sent once, never retried; a turn still running past the API's own budget answers `error_code: 'turn_timeout'` with the carts it had shown, and `buy.conversation` reads whether it is done (`turn_in_progress`) and every order it placed. Refusals are a `BuyError`, an `AgentcardError` with the API's code; `isBuyDeclined(turn)` narrows a declined answer. `buy.test.mjs` runs this block against a stub on every test run.
+
+## Approve a purchase by voice inside your app
+
+When your app holds the person, the confirm asks for their approval by voice instead of an approval page: `approval: 'voice'` with `payment_source: 'vault'`. The API mints the purchase's own approval and answers `status: 'needs_approval'` with its `authorization_id`; your server mints the key word on that id with `voice.challengeForHost`, exactly as for a purchase you created yourself, the app runs it, and the same confirm sent again places the order. `buy.approveByVoice` does the whole dance: one confirm, your `challenge` on the id, one retry. `app.approve(bundle)` below stands for your app taking the bundle to `VoiceHost.approve`.
+
+```js
+const turn = await agentcard.buy.ask({ user_id, ask: 'a flat white from Coffee to my desk' });          // { status: 'needs_input', cart: { hash } }
+const placed = await agentcard.buy.approveByVoice({ user_id, conversation_id: turn.conversation_id, confirm: turn.cart.hash,
+  challenge: async (id) => { await app.approve(await agentcard.voice.challengeForHost(id)); await agentcard.voice.awaitResult(id); },
+});                                                                                                     // 'order_placed', 'declined', or 'voice_execution_unsupported'
+if (placed.status === 'declined') console.log(placed.decline_code);                                    // 'voice_declined' | 'approval_expired'
+if (placed.status === 'voice_execution_unsupported') console.log(placed.error.message);               // take your own path; nothing was charged
+```
+
+`challenge` is called once, with the `authorization_id` the API minted and the `needs_approval` turn it rode on; resolve it when the verdict is in (`voice.awaitResult`, or your app's own word), and the retry follows. The answer is the final turn: `order_placed` with `order_id` and the `authorization_id` it was placed against; `declined` with `decline_code: 'voice_declined'` when the person said no, or `'approval_expired'` when the approval ran out first; `needs_approval` again when the verdict was still out, in which case a later `buy.confirm` with the same hash and `approval: 'voice'` completes it. A store whose connector cannot place under a voice verdict answers `409 voice_execution_unsupported`; `approveByVoice` returns it as `status: 'voice_execution_unsupported'` with the `BuyError` in `error`, and `buy.confirm` throws it, so your fallback is a branch and not a catch. A challenge that rejects is thrown as it came and nothing is placed. `isBuyNeedsApproval(turn)` and `isBuyVoiceUnsupported(turn)` narrow the two new shapes. Without `approval` the confirm is what it was: the page on `approval_url`.
+
+## Browser purchases
+
+Your agent drives checkout normally. When the page tries to send the card, the SDK pauses that one request, the cardholder approves on their device, the device supplies the card and calls the processor, and the page gets the answer to replay.
+
+```
+your agent ──drives──> merchant checkout
+                            │ card request
+                            ▼
+                    [ paused by this SDK ]
+                            │  template only, placeholder card
+                            ▼
+                  Agentcard ──notify──> cardholder's device
+                                             │ decrypts card locally
+                                             ▼
+                                     processor's card vault
+                            ┌────────token────────┘
+                            ▼
+                    [ request resumed ]  ──> order completes
+```
+
+```ts
+const agentcard = new Agentcard({ clientId, clientSecret });
+await agentcard.checkout.syncRegistry();              // the API's current recognisers; a failed read keeps the built-ins
+await agentcard.checkout.attachToCdp(cdp, pageSessionId, {
+  user: 'usr_123',                 // whose card should pay
+  merchant: 'vanman.shop',
+  amount: 583,                     // your hint, an integer in the currency's smallest unit (or a decimal string: '5.83')
+  currency: 'usd',
+  onApprovalUrl: (url) => sendToUser(url),   // SMS, push, email, iMessage: your call
+});
+```
+
+Playwright: `agentcard.checkout.attachToPlaywright(page, { user, merchant, amount, currency })`. The named exports `attachToCdp(cdp, id, { vault: agentcard, … })` and `attachToPlaywright(page, { vault: agentcard, … })` are the same calls.
+
+`amount` is your hint. The processor's own amount is the higher authority: Agentcard reads it from the paused request or from the Stripe intent the request names, right before the cardholder's device replays, and the company's caps are judged on it. A hint more than one smallest unit away from the processor's amount is refused with nothing charged (`AmountMismatchError`), and after the replay the charge is reconciled against the approval (`ReplayResponse.amountVerified`, `chargedAmount`, `chargedKind`, plus the `checkout_authorization.amount_mismatch` webhook when the charge disagreed). Every result carries `amountAuthority`: `processor`, `agent`, `page`, or `none`.
+
+Merchant timeouts still apply to the request itself: Square's observed tokenization deadline is about 10 seconds, Braintree's native request timeout is 60 seconds, and Adyen Web's own request timeout abandons its Sessions payment call 60 seconds after Pay. These are the processors' limits; the SDK's own authorization wait stays 15 minutes. The approval outlives the page's own request: when the page's script gives up on its paused card request while the cardholder is still deciding, the SDK keeps the approval pending (state `awaiting_approval`, reason `merchant_request_lost`) and answers the page's next request for the same purchase from it; when the approval lands first, the controller reads `ready_to_submit` with reason `awaiting_merchant_retry`, and one more Pay click completes the purchase. The wait for that request is bounded (`merchantRetryWaitMs`, two minutes by default); an approval the page never asks for again is retired as `merchant_never_retried`. For a short-deadline processor, `controller.prepare()` before the first Pay finishes the request inside its own deadline.
+
+### Pause only, and let your server create
+
+`attachToCdp(…, { pauseOnly: true, onPaused })` pauses the card request without creating the purchase and hands you `{ request, recognizer, page_origin, controller }`. Create it with `voice.authorizations.create` as on any other purchase, read the result, and `controller.resume(result)` replays the processor's answer into the page. `recognizer` names the processor that claimed the request (`stripe`), and so does the `card_request_paused` event's detail, so nothing has to re-match the URL.
+
+### Recognisers and request builders
+
+Both are registries the SDK ships and you extend at runtime, so a processor or a store Agentcard does not know yet needs no release.
+
+```js
+agentcard.checkout.recognizers.list();                                  // the API's list (after syncRegistry) or the built-ins, plus yours
+agentcard.checkout.recognizers.register({ psp: 'acme', match: /pay\.acme\.test\/tokens/i, hosts: ['^pay\\.acme\\.test$'], encoding: 'json' });
+agentcard.checkout.recognizers.find('https://pay.acme.test/tokens');   // { psp: 'acme', … } | null
+
+agentcard.checkout.requests.list();                                     // stripe/payment_intent_confirm, stripe/card_token, stripe/payment_method, plus yours
+agentcard.checkout.requests.build({ processor: 'stripe', kind: 'payment_intent_confirm', origin: 'https://yourapp.example', intent: { id, client_secret, publishable_key } });
+agentcard.checkout.requests.register({ processor: 'acme', kind: 'pay', build: ({ order }) => ({ url, method: 'POST', headers, body }) });
+```
+
+The three shipped builders are the Stripe shapes Agentcard completes from a direct create today: confirming a PaymentIntent your server created, tokenizing a card for your server to charge, and creating a PaymentMethod for your server to confirm with. A Braintree or Mercado Pago purchase pauses in a browser (`attachToCdp`) or runs as a prepared checkout (`checkout.prepareCheckout`); neither has a direct-create builder yet. `stripePaymentIntentConfirm(origin, intent)` stays as a named export for one release.
+
+### Moving from `@agent-cards/checkout` 0.x
+
+`@agent-cards/checkout` is this package's older name and re-exports it for one release. `@agent-cards/voice` is the phone package, not an alias of this one. `VaultClient` constructs the same client as `Agentcard`; every top-level checkout verb (`syncRegistry`, `authorize`, `isCardRequest`, …) is also under `agentcard.checkout`. The person's connection verbs (`connect`, `completeConnect`, `exchange`, `awaitConnected`, `disconnect`, `sessions.get`, `people.get`) are the voice module's. `voice.authorizations.create` and `voice.appKeys.register` now require `user_id`: there is no default from an earlier connect. `lang` is a `Language` tag (a string), not a union. The phone package is `@agent-cards/voice`.
+
+## The paused request
+
+A purchase's `status` is one of `awaiting_approval`, `approved`, `declined` (the person said no, a rule or the processor refused: `terminal_reason` says which), `cancelled` (withdrawn before a decision, by you or by the checkout runtime), `expired`, or, from `awaitResult` alone, `timeout` at your deadline. `voice.authorizations.cancel(id, { reason })` withdraws a purchase the person has not decided yet, in your words (`person_closed_sheet`, `person_changed_mind`, `business_cancelled`). `checkout_origin` on the create (or the paused request's `origin` header) is what an auto-approval rule needs to take the purchase; without it the create answers `execution_reason: 'unverified_origin'`. On a finished purchase `awaitResult` and `authorizations.get` carry `settlement`: whether the charge settled, as Agentcard read it back from the processor (`status: 'settled' | 'not_settled' | 'unknown'`, `final`, `settled_amount`, `message`).
+
+The connect link is an OAuth authorization grant: `voice.connect` mints `state` and a PKCE challenge, the sheet's return link carries `code` and `state`, and `voice.completeConnect(url)` exchanges it once, within 60 seconds, refusing a `state` it did not mint before any call. When another server instance minted the link, pass the `code_verifier` and `expected_state` that `connect` returned there. A mint with no return link polls (`grant: 'poll'`, then `awaitConnected`). `readReturnLink(url)` reads a return link's `code`, `state` and `voice_reset`. `voice.connect({ landing: 'voice_options' })` mints a link that lands the signed-in person on the Vault's Voice options page (the voice key, its reset, the language, the passkey it rests on) for an app's own settings row; it collects nothing and polls.
+
+## Credentials
+
+Use your **OAuth client credentials**, not an `sk_` API key: those are retired,
+and the checkout endpoints reject them (`client_credentials_required`) because an
+authorization is bound to the confidential client that created it. The SDK does
+the `client_credentials` exchange for you, caches the token, and refreshes it
+once on a 401. Create a client from the dashboard Credentials page or with
+`agent-cards-admin oauth-clients create`.
+
+## Why you need the SDK and not just `Fetch.enable`
+
+Card fields render in **cross-origin iframes**, which are separate CDP targets.
+Enabling `Fetch` on the page session never sees the tokenization request. You
+need recursive `Target.setAutoAttach({ flatten: true })` on every nested target,
+then `Fetch.enable` on each, then `Runtime.runIfWaitingForDebugger` to unpause
+them. That, plus which headers a merchant requires you to replay verbatim, is
+what this package encapsulates.
+
+## What runs where
+
+| | Sees the real card |
+|---|---|
+| Your agent / browser | **no**, only a dummy PAN and a token |
+| Agentcard servers | **no**, a request template and a token |
+| Cardholder's device | yes, decrypts locally, calls the merchant directly |
+
+Because your process only ever handles a dummy card and an opaque token, this
+integration is designed to keep you out of PCI scope. Get your own QSA's read
+before you put that in writing.
+
+## Supported processors
+
+Coverage is specific to the processor request format, merchant setup, browser transport and follow-up flow. A recognized endpoint is not proof that every store using that processor completes checkout.
+
+| Processor | Status |
+|---|---|
+| Shopify | supported, verified end to end |
+| Stripe | tokenization replay and direct card-bearing PaymentIntent confirms are implemented; direct confirms read the intent's amount back from Stripe; a hint sent as `amount` + `currency` must agree with it. Browser token-to-intent continuation is unsupported and held. Validate the exact merchant flow before pilot use |
+| Braintree card tokenization | Prepared checkout supported; one live Haymarket Books ebook purchase with SDK `0.5.0` confirmed merchant fulfillment and SDK `completed` using a merchant receipt resolver. Independent processor capture/settlement, live 3DS and PayPal wallet flows remain unverified. |
+| Checkout.com | supported |
+| Mercado Pago | Card tokenization and prepared checkout are implemented. Guest Checkout Pro in Mexico also corrects the issuer for one native card association when the selected card has the same brand and type. One live MXN 40 Lotería Chida purchase with published SDK 0.10.0 completed automatically through Pay; the merchant confirmed paid status and PDF fulfillment. The historical SDK result remains unknown because the private receipt adapter rejected a relative download URL; a separate read with the corrected adapter confirms that same paid receipt. Independent processor capture/settlement and other country or integration paths remain unverified. |
+| VGS Collect (Very Good Security; Wolt) | not supported: VGS's proxy aliases only submissions from its own iframe, so a replay from the cardholder's device is refused by the merchant (verified on Wolt, 2026-09-03). Not recognized, so the agent's browser is not paused there |
+| Adyen | supported (mode `cse`): the vault encrypts the card for Adyen on the cardholder's device and your browser sends it. Sessions flow: the paused request is `/checkoutshopper/v1/sessions/{id}/payments` on Adyen's own hosts. A merchant that posts the encrypted fields to its own server pauses only when Agentcard reviewed it as a merchant profile (Dunelm and Cinemark so far); both profiles are in `observe`, so their card requests are reported and aborted and nothing pays there yet (see "Adyen merchants that take the card on their own server"). Without a preparation, approval starts at Pay and must land before Adyen Web's own request timeout (observed at 60 seconds on Adyen Web 6.41 and 6.44; not enforced by the SDK); `prepare({ psp: 'adyen' })` moves the approval before Pay |
+| Tranzila | supported (mode `hosted_form`): the cardholder finishes on Tranzila's own page; the paused form navigation resolves to a synthetic page, and you poll the merchant's order state |
+| Fiserv Commerce Hub | implemented (mode `cse`, prepared checkout only) and off until Agentcard turns it on for your company: the card frame's card capture on `connect.fiservapis.com` (or `connect-cert.fiservapis.com` in the sandbox), with the approved card encrypted on the cardholder's device under a key Agentcard reviewed for the merchant. A merchant whose frame posts to Fiserv's `payment-link` endpoint is not recognized. No live merchant purchase is verified yet |
+| Gravy (Gr4vy) Secure Fields | not supported: recognized, not intercepted, and the preflight reports `unsupported` with `request_method_not_supported`. The card request is Secure Fields' update of a checkout session: a JSON body to `/checkout/sessions/<session id>/fields` on the merchant's own host `api.<merchant>.gr4vy.app` (sandbox: `api.sandbox.<merchant>.gr4vy.app`), carrying `payment_method.number`, `payment_method.expiration_date` as one `MM/YY` value and `payment_method.security_code`. Gravy publishes this request as an HTTP PUT and the SDK pauses and replays POST requests only, so today the SDK recognizes the destination but the request continues to Gravy untouched. The shape follows Gravy's published Secure Fields contract and is not confirmed by a capture from a live merchant form. Updating the session stores the card with Gravy; the merchant creates the transaction from the session on its own server, so a completed request is not a payment. Gravy Embed, the hosted frame on `embed.<merchant>.gr4vy.app`, is not covered |
+
+The recognizer list, and the status of each reviewed Adyen merchant profile on
+your client, are fetched from the API at runtime (`agentcard.checkout.syncRegistry()`),
+so new processors work without you shipping a release. `attachToCdp` derives the
+`Fetch.enable` url patterns from that same list rather than a constant, which is
+why the sync call belongs before the attach. `agentcard.checkout.cardUrlPatterns()` returns
+those patterns if you arm a CDP connection yourself. Call
+`GET /v2/checkout/recognizers?modes=token,cse,hosted_form&capabilities=fiserv_card_capture`
+for the list this build syncs. The API serves Fiserv's card capture only to a
+build that lists `fiserv_card_capture`, and only for a company Agentcard turned
+Fiserv on for. An older SDK never pauses a Fiserv request it could not finish,
+and no SDK pauses one for a company Fiserv is off for.
+
+## Modes
+
+Each recognizer carries a `mode` (absent means `token`), and every authorization
+carries the mode it was handled in. The adapters do the right thing for all
+three; the difference matters if you drive `authorize()` yourself.
+`ReplayResponse` is a union, so branch on `mode`.
+
+- **`token`** (every processor but Adyen and Fiserv). The cardholder's device calls the
+  processor and reports its answer; `authorize()` resolves with `status`,
+  `headers` and `body` to fulfill the paused request with. The browser checks
+  a fulfilled answer exactly as it checks a real one, so when the page called
+  the processor cross-origin (Stripe always does: Checkout on
+  `checkout.stripe.com` and Elements in the `js.stripe.com` frame both fetch
+  `api.stripe.com`) the answer must carry `access-control-allow-origin` for
+  the request's own `Origin`, or the page's fetch rejects and the checkout
+  reports a connection error even though the cardholder approved. The
+  adapters add those headers (`corsHeadersFor` + `withCorsHeaders`, exported
+  for a runtime that fulfills by hand, and `corsDecision` when you also want
+  the reason) and report the decision on the `authorized` event as `cors`:
+  `echoed`, `same_origin`, or `none` (no usable Origin on the request, so
+  the page could not read the answer). Only what a browser serializes is
+  echoed: one canonical http(s) origin, or the opaque `null`. Shopify's
+  card iframe posts to its own origin, so it never needed them.
+- **`cse`** (Adyen and Fiserv). Adyen's own page SDK encrypts the card before the request
+  leaves the browser, so the paused body carries ciphertext. The cardholder's
+  device produces the same ciphertext under the merchant's Adyen public key
+  (fetched by Agentcard from Adyen's host when the request is parked) and
+  `authorize()` resolves with `substitutions: { encoding: 'json', at, fields,
+  remove }`. Write them into the paused body with
+  `substituteEncryptedFields(body, substitutions)` and CONTINUE the request
+  from the same browser (`Fetch.continueRequest` with the rewritten
+  `postData`, or Playwright's `route.continue({ postData })`): its session
+  data, risk data and cookies must stay its own. Only the four encrypted
+  fields change, and the siblings named in `remove` are dropped (Adyen's
+  `brand`, which adyen-web derived from the dummy digits the agent typed:
+  left in place it names the wrong card and Adyen refuses the mismatch;
+  absent, Adyen reads the brand off the card it decrypts). A body that lacks
+  the fields throws `SubstitutionError`, which is not terminal. Adyen answers the browser,
+  so `charged_kind` is null on the approval and the merchant's order state is
+  the outcome to poll. A cse replay with `kind: 'merchant_hosted'` is an Adyen
+  merchant's own endpoint instead: its `substitutions` name the profile, a JSON
+  path (`[]` is the body root) and the merchant's field names, and
+  `substituteMerchantHostedBody(body, replay)` writes it after checking the body
+  against `bodySha256` (see "Adyen merchants that take the card on their own
+  server"). A Fiserv card capture (a prepared checkout only) comes back with its
+  envelope's four members at `source.encryptionData`: write them with
+  `substituteFiservEnvelope(body, substitutions)`, never
+  `substituteEncryptedFields`, and continue the request the same way.
+  `substituteFiservEnvelope` throws, writing nothing, when the body is not the
+  paused capture or the envelope names another key than the capture does. The
+  API serves a Fiserv envelope only in the moments after the approval; a later
+  read raises `PaymentOutcomeUnknownError` with reason `cse_substitutions_expired`.
+- **`hosted_form`** (Tranzila). The processor's hosted card form submits the
+  card as a TOP-LEVEL form post, so the paused request is a page navigation
+  (the adapters arm `Fetch.enable` with no resource-type filter and attach the
+  processor's iframe, which is how a Document request on `direct.tranzila.com`
+  gets paused at all). The cardholder's device rebuilds that form with the
+  real card and submits it itself; the processor answers the device, and
+  `authorize()` resolves with `{ mode: 'hosted_form', kind:
+  'submitted_on_device', outcome: 'unverified', submittedAt }` once the
+  device reports the form left. **This is not an approved payment.** The
+  stamp is the cardholder's device attesting that the form left it;
+  Agentcard holds no processor evidence on this mode and cannot obtain any,
+  so the API finishes the authorization as `submitted_on_device` (never
+  `approved`) and sends your server `checkout_authorization.submitted`
+  (never `.approved`). Treat it as "the person paid, or tried to, on their
+  own device" and confirm the order with the merchant before you count it.
+  There is no response to replay: FULFIL the paused navigation with
+  `hostedFormSubmittedPage({ authorizationId, merchant, submittedAt })` (200,
+  `text/html`, `x-agentcard-checkout: submitted_on_device`, a `<meta
+  name="agentcard-checkout">` and an inert JSON block saying "submitted on
+  the cardholder's device, payment unverified, do not resubmit"), the way
+  the adapters do. Do not abort it: an aborted navigation renders nothing,
+  the iframe silently keeps its dummy-card form, and the agent's next move is
+  to click Pay again. Do not fake the processor's result page either: this
+  SDK does not know the outcome. The adapters emit `submitted_on_device` (not
+  `authorized`), refuse a byte-identical re-post of the same form for 15
+  minutes (`hostedFormRepeatQuietMs`), and the API answers a regenerated one
+  with `409 duplicate_submission`, which the adapters quiet the way they quiet
+  a decline (`approvalCooldownMs`): the page's immediate re-posts are refused
+  without a round trip, and once the prior authorization is declined or
+  expired the same form is a new question. Confirm the order with the
+  merchant, which learns the outcome from the processor.
+
+`syncRegistry()` asks the API for `SUPPORTED_MODES` only
+(`token,cse,hosted_form`), so a processor whose flow this build cannot finish
+is never paused; the API serves `hosted_form` entries only to callers that ask.
+A registry mode this SDK cannot finish throws `UnsupportedModeError` before
+creation. An approval returned in an unexpected mode has an unknown outcome
+and holds the attachment for reconciliation. The `authorized` event's detail names
+the `mode`, the `authorizationId` and, for `cse`, the `fields` that were
+substituted; it never carries ciphertext. The `submitted_on_device` event's
+detail names the `authorizationId`, `submittedAt` and `outcome:
+'unverified'`; it is not an `authorized` event and must not be counted as
+one. `amountAuthority` on every replay is `stripe_payment_intent`,
+`hosted_form_sum` (the form's own amount) or `display_only`.
+
+## Errors worth handling
+
+- `ApprovalTimeoutError`: the server confirms the authorization expired without a replay attempt. A local deadline is different: `PaymentOutcomeUnknownError` means the approval link may still be valid, so reconcile the merchant order before another attempt.
+- `ApprovalDeclinedError`: the user said no.
+- `AmountMismatchError`: the processor's amount did not match the amount the
+  user was (or would have been) asked to approve. Nothing was charged. An
+  `ApprovalDeclinedError` with `expectedCents`, `actualCents`, `currency`,
+  `code: 'amount_mismatch'` and `stage`: `'pre_replay'` (checked right before
+  the device would have sent the card; `authorizationId` names the declined
+  authorization) or `'create'` (the intent already disagreed when the request
+  was parked; no authorization exists, `authorizationId` is null). Per
+  request, not per page: a merchant can still update an intent's amount
+  until it is confirmed, so the adapters quiet the page's immediate retry
+  and judge the next request afresh instead of latching.
+- `IntentNotConfirmableError`: the PaymentIntent was already charged, is
+  processing, or is authorized and on hold (or canceled), so Agentcard
+  refused to replay a confirm at it. An `ApprovalDeclinedError` with
+  `code: 'intent_not_confirmable'`. Deliberately not "nothing was charged":
+  check the intent at Stripe before retrying.
+- `ProcessorRefusedError`: the cardholder's device reported a processor
+  request rejection. `pspErrorCode` carries the processor's code; optional
+  `processorError` carries bounded Razorpay reason, source, step and payment/order
+  identifiers when the API has them. A generic code such as `BAD_REQUEST_ERROR`
+  does not establish an issuer decline or prove no money moved. Reconcile the
+  merchant payment before retrying. This remains an `ApprovalDeclinedError`
+  with `code: 'processor_refused'` for compatibility.
+  The attachment records `status: 'declined', reason: 'processor_refused'`
+  and holds further card requests. After confirming merchant failure, call
+  `retryAfterMerchantFailure({ status: 'failed' })` to permit a deliberate new
+  attempt immediately, without waiting for the user-decline cooldown. Do not
+  automatically create a new attachment after this error;
+  the guard applies only within the existing attachment.
+- `CheckoutApiError` with `code === 'amount_unverifiable'`: Stripe could not
+  be asked (502; the SDK retries twice, 500ms then 1500ms, before throwing)
+  or the paused request lacked its client secret or publishable key (400).
+  `code === 'intent_not_confirmable'` at create (409) means the intent was
+  already used; the adapters stop intercepting for that page.
+  `code === 'cse_key_unavailable'` (502) means Adyen did not answer the
+  public-key fetch and is retried the same way; `cse_client_key_unknown`
+  (400) means Adyen does not know the merchant's `clientKey`, and
+  `cse_template_unsupported` (400) means the paused body carries no
+  encrypted card fields to fill (a stored card, a wallet, a single-blob
+  `encryptedCard`); both are terminal for that page.
+  `hosted_form_template_incomplete` (400) means the paused form lacks a
+  field the device fills or the processor requires, `hosted_form_gated`
+  (400) means it carries a live captcha token the device could never
+  re-submit, and `hosted_form_field_refused` (400, with `field` and a
+  `reason` of `stored_credential`, `not_a_sale` or `callback_host`) means
+  the form asks the processor for something other than one plain sale
+  reporting to the merchant you named (a reusable token in or out, a sale
+  mode that is not a sale, a callback URL off the merchant's host: name the
+  merchant by its hostname when the form carries callback URLs); all three
+  are terminal for that page. `duplicate_submission` (409,
+  with `prior_authorization_id` and `prior_status`) means this exact
+  submission already has, or already had, its prompt: the adapters quiet the
+  page's re-posts for `approvalCooldownMs` (no second notification for one
+  payment) and judge the next request afresh, since the prior authorization
+  declines or expires and the same form is then a new question.
+- `AdyenTestPlatformRefusedError`: a payment on Adyen's TEST platform was
+  refused, since a test account can read whatever is encrypted under its key.
+  Nothing was encrypted or charged. An `ApprovalDeclinedError` with `code`
+  `adyen_test_environment_refused` (a live checkout names Adyen's test host or
+  a `test_` client key; at `stage: 'create'` nothing was created and the
+  adapters stop intercepting for that page) or
+  `adyen_test_platform_requires_documented_test_card` (a test-mode checkout
+  where the cardholder's card is not one of Adyen's documented test cards).
+  The controller reads `failed` at `stage: 'create'` and `declined` at
+  `stage: 'pre_replay'`, with the code as its reason, and the adapters' event
+  names the code (`AdyenTestPlatformRefusedError: <code>`).
+  A preparation refused for Adyen's test platform, or for a merchant profile
+  that is not turned on, not offered to your account, or whose key or checkout
+  page changed, throws `CheckoutPreparationError` with the API's code as its
+  `reason`.
+- `CardEncryptedError`: this processor encrypts the card in-page and its
+  registry entry does not (yet) say the vault can produce that ciphertext;
+  route the purchase to an Agentcard-issued card instead.
+- `UnsupportedModeError`: the registry requests a mode this SDK cannot finish
+  before an authorization exists. Upgrade. An unexpected approved mode instead
+  raises `PaymentOutcomeUnknownError` and requires reconciliation.
+- `PreparationRequiredError`: a direct `authorize()` call for a processor that
+  pays only through a prepared checkout (Fiserv) passed no preparation. Nothing
+  was created and nothing was charged; call `prepareCheckout()` first. The
+  adapters refuse such a request before it pauses, with the controller reason
+  `preparation_required`.
+- `SubstitutionError`: a `cse` approval could not be written into the paused
+  body (the four encrypted fields were not there). The request is failed and
+  the next one is judged afresh.
+
+## Building this package
+
+It declares **no dependencies**, so the workspace
+lockfile needs no importer entry for it (a new package with its own deps cannot
+be installed here without regenerating the lockfile, and a full regen drifts
+unrelated transitive versions). The voice module's streaming door is vendored
+from `packages/voice/src/core/stream.ts` by `scripts/generate-voice-stream.mjs`
+(`pnpm check:voice-stream` says when the copy has drifted). Build it with the
+workspace TypeScript:
+
+```bash
+cd packages/checkout && pnpm build && pnpm test
+```
+
+
+## Browser integration and merchant outcomes
+
+`attachToPlaywright` works with an existing Chromium page reached through
+`chromium.connectOverCDP`. Browserbase supplies `session.connectUrl`; Kernel
+supplies `browser.cdp_ws_url`; a custom browser must expose a compatible CDP
+endpoint. This is Agentcard's **direct SDK** path. Kernel's native Vault alias
+integration is a separate provider adapter with its own coverage and lifecycle;
+do not install both interceptors on the same checkout without validating how
+those routes interact.
+
+The local browser suite validates Chromium and nested cross-origin frames over
+both Playwright routing and a raw, session-aware CDP connection. It does not
+establish live Browserbase, Kernel, 3DS or merchant coverage. A raw page-scoped
+Playwright `CDPSession` is not the `CdpLike` type. Raw CDP must preserve the
+`sessionId` on every command/event and allow recursive target attachment.
+Initial arming errors reject `attachToCdp`; a child that cannot be armed remains
+paused and reports `browser_interception_unavailable` for operator recovery.
+
+Await attachment before clicking Pay. Both adapters stop waiting for browser
+setup after 30 seconds and throw `CheckoutAttachmentError` with
+`code: 'checkout_attachment_failed'` and `reason: 'timeout'`, `'closed'` or
+`'unavailable'`. Use `attachmentTimeoutMs` to choose a setup deadline from 1 to
+300000 milliseconds, separately from the approval's `timeoutMs`.
+Close the failed checkout page and create a fresh browser context before
+trying again. A late setup response cannot reopen the failed attachment or
+request approval; intercepted card requests remain blocked. A setup failure
+does not establish the status of any earlier purchase.
+
+Use a checkout context created with `serviceWorkers: 'block'`. Playwright cannot
+route requests intercepted by a service worker. The SDK rejects already active
+service workers, but that check cannot prevent a site from registering one
+later in an existing context configured to allow them. A browser extension's
+own worker, at a `chrome-extension://` URL, serves no site and does not count,
+so a cloud browser's default context that runs extensions (an agent, an ad
+blocker, a popup blocker) attaches as it is. Attach before entering
+card fields; keep the existing checkout tab. Separate popup tabs need their own
+attachment. A page route does not cover a popup's first navigation; a popup
+which submits payment on that navigation requires a separately validated
+context/browser-level integration. Existing `page.route` handlers must call
+`route.fallback()` when they do not handle a request; later routes have priority.
+
+Both adapters now return a controller; existing code that ignores the return
+value continues to work. Choose `requireMerchantResult: true` for a pilot:
+
+```ts
+const checkout = await attachToPlaywright(page, {
+  vault: agentcard, user, merchant, amount, currency,
+  requireMerchantResult: true,
+  onStateChange: state => recordState(state),
+  onUserAction: action => deliverPrivatelyToUser(action),
+  resolveMerchantResult: async state => readMerchantOrder(state),
+  paymentEndpoints: [
+    { origin: 'https://payments.example.com', pathname: '/submit', methods: ['POST'] },
+  ],
+});
+
+// Your existing agent dispatches checkout. Later, once the paused request resumes:
+const state = await checkout.reconcile();
+if (state.status === 'completed') await finishAgentTask(state);
+```
+
+`resolveMerchantResult` must verify the merchant's result for the original
+payment attempt. It returns one of:
+
+- `{ status: 'completed', orderId }`: merchant-confirmed success with a genuine order or receipt ID. Existing integrations keep this form.
+- `{ status: 'completed', confirmation: { kind: 'merchant_payment', authorizationId } }`: merchant-confirmed payment when no order or receipt ID is available. The ID must match the current checkout authorization.
+- `{ status: 'failed' }`: merchant confirmed the attempt failed; no successful payment/order exists.
+- `{ status: 'pending' }` or `{ status: 'unknown' }`: keep waiting or reconcile; never click Pay again.
+- `{ status: 'requires_user_action', reason: '3ds' | 'redirect' | 'other' }`: deliver your own browser live view or supported challenge UI to the user.
+
+For a merchant that confirms payment without returning an order ID, your
+resolver can return the explicit payment confirmation:
+
+```ts
+const checkout = await attachToPlaywright(page, {
+  vault: agentcard, user, merchant, amount, currency,
+  requireMerchantResult: true,
+  resolveMerchantResult: async state => {
+    const payment = await readOriginalMerchantPayment(state);
+    if (!payment.confirmed || !state.authorizationId) return { status: 'unknown' };
+    return {
+      status: 'completed',
+      confirmation: {
+        kind: 'merchant_payment',
+        authorizationId: state.authorizationId,
+      },
+    };
+  },
+});
+```
+
+`readOriginalMerchantPayment` is your merchant-specific check. The check must
+match the original payment request, amount, currency and selected card, and
+verify authoritative merchant success for that attempt. HTTP 200 alone, a card
+token, a success URL or text that anyone can open does not establish payment.
+Copying `state.authorizationId` without checking the payment is insufficient.
+The SDK checks the authorization binding; it does not independently authenticate
+the merchant evidence supplied by your resolver.
+
+Return one completion form at a time. The payment-confirmation form leaves
+`state.orderId` absent and exposes `state.confirmation` with the exported
+`MerchantPaymentConfirmation` type. Your consumer should finish on
+`state.status === 'completed'` and treat `orderId` as optional. A missing or
+mismatched authorization, or `{ status: 'completed' }` without either completion
+form, leaves the outcome unknown. Confirmed completion clears stale failure or
+authentication reasons and continues to block further payment submissions.
+Never invent an order ID from a token or authorization ID.
+
+The SDK does not infer order success from `authorized` or a tokenization reply,
+and does not claim to detect or solve arbitrary 3DS challenges. Your merchant
+resolver (or `checkout.requestUserAction('3ds')` when your browser observes it)
+drives that hook. Deliver `onUserAction` approval URLs privately: they are
+capabilities and never belong in general telemetry. Observer exceptions are
+isolated from the payment handoff.
+
+Native Stripe Checkout emits `checkout_blocked` before the existing `blocked`
+event when its local preparation rejects a request. Its
+`StripeCheckoutBlockedDetail` contains only fixed codes: `version: 1`,
+`processor: 'stripe'`, endpoint family, phase, stage, reason, optional validation code, gate state, and
+disposition. It contains no URLs, identifiers, request-derived field names or values, or exception text.
+
+| Field | Values |
+| --- | --- |
+| `endpoint_family` | `payment_methods`, `payment_page_confirm`, `other` |
+| `phase` | `tokenization`, `final`, `unknown` |
+| `stage` | `request_read`, `classification`, `claim`, `readiness`, `document`, `stub_response` |
+| `validation_code` | Shared-core `StripeCheckoutValidationCode`; present only for `request_validation_failed` |
+| `gate_state` | `fresh`, `stubbed`, `submitted`, `stopped` |
+| `disposition` | `active_claim_preserved`, `checkout_stopped` |
+
+`reason` is the exported `StripeCheckoutBlockReason` union. It identifies SDK
+claim and readiness failures, such as `duplicate_confirmation`, `document_changed`,
+or `attachment_not_ready`. A shared-core rejection reports
+`request_validation_failed` and a fixed `validation_code` identifying the failed
+check, or `unclassified` when no recognized code is available. Initial request
+classification uses phase `unknown`; a billing capture rejection uses
+`tokenization`, and a billing attachment rejection uses `final`.
+For example, `form_field_unknown` identifies an allowlist rejection without
+revealing the field name or value. Identifying that field requires a separate
+reviewed synthetic fixture; the code alone does not establish or fix a processor
+schema mismatch. `gate_state` records the state before the adapter handles
+the failure, though document validation may already have stopped the gate.
+
+`active_claim_preserved` means a valid duplicate was refused without invalidating
+the original request's claim. Do not cancel that checkout in response to the duplicate.
+`checkout_stopped` means the local preparation was retired; reconcile any existing
+authorization before another attempt. Neither disposition proves a payment outcome.
+
+With `requireMerchantResult`, subsequent card requests stay blocked after
+handoff. Stripe tokenization handoffs (`/v1/payment_methods`, `/v1/tokens`,
+`/v1/sources`, `/v1/confirmation_tokens`) always hold further recognized card
+requests, even when that option is false. A tokenization approval has no
+authoritative binding to a specific PaymentIntent, amount or currency, and the
+page cannot supply one. The SDK reports `awaiting_merchant` with reason
+`stripe_tokenization_unbound`, while ordinary browser traffic stays available.
+
+One follow-up can continue: the page's own card-free PaymentIntent confirm that
+pays with the approved token (`confirmCardPayment` with `payment_method: 'pm_...'`,
+`confirmPayment` with the confirmation token). The SDK asks the API, which reads
+the payment from Stripe and allows it only for the approved amount and
+currency, on the same Stripe account, paid with exactly the approved token.
+Allowed, the request continues untouched, the SDK emits `stripe_payment_continued`
+and the reason becomes `stripe_payment_continued`. One confirm continues per
+approval; every other follow-up, including an unrelated intent, a changed
+amount and a retry, stays blocked.
+Unrecognized merchant-server endpoints remain outside this guard unless listed
+in `paymentEndpoints`; this is not a guarantee against a merchant charging a
+saved token on its own server.
+A direct card-bearing PaymentIntent confirm remains supported with the backend's
+existing amount verification when `amount` and `currency` are supplied.
+
+Hosted-form submissions also always stay blocked because their payment outcome
+is unverified. `reconcile()` calls the resolver once, coalescing concurrent calls.
+After an explicit merchant-confirmed failure, the application may call
+`checkout.retryAfterMerchantFailure({ status: 'failed' })` to permit another
+attempt where the attachment permits recovery. This is an assertion from your
+merchant integration, not a timeout or a best guess. Completed orders, cancelled
+attachments and attachments that issued an unbound Stripe token cannot reset
+this way, including when the token's browser delivery acknowledgement was lost.
+Reconcile the merchant outcome and use a separately validated checkout flow;
+do not reuse that token in a new attachment as a workaround. Configuration and
+unsupported-mode failures require fixing the integration. Bank flows requiring
+another confirmation and other stored-token chains remain unverified.
+
+Worldpay, Bambora and Mercado Pago preparation requires SDK 0.6.0 or later and the matching API and Vault release.
+
+Prepare a Square, Braintree, Worldpay, Bambora or Mercado Pago checkout before the first Pay action so the cardholder can approve before the native card request starts. The API and Vault deployments must support the selected processor:
+
+```ts
+const checkout = await attachToPlaywright(page, {
+  vault: agentcard, user: 'your-user-id', merchant: 'Example merchant',
+  amount: 100, currency: 'USD',
+  onApprovalUrl: deliverPrivatelyToCardholder,
+});
+const preparation = await checkout.prepare({
+  psp: 'braintree',
+  environment: 'production', // Square, Braintree and Worldpay: production or sandbox
+});
+// The cardholder has consented and unlocked the same approval document.
+// No processor request or payment has started.
+await page.getByRole('button', { name: 'Pay', exact: true }).click();
+```
+
+`prepare()` is available on both Playwright and raw CDP controllers. It requires `amount` and `currency`, must precede the first recognized card request, and returns only when the cardholder's device is ready. It delivers the preparation URL through `onApprovalUrl` and `onUserAction`; binding the subsequent authorization sends no second approval link or SMS. The approval page on the cardholder's device must stay open. Its selected card, merchant origin, declared merchant, amount, currency, processor and environment bind one fresh request. The amount's authority is `agent`; a card token does not enforce the merchant's eventual charge amount.
+
+| Processor | `environment` | Fresh native request |
+| --- | --- | --- |
+| Square | `production` or `sandbox` | Matching Square `/v2/card-nonce` host |
+| Braintree | `production` or `sandbox` | Matching Braintree GraphQL host and guest `TokenizeCreditCard` mutation |
+| Worldpay | `production` or `sandbox` | Matching Access Worldpay host and `/sessions/card` |
+| Checkout.com | `production` or `sandbox` | Fresh guest-card JSON POST to `/tokens` on the matching API or card-acquisition-gateway host |
+| Bambora | `shared` | `/scripts/tokenization/tokens` on `api.bam.shift4api.net` or `api.na.bambora.com` |
+| Mercado Pago | `shared` | `api.mercadopago.com/v1/card_tokens` with a fresh card body |
+| Recurly | `shared` | Form-encoded POST to `/js/v1/token` on `api.recurly.com` or `api.eu.recurly.com` |
+| Spreedly | `shared` | Native iframe JSON POST to `/v1/payment_methods/restricted.json` on `core.spreedly.com` |
+| Adyen | `production` or `sandbox` | The Sessions `/checkoutshopper/v1/sessions/{id}/payments` POST on the matching Adyen host family (`sandbox` is `checkoutshopper-test.adyen.com` with a `test_` client key; `production` is the live hosts with a `live_` key), carrying a fresh card's four encrypted fields |
+| Fiserv | `production` or `sandbox`, with `merchantProfile` | The card frame's `/ch/payments-vas/v1/card-capture` POST on `connect.fiservapis.com` (`production`) or `connect-cert.fiservapis.com` (`sandbox`), carrying a new card's envelope under the key `merchantProfile` names |
+
+Use `environment: 'shared'` for Bambora, Mercado Pago, Recurly and Spreedly because the same endpoint serves test and live requests. Agentcard cannot establish the processor's test mode from that URL or a credential prefix. Configure test mode through the merchant's processor account when testing. Agentcard's own `sandbox` flag remains separate. Prepared Worldpay, Bambora, Mercado Pago and Recurly requests reject saved-card and recurring request bodies; a refused request retires the local preparation. Reconcile any existing merchant attempt before creating a new attachment.
+
+Prepare a Checkout.com checkout before the agent clicks Pay:
+
+```ts
+await controller.prepare({ psp: 'checkout_com', environment: 'production' });
+```
+
+Keep the phone approval page open, then click Pay once after readiness. Checkout.com Flow 1.228.0 gives its card iframe 12 seconds to return a token; approval before Pay leaves that interval for request binding and tokenization. Prepared requests must use an exact `/tokens` URL on `api.checkout.com` or `card-acquisition-gateway.checkout.com`, or the corresponding `.sandbox.checkout.com` host for `sandbox`. The request must describe a fresh card with a CVV and public-key authentication. Wallet, saved-card, reusable-token and recurring variants are refused. A native API fallback after the first CAG request cannot reuse approval. Match the actual merchant charge to the approved amount separately; a token does not enforce that amount.
+
+Prepare an Adyen Sessions checkout before the agent clicks Pay:
+
+```ts
+await controller.prepare({ psp: 'adyen', environment: 'production' }); // 'sandbox' for Adyen's test host
+```
+
+After approval, click Pay once. adyen-web encrypts the agent's placeholder digits and posts its Sessions `/payments` request; the SDK pauses it and binds it to the approval, the cardholder's device (still on the approval page) encrypts the approved card under the merchant's Adyen key, and the request continues from your browser with only the four encrypted fields swapped and `brand` dropped. Adyen answers your browser, so the merchant's order state is the outcome to poll. The bound request must be a fresh `scheme` card on the approved host family with a client key of that environment; a stored-card, single-blob or store-the-card request never uses the approval. Adyen Web's own 60-second request timeout then covers only the pause, the bind and the device's encryption.
+
+Prepare a Fiserv checkout before the agent clicks Pay:
+
+```ts
+// The attachment names the key's merchant: attachToCdp(cdp, sessionId, { ..., merchant: 'Agentcard sandbox' })
+await controller.prepare({ psp: 'fiserv', environment: 'sandbox', merchantProfile: 'agentcard_sandbox' });
+```
+
+`merchantProfile` names the key Agentcard reviewed for the merchant, and the cardholder's approval page names that key's merchant. The checkout's `merchant` must be that merchant's name (`Agentcard sandbox` for `agentcard_sandbox`), so the approval, the preparation and the authorization name one merchant; any other name is refused with reason `merchant_profile_mismatch` before any network call. After approval, click Pay once. Fiserv's card frame encrypts the agent's placeholder and posts its card capture; the SDK pauses the capture and binds it to the approval, the cardholder's device encrypts the approved card under that key, and the capture continues from your browser with only the envelope's four members swapped. Fiserv answers your browser, so confirm the order with the merchant.
+
+A card capture with no preparation is refused before anyone is asked: the controller reads `failed` with reason `preparation_required`, nothing reaches Fiserv, and a later `prepare()` on that attachment is refused, so attach again. Fastlane, ACH, gift and EBT captures on the same endpoint continue untouched and leave the preparation for the card capture. Every other body on that endpoint counts as a card capture, including one the SDK cannot prove card-free (not JSON, over 64 KiB, or a plaintext card): with no preparation it is refused the same way, and with one the bind refuses it as `checkout_changed`. So does a capture carrying a header that neither Fiserv's card frame nor the browser writes, such as the `traceparent` header tracing tools add: it is not the request the cardholder approved. Every Fiserv payment needs the cardholder's approval: the envelope carries no expiry, so Autopilot never pays one. Fiserv is off for every company until Agentcard turns it on for yours; until then the API serves your SDK no Fiserv recognizer, so nothing pauses on a Fiserv checkout, and `prepare()` fails with reason `processor_unavailable`. A merchant whose key Agentcard has not turned on yet fails with `unsupported_checkout`.
+
+Prepare a Spreedly checkout before submitting the merchant's card form:
+
+```ts
+await controller.prepare({ psp: 'spreedly', environment: 'shared' });
+```
+
+After approval, submit the form once. The Vault replaces the card fields on your device and sends the native request through an encrypted connection to Spreedly. The merchant's environment and signed session stay unchanged. The API, Vault, relay and preparation migration must support Spreedly before you use this flow; the API refuses preparations while its relay rollout flag is disabled.
+
+Initial coverage includes the hosted iframe's new-card request. Saved-card CVV updates, Express, wallets, bank accounts and gateway purchase APIs require separate support. A returned card token does not confirm payment; wait for the merchant's result before reporting success. Autopilot is unavailable for Spreedly.
+
+Prepare Recurly before clicking the merchant's payment button:
+
+```ts
+await controller.prepare({ psp: 'recurly', environment: 'shared' });
+```
+
+After approval, submit the merchant's form once. Recurly's native request timer starts with that submission. The SDK preserves the captured US or EU endpoint and accepts a new-card form only. Legacy JSONP, saved tokens, bank accounts, alternative payments and proactive authentication requests require separate support. Prepared requests also refuse nonempty Worldpay or Cybersource risk results because those sessions can depend on the original card. A nonempty co-badged network preference is also refused until the selected card’s supported networks can be checked. A card token does not confirm a donation, subscription or purchase; confirm the merchant's result before reporting payment success.
+
+### Use Checkout Pro in Mexico
+
+Attach the SDK before entering card fields on `www.mercadopago.com.mx`, then prepare the guest card checkout:
+
+```ts
+await controller.prepare({ psp: 'mercado_pago', environment: 'shared' });
+```
+
+The Vault checks the selected card's issuer using the merchant's current checkout configuration. Your browser receives the processor's original card-token response, and the SDK replaces the issuer in one native card association. The card number, security code and eight-digit prefix stay out of your SDK process. The encrypted relay carries the configuration lookup between the approval device and Mercado Pago.
+
+The selected card must have the same brand and card type as the native form. Missing or ambiguous configuration, changed checkout details, and a repeated card association stop continuation. Start a fresh checkout and approval after resolving the mismatch. Final Pay and merchant confirmation still follow your existing checkout integration.
+
+Use the matching SDK, API, Vault and relay releases together. The issuer correction covers the observed guest Checkout Pro flow in Mexico. CardForm or Bricks on merchant websites, other countries, installment changes and Autopilot need separate validation. Successful tokenization and issuer association do not establish a paid order; keep `requireMerchantResult` and a merchant receipt resolver when validating a purchase.
+
+Braintree's native `ClientConfiguration` GraphQL query can run before, during or after preparation without using the approval. Only a single `TokenizeCreditCard` mutation can consume the prepared Braintree checkout. Prepared requests require guest card tokenization with explicit `options.validate: false`; omitted validation options, saved-card fields and `validate: true` are refused. Other GraphQL operations, batches and compound mutations are blocked. Braintree's legacy REST fallback cannot consume a prepared authorization.
+
+Readiness lasts up to 30 seconds (`preparation.expiresAt`) and appears as `ready_to_submit`, with `paymentStatus: 'not_started'`. Trigger the caller-owned Pay action immediately after the promise resolves. Expiry, navigation, cancellation, an early request or a changed checkout fails closed. A preparation and its attachment are single use; reconcile any bound authorization before creating a new attachment. The SDK never clicks Pay, reuses a stale request, changes native request deadlines, or automatically retries a failed prepared checkout.
+
+After Pay, the processor's native deadline still covers fresh authorization binding, device replay and token handoff. A disconnected or backgrounded cardholder device, or a slow transport, can still miss it. A subsequent SCA challenge has its own lifetime after token handoff. If the page's own script abandons an unprepared `token` or `cse` request while the cardholder decides, the approval survives and answers the page's next request for the same purchase (see "The approval outlives the page's own request" above). If the frame that sent the request is removed, the document moves to another URL, the page closes or crashes, or a prepared request is abandoned, the attachment blocks further requests and tries to retire the pre-replay authorization; a started replay or unconfirmed cancellation remains unknown. Without `prepare()`, approval loading and human interaction still share the native deadline, so a delayed approval finishes the page's retry rather than its first request.
+
+Lost authorization polling, local approval timeouts, or interrupted browser
+handoffs produce `outcome_unknown` and block automatic retry. The thrown
+`PaymentOutcomeUnknownError` carries `authorizationId` when creation was
+acknowledged. `checkout.cancel()` stops the local attachment and polling; it
+does not revoke a pending approval link or undo a processor payment. Cancellation
+after an attempt starts is therefore unknown until reconciled. A cancelled
+attachment cannot restart.
+
+### Adyen merchants that take the card on their own server
+
+Some Adyen merchants have adyen-web encrypt the card into four fields and post them to their own server, which then charges the card through Adyen. No processor host is involved, so no recognizer matches that request. Agentcard reviews each such merchant as a merchant profile: its endpoint, the body rules of its card request, and the Adyen key the card must be encrypted under. The SDK arms every profile this build reviewed from the start, in `observe`, so the agent's dummy card never reaches a reviewed merchant, even before `syncRegistry()` runs or when it fails. `syncRegistry()` asks the API for each profile's status on your client (`merchant_profiles=1`), and a profile turns `enabled` only when the API serves it enabled with the same rules this SDK build reviewed and this build ships it enabled. Both adapters pause the profile's endpoint and any sibling of it (the same path under another query) from attach, and judge each request there against the profile's status at that moment.
+
+- A request that carries no encrypted card (a basket query, a preflight) continues as before.
+- A body the browser did not hand over (a blob or a file, which neither adapter can read) is not proven card-free, so any request but a `GET`, `HEAD` or `OPTIONS` that carries one is treated as a card request the profile cannot finish. Playwright reports a missing body the same way, so an empty body is treated alike in both adapters.
+- A profile in `observe` never pays. Its card request is aborted before it reaches the merchant, and the adapters report `merchant_profile_observed` with the profile, the templated URL, the verdict and `keyPathSha256`, the SHA-256 of the body's sorted key paths (never a value; `null` for a body that was not read), then `unsupported_checkout`. The controller reads `unsupported` with reason `merchant_profile_observe`, and no authorization exists. Both reviewed profiles, `dunelm_was_graphql` and `cinemark_initiate`, ship in `observe`.
+- A card request the profile cannot finish (storing the card, a stored card, another operation, three fields instead of four, a sibling endpoint, an unreadable body) is aborted with `unsupported_checkout` and the reason, and reads `unsupported` with reason `merchant_request_unsupported`.
+- The profile's own card request, once Agentcard enables the profile for your client and this build, pays only through a preparation for that profile. Without one it is aborted before any pause, prompt or authorization: the adapters report `blocked` with `preparation_required`, the controller reads `failed` with that reason, and `prepare()` is refused on that attachment, as after any first card request. Create a new attachment and prepare before Pay.
+
+```ts
+await controller.prepare({ psp: 'adyen', environment: 'production', merchantProfile: 'dunelm_was_graphql' });
+```
+
+The environment is the profile's (`production` for a live Adyen key). After approval, click Pay once. The SDK sends the API the profile id with the paused request (`merchant_hosted: { profile }`, `content-type` as the only header, never Autopilot), and the cardholder's device encrypts the approved card under the key Agentcard reviewed for that merchant. The paused request's URL and body reach the API with that create, as every processor's do: the API checks the body against the profile and the amount, then keeps only its SHA-256 and the templated URL, so anything else in the body (a gift card number, a session token, an idempotency key) passes through Agentcard once and is not stored. The approval comes back as a `cse` replay with `kind: 'merchant_hosted'`, and the request continues from your browser with the four fields swapped and adyen-web's `brand` dropped, but only if the live body still hashes to the body the API checked at create (`bodySha256`). A continuation the SDK refuses sends nothing, and the SDK retires the approval (`merchant_never_retried`) so the API stops serving its ciphertext. The merchant's server charges the card and answers its own page; confirm the order with the merchant.
+
+After hand-off, a `5xx` final answer (after any redirect), a network failure, or the page closing before an answer arrived reports `payment_outcome_unknown` and holds the checkout (`outcome_unknown`). So does the page sending the card request again before an answer arrived. Every later card request to the same profile is aborted, since it carries the agent's dummy card and a prepared approval is single use. Events name a merchant profile's endpoint by its templated URL (origin, path template and the profile's own query), so a user id, cart id or email in the merchant's URL never reaches telemetry.
+
+#### Testing against your own Adyen TEST account
+
+A test-mode client can run the same checkout against its own server and its own Adyen TEST account, before any reviewed profile is enabled. Declare your endpoint on the client, before any attach, as taking the card request of a profile this build reviewed:
+
+```ts
+const vault = new VaultClient({ clientId, clientSecret, sandboxMerchants: [
+  { profile: 'dunelm_was_graphql', endpoint: 'https://pay.your-test-shop.example/graphql', clientKey: 'test_...' },
+] });
+await controller.prepare({ psp: 'adyen', environment: 'sandbox', merchantProfile: 'dunelm_was_graphql' });
+```
+
+The adapters then pause that exact endpoint (and its siblings) and judge its requests with the profile's body rules, whatever the profile's status. The preparation and the create carry `sandbox_declaration: { endpoint, client_key, environment: 'test' }`, and both name your endpoint's host as the merchant. The API accepts a declaration only from a test-mode client of an organization Agentcard has turned declarations on for. Your endpoint must be HTTPS on a public domain name, outside every payment processor's host, Adyen's and Agentcard's domains, and the domain of every merchant Agentcard reviewed (so `www.dunelm.com` is refused along with `was.dunelm.com`); the client checks the same rule when it is constructed. The API reads the key's public key from Adyen's TEST platform itself. The Vault page names your host, holds the bound request's key to the one the preparation read, and encrypts only Adyen's documented test cards under a `test_` key: a real card is refused on the device. A live client, or an organization without declarations turned on, gets `sandbox_declaration_refused`, and a declaration the API cannot pay gets `sandbox_declaration_invalid`, both as `CheckoutPreparationError` reasons at `prepare()`.
+
+On a client that declares a profile, that profile id names the declaration: `prepare({ merchantProfile })` with that id pays your endpoint, never the reviewed merchant. A test-mode client can never pay a reviewed merchant on Adyen's live platform anyway; use a separate live client for that.
+
+A raw CDP runtime arms `vault.merchantProfileUrlPatterns()` after `syncRegistry()`, beside `vault.cardUrlPatterns()`, reads `vault.merchantProfileOf(url)` and `classifyMerchantRequest(profile, url, method, body)` for each paused request, and writes a merchant-hosted approval with `substituteMerchantHostedBody(body, replay)`. Never continue a card body, or a body you could not read, to a profile's endpoint that `authorize()` did not pay.
+
+### Unsupported endpoints
+
+`paymentEndpoints` is an explicit list supplied by the integrator after observing
+the site's payment requests. Each guard uses a canonical origin, exact path and
+mutation methods; it never examines or logs card bodies. If a guarded endpoint
+is not recognized, the SDK aborts it and reports `unsupported_checkout` /
+`unsupported` without creating an approval. Preflights and ordinary page traffic
+continue. There is no wildcard or intercept-all fallback, and no automatic
+conversion to an issued card. Unknown endpoints absent from these guards remain
+untouched; the SDK cannot identify every payment request from its URL.
+
+### Runnable integration and local verification
+
+`examples/existing-browser.mjs` runs against an existing provider session, using
+an application-owned driver module for the agent's actions, user communication
+and merchant-result resolver. Set `CHECKOUT_DRIVER` to that module's absolute
+path and `CHECKOUT_CDP_URL` to the provider connection URL; optionally select the
+existing tab with `CHECKOUT_PAGE_INDEX`. The module must export
+`prepareCheckout(page)`, `submitCheckout(page)`, `resolveMerchantResult({page,
+state})`, `onUserAction(action, {page})`, and `finishAfterPayment({page, orderId})`.
+`prepareCheckout` returns the checkout options above. `submitCheckout` dispatches
+the existing agent's approved purchase and returns without waiting for approval.
+Install `playwright-core` in the example's host project. The SDK itself keeps no
+runtime dependencies. The example is integration scaffolding, not a universal
+merchant driver and not evidence of a live provider checkout.
+
+```sh
+pnpm build
+pnpm test
+# Uses installed playwright-core, falling back to the monorepo backend dependency.
+# Set CHECKOUT_CHROME_PATH if Chromium is not installed in Playwright's cache.
+pnpm test:browser
+```
+
+The browser fixtures never contact a payment service. The general suite uses
+`psp.invalid`; the Stripe continuation suite forces `api.stripe.com` through an
+allowlisted loopback proxy and a temporary self-signed TLS stub (requires the
+`openssl` CLI). All other proxy destinations are rejected. These suites use an
+in-process Agentcard API fixture and loopback merchant pages. The preparation
+fixture denies all external traffic and waits beyond each modeled request deadline before any card request: eleven seconds for Square, sixty-one seconds for Braintree, and six and a half seconds for Worldpay, Bambora and Mercado Pago. Each fixture then checks one fresh request with an unchanged abort timer. The five-second timer matches the inspected Worldpay and Bambora source; the Mercado Pago timer is a test boundary, not a measured native deadline. The fixture exercises SDK ordering with native-shaped request bodies and synthetic responses, not processor acceptance. It proves nested-frame pause/resume, agent control during approval,
+post-payment tasks in the same page, decline/expiry/cancel, unknown-outcome retry
+blocking, explicit unsupported endpoint behavior, and blocking an immediate real-browser
+Stripe token-to-intent fetch chain, including unrelated first intents, changed
+amounts/currencies and delayed CDP acknowledgement. It does not test card
+cryptography, real bank authorization or a cloud-provider deployment.
+
+Provider/API references checked for this integration:
+[Playwright CDP](https://playwright.dev/docs/api/class-browsertype#browser-type-connect-over-cdp),
+[Playwright routing limitations](https://playwright.dev/docs/api/class-page#page-route),
+[Browserbase Playwright quickstart](https://docs.browserbase.com/welcome/quickstarts/playwright),
+[Kernel native Agentcard integration](https://www.kernel.sh/docs/integrations/payments/agentcard).
+
+
+The authenticated `GET /v2/checkout/coverage` endpoint describes direct-SDK
+processor modes, limitations and verification levels. Use
+`POST /v2/checkout/coverage/assess` with up to 1,000 uniquely identified cases:
+`{ cases: [{ id, request_url, method: "POST", scenario: "one_time", weight: 1,
+requires_3ds: false }] }`. Scenarios also include `save_card`,
+`subscription_initial` and `subscription_renewal`. The endpoint assesses request
+recognition, not purchases: `recognized`, `unsupported` and `unverified` are
+coverage classifications, `recognized_traffic_share` is traffic-weighted, and
+`purchase_success_rate` stays null without observed merchant outcomes. Do not
+substitute the assessor for a browser/merchant validation run or use native
+Kernel adapter coverage as evidence for this SDK's coverage.
+### Autopilot execution metadata
+
+When the cardholder has enabled an eligible spending rule in their vault, the same authorization can run through autopilot. The SDK keeps polling the existing authorization and returns optional `executionMode: 'autopilot' | 'user_approval'` and `grantId` metadata. Older API responses remain supported.
+
+`authorize()` accepts optional `executionMode` and `grantId` routing hints, sent as `execution_mode` and `grant_id`. These never establish permission to spend; the protected payment service checks the cardholder's signed rule. Autopilot suppresses `onApprovalUrl` while it is executing. A definite fallback to user approval delivers the existing authorization's URL once. A lost outcome remains `PaymentOutcomeUnknownError`; it does not create or submit a second payment.
+
+Use `executionMode: 'user_approval'` to require the existing confirmation flow. Without a selected card or grant, the backend can use exactly one eligible rule; ambiguous card selection keeps confirmation. A `grantId` restricts selection to that rule. The initial executor supports only the configured controlled Stripe test flow, and production remains disabled.
+
+For controlled hosted Stripe Checkout, both attachment functions accept `stripeCheckout: { sessionId, publishableKey, environment? }`. The default is TEST, requiring `cs_test_` and `pk_test_`. LIVE requires explicit `environment: 'production'`, a `cs_live_` Session and its `pk_live_` key. Both modes require `executionMode: 'autopilot'`, an explicit `grantId`, and a positive numeric USD `amount` in cents. The top-level document must be that exact Session on `https://checkout.stripe.com`, at `/c/pay/{sessionId}`, `/pay/{sessionId}`, `/g/pay/{sessionId}`, or `/f/pay/{sessionId}`. The SDK validates the existing URL without rewriting or navigating it. Direct `authorize()` calls use `stripeCheckoutEnvironment: 'production'` for the same explicit LIVE opt-in; the attachment functions pass it automatically.
+
+The SDK answers dummy-card tokenization locally, then sends the browser's final native confirmation through the shared core and enclave. The local response is preparation only: it creates no authorization and makes no processor request. The final result includes `checkoutSessionId` only after the selected grant, restricted terminal response, and captured amount have been checked. Continue to confirm the merchant order through the checkout controller.
+
+When Agentcard reports `autopilot_status: action_required` for the same authorization and grant, the SDK stops waiting and calls `onUserAction` with `reason: 'other'` and the authorization ID. The checkout controller records `requires_user_action` and holds further card requests. A direct `Agentcard.authorize()` call rejects with `PaymentOutcomeUnknownError` and reason `autopilot_action_required`. The existing authorization and reservation remain held; the SDK does not cancel or create another payment, return a processor payload, or infer a 3DS challenge. Your application's `resolveMerchantResult` can report the authoritative outcome of this same payment through `reconcile()`. Challenge execution and automatic continuation are not provided by this status report.
+
+The shared core carries a validated billing email from that tokenization request into the final confirmation before authorization. The email stays bound to the same Session and local PaymentMethod reference. Missing email stays missing; duplicate or conflicting values are refused. The SDK does not fill an email from the Agentcard account or invent one for the merchant.
+
+This integration requires matching backend and measured executor releases. TEST and LIVE have separate admission controls. LIVE also requires a newly authorized production grant on the selected real card, a fixed merchant account/profile with exactly one complete fixed-price USD line item and an independently reviewed operation qualification reference; the SDK option supplies none of these. LIVE deployment remains unqualified and disabled until that evidence exists. Exact observed totals do not establish atomic amount enforcement by Stripe. Subscriptions, saved-card flows and authentication continuations remain excluded. An unavailable preparation or uncertain result is declined or held for reconciliation; it cannot switch to a competing human-approval payment.
+
+The adapters also send the observed top-level HTTPS `merchantOrigin`, such as `https://shop.example`, without a path, query or trailing slash. Direct `authorize()` callers can supply that origin explicitly. It is a routing hint; the protected adapter independently verifies the processor account, payee and amount. If a browser cannot provide its top-level URL, an explicit `merchantOrigin` option can supply the hint; otherwise the regular approval path remains available.