@agent-cards/sdk 0.23.28 → 0.24.1

package/README.md

@@ -1,11 +1,12 @@
 # @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.
+Agentcard's SDK: one client, `Agentcard`, with three 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.
 
 | 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 |
+| `agentcard.buy` | Asks the Purchase API for a cart for a person you connected, places it by its hash, and reads the conversation |
+| `agentcard.approvals` | Creates a purchase for a person you connected, which they approve on Agentcard's page, and reads or waits for their decision |
 
 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.
 
@@ -15,73 +16,9 @@ Card data never enters your process, your logs or your network: your server hold
 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.
+Node 22 or any runtime with `fetch` 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. Leave it out and the client approves on Agentcard's page, as with `approval: 'sheet'`; a value that is neither `'sheet'` nor `'in_app'` throws `missing_approval_posture` at construction.
-
-### 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`. A prepared checkout pays only with the card the cardholder approved for it: there the call answers `card_not_stored` for a card a company added and `preparation_card_locked` for any other card.
-
-### 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
+## Webhooks
 
 Agentcard signs every delivery. Verify against the raw bytes and branch on `type`:
 
@@ -94,35 +31,40 @@ if (isCheckoutAuthorizationEvent(event) && event.type === 'checkout_authorizatio
 
 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
+## Connect a person
+
+Every purchase names the person who pays: `user_id` on `agentcard.buy`, `user` on `agentcard.checkout`. A person gets that id when they store a card in the Vault from a link your server mints:
+
+```bash
+curl -X POST https://api.agentcard.sh/api/v2/vault_sessions -H "Authorization: Bearer $ORG_TOKEN" -H "Content-Type: application/json" -d '{}'
+```
+
+Send the person the answer's `url`. When they finish, the `vault.session_linked` webhook carries their `user_id`, and `GET /api/v2/vault_sessions/{id}` returns it once `status` is `linked`. Store it, because every call below names it. `$ORG_TOKEN` is your client's token from `POST /api/v2/oauth/token`. The [Vault quickstart](https://docs.agentcard.sh/vault/quickstart) covers the whole flow, test cards included.
+
+## Buy through the Purchase API
 
-`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.
+`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. `user_id` is the id from [Connect a person](#connect-a-person).
 
 ```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 placed = await agentcard.buy.confirm({ user_id, conversation_id: turn.conversation_id, confirm: turn.cart.hash });
 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
+## Approve a purchase on Agentcard's page
 
-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`.
+`agentcard.approvals` creates a purchase for a person you connected and has them approve it on Agentcard's page. `user_id` is the id from [Connect a person](#connect-a-person); `request` is the processor's card request the purchase pays, or `'sandbox'` under a sandbox client.
 
 ```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
+const purchase = await agentcard.approvals.create({ user_id, merchant: 'Coffee', amount: 1250, currency: 'usd', request: 'sandbox' });
+// Send the person purchase.approval_url: they approve with Face ID, Touch ID or their master password.
+const result = await agentcard.approvals.awaitResult(purchase.id);    // { status: 'approved', approved_with: 'passkey' }
 ```
 
-`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`.
+`approvals.get(id)` reads where a purchase stands without waiting, and `approvals.cancel(id, { reason })` withdraws one the person has not decided, with `person_closed_sheet`, `person_changed_mind` or `business_cancelled`. `awaitResult` polls no faster than the interval the purchase names, waits out `slow_down`, and answers `{ status: 'timeout' }` after 60 seconds unless `timeout_ms` names another deadline. A live client refuses `request: 'sandbox'` with `sandbox_request_in_live` before any call.
 
 ## Browser purchases
 
@@ -176,10 +118,6 @@ await agentcard.checkout.attachToCdp(cdp, pageSessionId, { user: 'usr_123', merc
 
 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. A Shiji STS getTokenId is the exception: its approval answers only the request it was created from, and the SDK cancels it as `merchant_request_aborted` when the page abandons that request.
 
-### 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.
-
 ### Hold the card request until the person confirms the total
 
 `attachToCdp(…, { hold: true })` pauses the first card request and holds it with nothing created. `controller.hold.whenHeld()` resolves with what was held (the processor and the endpoint, never a body). Once the person confirmed the total and the page still shows it, `controller.release({ amount, currency, pageTotal })` creates the authorization at that amount: a live client answers the page with the device's replay, a sandbox client never sends the request on and resolves `approved_not_charged`. A page total that moved, or one you could not read (`pageTotal: null`), cancels the request instead. `upTo: true` releases at a ceiling while the page total stays at or under it. `controller.hold.cancel()` fails the request. A held request is cancelled before its processor's own wait runs out (Braintree 60 s, Bolt 20 s, 30 s for the rest), and every other card request, and every one after a decision, fails at once.
@@ -204,13 +142,7 @@ The three shipped builders are the Stripe shapes Agentcard completes from a dire
 
 ### 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.
+`@agent-cards/checkout` is this package's older name and re-exports it for one release. `VaultClient` constructs the same client as `Agentcard`; every top-level checkout verb (`syncRegistry`, `authorize`, `isCardRequest`, …) is also under `agentcard.checkout`.
 
 ## Credentials
 
@@ -235,8 +167,16 @@ what this package encapsulates.
 | | 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 |
+| Agentcard servers | no for a card the cardholder stored, only a request template and a token; yes for a card your company issued, for the one payment it pays |
+| Cardholder's device | yes, decrypts a stored card locally or receives your company's card from Agentcard, and calls the merchant directly |
+
+The cardholder's Vault keeps no copy of a card your company issued, only a link
+to it, so their device has nothing to decrypt. When the cardholder approves a
+payment with that card, Agentcard's servers fetch its number and CVC from the
+card's issuer and send them to the cardholder's device in the response to that
+approval. The servers hold the card in memory for that one response and never
+log or store it. Your agent and browser still see only the dummy card and the
+token.
 
 On a reviewed merchant's own card endpoint (mode `card_endpoint`, below) the
 device sends the card to the merchant through Agentcard's checkout relay, which
@@ -244,6 +184,18 @@ carries end-to-end TLS it cannot read. Agentcard's servers hold the paused
 request's session and the merchant's answer encrypted, for minutes, and hand
 each over once.
 
+Agentcard's own shopping agent (/buy) has one more lane, built and switched
+off, the typed card lane, which this package never runs in your process. Once
+it is on, at a store whose card request no swap can reach, the shopper approves
+Agentcard typing their card into the store's page, and Agentcard's card typer
+types it there and presses the store's Pay, in Agentcard's own hosted browser.
+The card reaches the typer sealed by the shopper's device, and your agent never
+sees it. Agentcard's backend and its checkout agent let go of that page before
+the card goes in and connect again only once the store's page settled after
+Pay, so the requests that carry the card reach the typer's connection alone.
+Until then, /buy answers such a store as it does today: the card form is not
+one it pays at.
+
 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.
@@ -294,6 +246,7 @@ Coverage is specific to the processor request format, merchant setup, browser tr
 | Amadeus Checkout (Air France, KLM) | dark: only for an org Agentcard enabled, and only through `prepare({ psp: 'amadeus_checkout', cardId })`. The Checkout Web SDK's card add pauses; every other action on its URL continues. Air France and KLM keep the expiry in their own form, so the agent types the stored card's real expiry there and the checkout pays only with that card. Every Data Collection Page store is refused as `amadeus_dcp_field_config_unreviewed`. No live purchase yet. See "Prepare an Amadeus Checkout card step" |
 | Paddle checkout (Paddle's card vault or TokenEx; any Paddle seller) | dark launch: after `vault.syncRegistry()`, and only for an org Agentcard has enabled. On a Paddle checkout whose card method names VGS, pay only through `prepare({ psp: 'paddle_vgs', environment: 'production' })` (`'sandbox'` for Paddle's sandbox) on an attachment whose `cardId` names the paying card; without one, `prepare()` fails with `card_required`. The frame's post to `vault.paddle.com/cards` pauses, the cardholder's device sends the card itself, and the frame receives the stored card's id; its second request after its 10-second timeout gets the same answer. Type `placeholderCard()`'s facts for that card into Paddle's form, and pass `amount` and `currency`, the total the cardholder approves. Only Visa, Mastercard and American Express cards are paid (`paddle_vgs_card_unsupported` otherwise), and a typed expiry or placeholder that is not the card's fails the create with `paddle_vgs_card_mismatch`. On the live vault, Agentcard pays a checkout at any Paddle seller's own https page; from any other page, such as `http://localhost:4000`, `prepare()` fails with `unsupported_checkout`. Paddle's vault keeps the card, so Paddle can charge it again without another approval, at a subscription's renewal for example. Paddle's `/pay` that follows names the approved card's first six and last four digits, expiry and brand: the SDK writes them over the ones Paddle's form read from the placeholder, and aborts a `/pay` that names another stored card or comes more than a minute later. On a Paddle checkout whose card method names TokenEx, call no `prepare()`: the SDK pauses Paddle's `/pay`, and once the cardholder approves it, writes the card the cardholder's device encrypted over the placeholder's. With a `paddle_vgs` preparation on the attachment, the SDK refuses that `/pay` with `checkout_changed`. A Paddle checkout that sends the card through Spreedly is not supported |
 | Paygent (`PaygentToken.js`; Fundex donation forms) | dark launch: only for an org Agentcard enabled, after `vault.syncRegistry()`, and only through `prepare({ psp: 'paygent', environment: 'production' })` (`'sandbox'` for Paygent's test host) before the press that sends the card: the script gives up on its token request 35 seconds after sending it. The request to `token.paygent.co.jp/n/token/request` pauses, the cardholder's device sends the card itself, and the page receives Paygent's single-use token. One approval sends one card request, so the SDK refuses a second press, and a request for a stored card's security code too. Pass `amount` and `currency`, the total the cardholder approves. On the live host the API accepts only a reviewed merchant at its reviewed page, under its reviewed name, merchant id and token key, and in its currency (Tokyo Chinese School at `https://fundexapp.jp`, in yen), and refuses any other before anyone is asked. The merchant runs 3-D Secure after the token in the agent's browser. No live payment has gone through this route yet |
+| ProcessOut (ProcessOut.js's card frame on `js.processout.com`) | dark launch: only for the company Agentcard turned ProcessOut on for, after `vault.syncRegistry()`, and only through `prepare({ psp: 'processout', environment: 'production' })` (`'sandbox'` for a `test-proj_` project) before the press that asks the frame for a token: the frame calls the page's error callback 20 seconds after that press. The frame's post to `api.processout.com/cards` pauses, the cardholder's device sends the card to ProcessOut itself, and the frame receives ProcessOut's card token, rebuilt from the card facts the page reads. A refusal inside a 2xx answer never reaches the frame as a token, and a request still unsent 12 seconds after the pause fails before the card leaves (`processout_send_window_closed`). Pass `amount` and `currency` above zero, the total the cardholder approves. A live project pays only a store Agentcard reviewed, at its reviewed page and under its reviewed name and project id, and Agentcard has reviewed none yet, so a live `prepare()` fails with `unsupported_checkout`. No ProcessOut payment has gone through this route yet |
 
 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()`),
@@ -301,7 +254,7 @@ 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,device_encrypt&capabilities=fiserv_card_capture,gmo_shared_pk,capture_context,juspay_txns.v1,datatrans_secure_fields_tokenize,authorize_net_dpm_form,pelecard_transaction,aci_split_card.v1,creditguard_pps_process,primer_payment_instruments,payrails_device_encrypt,converge_hpp_process,worldpay_eprotect_jsonp,wspay_confirm,shiji_sts_pinned_key,amadeus_checkout_actions.v1,worldline_mycheckout_form,verifone_card_capture,ekashu_hosted_payment_page,cybersource_sa_token_create,gravy_session_fields_put,moneris_hosted_tokenization,paddle_vgs_cards,paddle_tokenex_pay,redsys_hosted_payment_page,lyra_krypton_payment,payfast_card_pay,wix_payments_tokenize,paymongo_checkout_pay,paygent_token,pay_nl_card_token,hipay_vault_token,twoc2p_secure_pay,quickpay_hosted_payment_page,revolut_card_field,paypal_card_fields,gopay_card_form,payrexx_card_frame,comgate_hosted_payment_page,przelewy24_hosted_payment_page,makecommerce_card_frame,poynt_collect_nonce,tokenex_iframe_tokenize,transbank_webpay_hosted_payment_page,sumup_checkout_process,clover_card_token,eximbay_hosted_payment_page,toast_pinned_key,xendit_card_token,omise_card_token,paytrail_hosted_payment_page,fastspring_card_payment,openpay_tokenizer,barion_hosted_payment_page,paymob_checkout_pay,payu_latam_webcheckout_card,nexi_checkout_pay,pin_payments_card_token`
+`GET /v2/checkout/recognizers?modes=token,cse,hosted_form,device_encrypt&capabilities=fiserv_card_capture,gmo_shared_pk,capture_context,juspay_txns.v1,datatrans_secure_fields_tokenize,authorize_net_dpm_form,pelecard_transaction,aci_split_card.v1,creditguard_pps_process,primer_payment_instruments,payrails_device_encrypt,converge_hpp_process,worldpay_eprotect_jsonp,wspay_confirm,shiji_sts_pinned_key,amadeus_checkout_actions.v1,worldline_mycheckout_form,verifone_card_capture,ekashu_hosted_payment_page,cybersource_sa_token_create,gravy_session_fields_put,moneris_hosted_tokenization,paddle_vgs_cards,paddle_tokenex_pay,redsys_hosted_payment_page,lyra_krypton_payment,payfast_card_pay,wix_payments_tokenize,paymongo_checkout_pay,paygent_token,pay_nl_card_token,hipay_vault_token,twoc2p_secure_pay,quickpay_hosted_payment_page,revolut_card_field,paypal_card_fields,gopay_card_form,payrexx_card_frame,comgate_hosted_payment_page,przelewy24_hosted_payment_page,makecommerce_card_frame,poynt_collect_nonce,tokenex_iframe_tokenize,transbank_webpay_hosted_payment_page,sumup_checkout_process,clover_card_token,eximbay_hosted_payment_page,toast_pinned_key,xendit_card_token,omise_card_token,paytrail_hosted_payment_page,fastspring_card_payment,openpay_tokenizer,barion_hosted_payment_page,paymob_checkout_pay,payu_latam_webcheckout_card,nexi_checkout_pay,pin_payments_card_token,paymentwall_card_token,oceanpayment_hosted_payment_page,payplug_hosted_payment_page,processout_card_token,aps_custom_merchant_page,bluesnap_hosted_payment_fields,iyzico_checkout_form,midtrans_card_token,sbps_token_jsonp,tap_card_sdk_token,usaepay_payment_key,vtex_payments_card_payment,viva_smart_checkout_chargetoken,cardlink_vpos_hosted_payment_page,eghl_hosted_payment_page`
 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,
@@ -380,6 +333,42 @@ this build pauses the gateway link `secure.barion.com/Pay?Id=<payment id>` for
 the cardholder's device and fails every post a page it watches makes to the
 gateway. A merchant's server often sends the buyer to that link with a
 redirect, and only `attachToCdp` pauses a redirect.
+PayPlug's payment page (`payplug_hosted_payment_page`) is served the same way:
+this build pauses the page link `secure.payplug.com/pay/<payment id>` (or
+`/pay/test/<payment id>`) for the cardholder's device and fails every post a
+page it watches makes to PayPlug's page host. The link names no amount, so
+`authorize()` needs your `amount`, above zero, and the API takes it in euros
+alone (`currency: 'eur'`), the one currency PayPlug's page charges. One PayPlug
+payment takes one authorization across your company: a second one while the
+first awaits answers `duplicate_submission`, and one for a payment a card may
+already have gone to answers `payplug_payment_already_sent`. The API serves
+PayPlug to Agentcard's own company alone for now, and takes no PayPlug payment
+until Agentcard has reviewed the name and the PayPlug account a merchant's
+PayPlug page shows: until then it refuses every PayPlug link with
+`seller_unreviewed`, which is expected and not a setup error.
+Cardlink's VPOS (`cardlink_vpos_hosted_payment_page`), the payment page Greek
+banks give their merchants on `vpos.eurocommerce.gr`, `ecommerce.cardlink.gr`
+and `www.alphaecommerce.gr`, is served the same way: this build pauses the
+merchant's signed entry, a form post to `/vpos/shophandlermpi`, for the
+cardholder's device and fails every other post a page it watches makes to those
+hosts, the card page's own post to the same URL included. The entry names its
+amount in euros, and the API holds your `amount` to it exactly. The API serves
+the lane to Agentcard's own company alone for now. While the relay route stays
+closed, every Cardlink create answers `503 cardlink_vpos_relay_unavailable`
+before any prompt. Once the route opens, the API takes an entry only for a
+merchant Agentcard has reviewed by its mid on its host, one so far, and refuses
+every other entry with `seller_unreviewed`, whose answer names the `mid`,
+`vpos_host` and `result_host` a review needs. Both refusals are expected and not
+a setup error.
+eGHL's payment page (`eghl_hosted_payment_page`, sold as ADAPTIS) on
+`securepay.e-ghl.com` is served the same way: this build pauses the merchant's
+entry, a `GET` of `/IPG/payment.aspx` whose query names the payment, for the
+cardholder's device and fails every post a page it watches makes to eGHL's
+hosts, the card page's own post to the same address included. The entry names
+its amount, and the API holds your `amount` to it exactly. The API serves the
+lane to Agentcard's own company alone for now. While the relay route stays
+closed, every eGHL create answers `503 eghl_relay_unavailable` before any
+prompt, which is expected and not a setup error.
 Revolut Business's card field (`revolut_card_field`) is served on the same
 terms: this build pauses the frame's card payment on `merchant.revolut.com`,
 the cardholder's device sends it to Revolut itself, and the frame gets
@@ -429,6 +418,22 @@ page, the cardholder's device sends it to Omise itself with the real card, and
 the page gets Omise's token. The API pays only a merchant Agentcard reviewed
 for the page the request comes from. Omise's request names no price, so pass
 `amount` and `currency`, above zero: that is the amount the cardholder approves.
+VTEX Payments' card post (`vtex_payments_card_payment`) is served on the same
+terms, and only through `prepare({ psp: 'vtex_payments', environment: 'production' })`
+before Pay: Ollie's headless checkout, which some VTEX stores run, posts the
+card to the store's own VTEX vault, `<account>.vtexvault.com`, and gives the
+post 12 seconds. This build pauses that post, binds it to the approval, and
+refuses each later post on the same approval, Ollie's resends and its post to
+`api.vtexvault.com` included, so one approval sends the card once. The post
+names its price, which the cardholder approves; VTEX answers it with 201 and no
+body, so the payment's result comes from the checkout's next step, not from
+this answer. The API pays only a store Agentcard reviewed for the page. A paused
+post is read every 500 ms while Ollie waits, and one the cardholder's device has
+not sent 8 seconds after the pause fails in your browser with nothing sent
+(`CheckoutPreparationError`, `vtex_payments_send_window_closed`). A direct
+`authorize()` of that post names `pausedAt`, the moment it paused in epoch
+milliseconds. The adapters fill it, and a call without it throws before
+anything is created.
 Pin Payments' card request (`pin_payments_card_token`) is served on the same
 terms: this build pauses the card request Pin's Hosted Fields or Pin.js sends to
 `https://api.pinpayments.com/1/cards`, the cardholder's device sends it to Pin
@@ -437,6 +442,24 @@ merchant's server charges afterwards. The API pays only a Pin account Agentcard
 reviewed for the page the request comes from. Pin's request names no price, so
 pass `amount` and `currency`, above zero: that is the amount the cardholder
 approves.
+Paymentwall's card request (`paymentwall_card_token`) is served on the same
+terms: this build pauses the card request Paymentwall's card form sends to
+`https://pwgateway.com/api/token` (`https://api.paymentwall.com/api/brick/token`
+under a test key), from Paymentwall's hosted checkout or a merchant's own page,
+the cardholder's device sends it to Paymentwall itself with
+the real card, and the page gets Paymentwall's one-time token, which the
+checkout charges afterwards. The API pays only a Paymentwall merchant Agentcard
+reviewed for the page the request comes from. Paymentwall's request names no
+price, so pass `amount` and `currency`, above zero: that is the amount the
+cardholder approves.
+ProcessOut's card request (`processout_card_token`) is served on the same
+terms, through a prepared checkout only: this build pauses the card request
+ProcessOut.js's card frame sends to `https://api.processout.com/cards`, the
+cardholder's device sends it to ProcessOut itself with the real card, and the
+frame gets ProcessOut's card token, which the store's server charges
+afterwards. The API pays only a store Agentcard reviewed for the page the
+request comes from. ProcessOut's request names no price, so pass `amount` and
+`currency`, above zero: that is the amount the cardholder approves.
 FastSpring's checkout (`fastspring_card_payment`) is served on the same terms:
 this build pauses the card payment the checkout posts to
 `<store>.onfastspring.com/.../session/<id>/payment`, the cardholder's device
@@ -472,6 +495,14 @@ checkout shows, which the API holds to the payment's own amount and the device
 holds to Nexi's record. The SDK sends the checkout page's origin as
 `checkout_origin`, which for Nexi's hosted page is `https://checkout.dibspayment.eu`,
 and the API pays only a merchant reviewed for that page.
+Oceanpayment's hosted payment page (`oceanpayment_hosted_payment_page`) is served
+on the same terms: this build pauses the card post the page submits to
+`https://secure.oceanpayment.com/gateway/sendPay;jsessionid=<session>`, aborts every
+other post to Oceanpayment's hosts, and the cardholder's device writes the real card
+into the paused post and sends it through Agentcard's checkout relay. The post
+names no amount, so pass `amount` and `currency`, above zero: the total the page
+shows. The API takes only a test payment on Oceanpayment's sandbox today, because
+the post names neither the merchant nor the amount.
 CyberSource Secure Acceptance's token
 create (`cybersource_sa_token_create`) is served on the same terms too; every
 other company keeps the stop every build applies to a card posted to Secure
@@ -636,7 +667,8 @@ mode; the difference matters if you drive `authorize()` yourself.
   sends the card request to the merchant itself over Agentcard's checkout
   relay and reports the merchant's answer; `authorize()` resolves with
   `{ mode: 'card_endpoint', profile, status, headers, setCookies, body,
-  withheld }`. The adapters write each `Set-Cookie` into your browser
+  withheld, approved }`, where `approved` is the amount the cardholder approved,
+  in the currency's smallest unit. The adapters write each `Set-Cookie` into your browser
   host-only on the endpoint host and Secure, so none of them travels over
   plain http. A `Set-Cookie` whose `Domain` names a parent of the endpoint
   host that your browser already holds a cookie of that name on is written
@@ -689,6 +721,44 @@ mode; the difference matters if you drive `authorize()` yourself.
   `profile` and the `endpoint` origin, never the request's URL, body or
   session: the URL carries the merchant's cart and booking ids.
 
+  Nike's card frame stores the card under the checkout's id, and Nike charges
+  nothing until its page sends the order, `PUT
+  https://api.nike.com/buy/checkouts/v3/<checkoutId>`. So once an adapter asks
+  the cardholder to pay through Nike's profile, it holds every request to
+  `api.nike.com`. `attachToCdp` pauses it in every frame the attachment arms,
+  from the attach on, so a document already loaded when the cardholder is
+  asked is held too. At the ask it also arms every other page of the browser
+  context then open, and every frame in one, and the browser target, which
+  reaches a tab, frame, worker or shared worker this checkout did not open
+  once it loads after the ask: Chrome applies the browser-level pause only to
+  what loads after it. `attachToPlaywright` routes the page's browser context,
+  which reaches its pages, those already loaded included, but no shared or
+  service worker. A write there whose path a server may read as
+  under `/buy/checkouts/`, however it is spelled, is the order. One order goes
+  unchanged, only when its `request.totals.total`, a JSON number, and its
+  `request.currency` are the `approved` amount and the checkout still names
+  that approval as under way, and after it only a byte-identical retry. An
+  order that fails the amount rule, or comes while no approved amount was read,
+  fails in the browser, so Nike never charges the card: a checkout still under
+  way reads `failed` with a `merchant_order_` reason such as
+  `merchant_order_amount_mismatch`, and every later order under that approval
+  fails too. A second order, or one after the checkout was cancelled,
+  reconciled or retried, fails and leaves the state as it is. The events
+  `merchant_order_released` and `merchant_order_refused` name the
+  authorization, never the order. Every other request, and the order on an
+  attachment that never asked to pay through Nike's profile, continues
+  untouched. A browser that refuses the browser-level pause, a page or frame
+  `attachToCdp` cannot arm at the ask, or a context that refuses the route,
+  refuses the payment to Nike before anything is created. At the browser
+  target, in the pages armed at the ask and on Playwright's context route,
+  only the attachment that asked through Nike's profile last in that browser
+  context, for any attempt, judges Nike's order; in the frames it arms from
+  the attach on, each `attachToCdp` attachment judges every order itself. A
+  shared or service worker that started before the ask, which `attachToCdp`
+  lets run only when its `sharedWorkers` or `serviceWorkers` option allows
+  one, is not held. An attachment that has not asked holds nothing, and an
+  order sent from outside the browser never reaches the SDK.
+
   Some of these merchants' pages submit the card form as a page load rather
   than a fetch: the profile's `navigation` is `top`, or `frame` for a form
   inside an iframe, which is then judged by the iframe's own document. The
@@ -742,7 +812,7 @@ mode; the difference matters if you drive `authorize()` yourself.
 cannot finish is never paused; the API serves `hosted_form` and `device_encrypt`
 entries only to callers that ask.
 `syncRegistry()` also sends `SUPPORTED_CAPABILITIES`
-(`capabilities=fiserv_card_capture,gmo_shared_pk,capture_context,juspay_txns.v1,datatrans_secure_fields_tokenize,authorize_net_dpm_form,pelecard_transaction,aci_split_card.v1,creditguard_pps_process,primer_payment_instruments,payrails_device_encrypt,converge_hpp_process,worldpay_eprotect_jsonp,wspay_confirm,shiji_sts_pinned_key,amadeus_checkout_actions.v1`),
+(the `capabilities=` list under "Supported processors"),
 the dark-launch half of the same negotiation: the API serves a processor gated
 behind a capability only to a build that declares it, for a company Agentcard
 turned that processor on for, and the built-in list never holds one, so the SDK
@@ -1085,8 +1155,7 @@ 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 build writes the SDK's copies of
-payment-core's rules (`src/*.generated.ts`), the voice module's streaming door
-from `packages/voice/src/core/stream.ts`, and the Kernel kit's
+payment-core's rules (`src/*.generated.ts`) and the Kernel kit's
 `examples/preflight/kernel-native/inventory.json`. Git ignores those files, so
 build before you test, with the workspace TypeScript:
 
@@ -1280,7 +1349,7 @@ with the Card Element after `createPaymentMethod`) has it sent with every
 `payment_method_data` field removed and the approved `payment_method` in their
 place: the SDK asks the API with exactly that body and continues the page's
 request with it. The API allows it only for an approval the cardholder gave on
-the Vault page, not by voice, with no `amount` (a SetupIntent charges
+the Vault page, with no `amount` (a SetupIntent charges
 nothing), paid with exactly the approved payment method on the same Stripe
 account, and a SetupIntent Stripe reports still confirmable. Allowed, the SDK
 emits `stripe_setup_continued` with
@@ -1358,7 +1427,15 @@ Prepare a Checkout.com checkout before the agent clicks Pay:
 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.
+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 URL that Checkout.com's card fields send the card to:
+
+- `/tokens` on `api.checkout.com` or `card-acquisition-gateway.checkout.com`.
+- `/tokens` on your account's own API host, named by its base URL prefix, such as `4k2njisl.api.checkout.com`. Frames sends the card there when you set `baseURLPrefix`.
+- `/cag/tokens`, or `/tokens` after a failed gateway call, on `devices.api.checkout.com` or under your prefix, such as `4k2njisl.devices.api.checkout.com`. Flow sends the card there when its payment session turns on Checkout.com's devices API, as the hosted payments page does.
+
+Any alphanumeric prefix works. For `sandbox`, each host is its `.sandbox.checkout.com` counterpart, such as `4k2njisl.api.sandbox.checkout.com`. 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:
 
@@ -1462,6 +1539,24 @@ An attachment keeps no memory of an earlier one. The API reads each checkout fro
 
 Once the card-number request is answered, ACI holds the real card on that checkout for up to 30 minutes, and the checkout id is what lets anyone post `/payment` against it, so event URLs show it as `{checkoutId}`. The `/payment` check runs in your browser: it holds an honest agent to the approved card, and the merchant's order state is the outcome to confirm. Autopilot is unavailable for ACI.
 
+### Pay a BlueSnap Hosted Payment Fields checkout
+
+BlueSnap's Hosted Payment Fields send the card in three requests too: the card number frame, the expiry frame and the code frame each send their own field as a JSON `PUT` to the merchant's token, `https://ws1.bluesnap.com/services/2/payment-fields-tokens/<token>` (`ws2` for a token ending `_2`, `sandpay` for BlueSnap's sandbox). BlueSnap launches dark: `syncRegistry()` declares `bluesnap_hosted_payment_fields`, the API serves BlueSnap only to an SDK that declares it, and only for Agentcard's own company.
+
+Pass `amount` and `currency`, above zero: the request names no price, so that is the amount the cardholder approves. Type a placeholder card of the paying card's network. The SDK:
+
+- pauses the card number request, which the number frame sends when its field loses focus. The cardholder's device sends it to BlueSnap with the real number, expiry and code, and the page receives BlueSnap's card data.
+- holds the page's own expiry and code requests, which the frames send when the page submits, and answers them with that answer, so the placeholder values never reach BlueSnap (`split_card_leg_absorbed`). They fail when the card number request fails, or when none begins within 5 seconds (`split_card_leg_unanswered`).
+- refuses a second card number request on the same token (`split_card_reused`), a saved card's request (`bluesnap_saved_card`), and anything else on the token's URL. The page's own retry of the card number request, sent again while the cardholder is still deciding, gets the approval's answer.
+
+The store's server charges the token afterwards, and its charge can ask BlueSnap to keep the card. So a live BlueSnap payment takes only a card the person stored, never one a company added (`card_not_stored`), and the approval says the store can keep it.
+
+### Pay a Paystack checkout
+
+Paystack's hosted checkout (`checkout.paystack.com`) sends the card in one form `POST` to `https://standard.paystack.co/charge/`, as `clientdata`: the card number, code and expiry encrypted under the one RSA key Paystack's page carries, with the card's last four digits beside it. Paystack launches dark: `syncRegistry()` declares `paystack_pinned_key`, the API serves Paystack only to an SDK that declares it, and only for Agentcard's own company.
+
+Pass `amount` and `currency`, above zero: the charge names no price, so that is the amount the cardholder approves. Type a placeholder card of the paying card's network, since Paystack's page reads the card's first six digits before the charge. The SDK pauses the charge, and the cardholder's device encrypts the real card under the same pinned key and sends the charge to Paystack itself. The page receives Paystack's answer: paid, declined, or the issuer's 3-D Secure step, which the page runs in the agent's browser. A charge that keeps the card (`paystack_saved_card`), starts a plan (`paystack_subscription`) or carries a PIN is refused before anything is created. Autopilot is unavailable for Paystack.
+
 ### Use Checkout Pro in Mexico
 
 Attach the SDK before entering card fields on `www.mercadopago.com.mx`, then prepare the guest card checkout: