@agent-cards/sdk 0.23.9 → 0.23.11

package/README.md

@@ -61,7 +61,7 @@ One choice per business, not per purchase; there is no default, and a client bui
 
 ### 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`.
+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
 
@@ -260,9 +260,9 @@ Coverage is specific to the processor request format, merchant setup, browser tr
 | ACI Worldwide COPYandPAY (Halfords) | dark launch: served only after `syncRegistry()` and only for an org Agentcard enabled; prepared checkout only. The card-number request is replayed from the cardholder's device, the page's own CVC and expiry requests are answered locally, and `/payment` continues once. See [Pay an ACI COPYandPAY checkout](#pay-an-aci-copyandpay-checkout) |
 | 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 |
-| Worldline MyCheckout | implemented (mode `hosted_form`) and off until Agentcard turns it on for your company: the card form on Worldline's hosted payment page, a top-level form POST to `/checkout` on `payment.pay1` or `payment.pay2` under `checkout.worldline-solutions.com` (pre-production: `payment.pay1.preprod` and `payment.pay2.preprod`). The cardholder's device submits Worldline's form with the approved card; the paused navigation resolves to the synthetic page, and you poll the merchant's order state. The form names no amount, so pass `amount` and `currency`, above zero: that is what the cardholder approves. A card submit with a checked "remember" box, a Google Pay token or a Click to Pay answer is refused. Google Pay and Click to Pay payments that carry no card number continue untouched, as the page's cancel and its other payment methods do: no authorization, no prompt. A MyCheckout page on a merchant's own subdomain is not recognized. No live merchant purchase is verified yet |
-| Verifone eCommerce (verifone.js) | implemented (mode `cse`, prepared checkout only) and off until Agentcard turns it on for your company: the SDK pauses a request at a merchant whose page encrypts the card with verifone.js and posts it to the merchant's own server only when Agentcard reviewed that merchant as a Verifone profile. The Container Store is the one profile, in `observe`, and Agentcard has reviewed neither its card request nor its key yet, so the SDK reports and aborts a request there that carries a verifone.js blob, and nothing pays (see "Verifone merchants that encrypt the card in the page"). Agentcard has not verified a live merchant purchase 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 |
+| Worldline MyCheckout | implemented (mode `hosted_form`) and off until Agentcard turns it on for your company: the card form on Worldline's hosted payment page, a top-level form POST to `/checkout` on `payment.pay1` or `payment.pay2` under `checkout.worldline-solutions.com` (pre-production: `payment.pay1.preprod` and `payment.pay2.preprod`). The cardholder's device submits Worldline's form with the approved card; the paused navigation resolves to the synthetic page, and you poll the merchant's order state. The form names no amount, so pass `amount` and `currency`, above zero: that is what the cardholder approves. A card submit with a checked "remember" box, a Google Pay token or a Click to Pay answer is refused. Google Pay and Click to Pay payments that carry no card number continue untouched, as the page's cancel and its other payment methods do: no authorization, no prompt. A MyCheckout page on a merchant's own subdomain is not recognized. On a page that asks the shopper to choose a card product first, the adapters hold the card submit to that product: Worldline's IIN lookup on the agent's placeholder can switch the form to another product of the same network (CLZ's page read the Visa placeholder as Visa Electron), and a submit whose `paymentProductId` is not the product chosen is aborted before any create, with a `blocked` event, `worldline_mycheckout_product_changed` (`worldline_mycheckout_product_missing` when it names none), without holding the attachment. `placeholderCard({ psp })` returns a processor's own placeholder for the card's network where one is reviewed; none is yet for Worldline, so its Visa placeholder can still be read as Visa Electron, and that submit is then refused. No live merchant purchase is verified yet |
+| Verifone eCommerce (verifone.js) | implemented (mode `cse`, prepared checkout only) and off until Agentcard turns it on for your company: the SDK pauses a request at a merchant whose page encrypts the card with verifone.js and posts it to the merchant's own server only when Agentcard reviewed that merchant as a Verifone profile. The Container Store is the one profile, in `observe`, and Agentcard has reviewed its card request but not its key yet, so the SDK reports and aborts a request there that carries a verifone.js blob, and nothing pays (see "Verifone merchants that encrypt the card in the page"). Agentcard has not verified a live merchant purchase yet |
+| Gravy (Gr4vy) Secure Fields | dark launch: for an org Agentcard has enabled, after `vault.syncRegistry()`, which declares `gravy_session_fields_put`; for any other org the SDK leaves Gravy's requests alone and the request continues to Gravy untouched. The card request is Secure Fields' update of a checkout session: a JSON `PUT` to `/checkout/sessions/<session id>/fields` on the merchant's own host `api.<merchant>.gr4vy.app` (sandbox: `api.sandbox.<merchant>.gr4vy.app`), sent from Gravy's hidden controller frame and carrying `payment_method.number`, `payment_method.expiration_date` as one `MM/YY` value and `payment_method.security_code`. The SDK pauses that `PUT`, never a `POST` to the same URL; the cardholder's device sends the card as the same `PUT`, and the frame receives Gravy's answer, a `204` with no body. The request names no amount, so pass `amount` and `currency`. 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 |
 | GMO Payment Gateway | dark launch (mode `token`): only for an org Agentcard has enabled; see [Pay a GMO Payment Gateway checkout](#pay-a-gmo-payment-gateway-checkout) |
 | CyberSource Flex Microform | dark launch: Microform 2.12.1 card fields only, after `vault.syncRegistry()`, and only for an org Agentcard has enabled. For any other org the API does not serve the recognizer, so nothing pauses there. The cardholder's device seals the card for CyberSource and the card field receives the transient token. Validated in local Chromium; no live merchant purchase yet. See [Pay a CyberSource Flex Microform checkout](#pay-a-cybersource-flex-microform-checkout) |
 | Juspay Express Checkout | dark launch: the new-card flow Swiggy's website sends from its own page, for an org Agentcard has enabled, after `vault.syncRegistry()`. Validated in local Chromium with no live merchant purchase yet; see [Pay a Juspay checkout](#pay-a-juspay-checkout) |
@@ -272,11 +272,12 @@ Coverage is specific to the processor request format, merchant setup, browser tr
 | Pelecard (Iframe/Redirect 2.0) | dark: paused only for an org Agentcard enables for Pelecard, in test mode only. One-time card payments on `gateway21` and `gateway20.pelecard.biz`; pass `amount`, `currency` and the page's total as `pageAmount`. See [Pay a Pelecard checkout](#pay-a-pelecard-checkout) |
 | CreditGuard (Hyp PPS hosted payment page) | dark launch, prepared checkout only (see "Pay a CreditGuard checkout"): served to this build (`capabilities=creditguard_pps_process`) only for a company Agentcard enabled for it, and prepared or paid only for that company. The cardholder's device sends the card and the page reads CreditGuard's answer. 3-D Secure, OTP, installments, save-my-card and currency conversion are refused. No UAT or live capture yet |
 | Primer (Web SDK v2 hosted fields; Printful, GetYourGuide) | dark launch (mode `token`): only for an org Agentcard has enabled; see [Pay a Primer checkout](#pay-a-primer-checkout) |
-| Payrails web SDK v6 (Blacklane) | dark launch (mode `device_encrypt`): only for an org Agentcard has enabled, and only the card form's single-use save until card-on-file consent exists; see [Pay a Payrails checkout](#pay-a-payrails-checkout) |
-| Elavon Converge (Hosted Payment Page) | dark: paused only for an org Agentcard enables for Converge, always with the cardholder's approval, never autopilot. One credit card sale in US dollars per payment page on `api.convergepay.com` (`api.demo.convergepay.com` in Converge's demo environment); no amount needed. See [Pay an Elavon Converge payment page](#pay-an-elavon-converge-payment-page) |
-| WSPay Components (WSPay's build of Monri Components) | dark launch: the card frame's confirm of a new card for a one-time payment only, after `vault.syncRegistry()`, with `amount` and `currency`, and only for an org Agentcard has enabled; for any other org the SDK leaves WSPay's requests alone. The cardholder's device sends the card to WSPay and the frame receives WSPay's answer. A confirm that asks WSPay to keep the card on file is refused, and Valamar asks on every booking. Validated in local Chromium against a model of the card frame; no WSPay sandbox run or live merchant purchase yet. See [Pay a WSPay Components checkout](#pay-a-wspay-components-checkout) |
-| Shiji STS (MyCheck Wallet V3; La Quinta by Wyndham) | dark launch, mode `cse` under a pinned key, and only for an org Agentcard has enabled. Every card request is refused in the browser today (`shiji_sts_keep_on_file`): the card token a hotel booking mints guarantees the stay, and Agentcard cannot yet ask the cardholder to let the hotel keep the card. See [Shiji STS](#shiji-sts-mycheck-wallet-v3) |
-| Amadeus Checkout (Air France, KLM) | dark: only for an org Agentcard enabled, and only through `prepare({ psp: 'amadeus_checkout' })`. The Checkout Web SDK's card add pauses; every other action on its URL continues. Air France's and KLM's add is refused as `amadeus_merchant_held_expiry` and every Data Collection Page store as `amadeus_dcp_field_config_unreviewed`, so neither merchant completes yet. See "Prepare an Amadeus Checkout card step" |
+| Payrails web SDK (Blacklane, FlixBus) | dark launch (mode `device_encrypt`): only for an org Agentcard has enabled, and only the card form's single-use save and its single-use payment until card-on-file consent exists; see [Pay a Payrails checkout](#pay-a-payrails-checkout) |
+| Elavon Converge (Hosted Payment Page) | dark: paused only for an org Agentcard enables for Converge, always with the cardholder's approval, never autopilot. One credit card sale in US dollars per payment page on `api.convergepay.com` or `www.convergepay.com` (`api.demo.convergepay.com` in Converge's demo environment); no amount needed. See [Pay an Elavon Converge payment page](#pay-an-elavon-converge-payment-page) |
+| Moneris Hosted Tokenization (Moneris's card frame; Raisin donation pages) | dark launch: after `vault.syncRegistry()`, and only for an org Agentcard has enabled, the SDK pauses the frame's post to `/HPPtoken/request.php` on `www3.moneris.com` or `gateway.moneris.com` (`esqa.moneris.com` for a test row) when it carries the card number, expiry and CVD, always with the cardholder's approval. A live payment needs a merchant Agentcard reviewed: the profile id the frame names must be one pinned for the checkout page's origin (Jack.org's Raisin page today), or the create answers `unsupported_checkout`. A frame that leaves the expiry or CVD to the merchant's page, or a post to any other `request.php` URL, fails in the browser with a `blocked` event, `request_without_card`. The cardholder's device sends the card through the checkout relay, and the page gets Moneris's temporary token, which the merchant charges from its own server: pass `amount` and `currency`, the total the cardholder approves. Moneris Checkout (`/chkt/`, `/chktv2/`) is not supported |
+| WSPay Components (WSPay's build of Monri Components) | dark launch: the card frame's confirm of a new card, after `vault.syncRegistry()`, with `amount` and `currency`, and only for an org Agentcard has enabled; for any other org the SDK leaves WSPay's requests alone. The cardholder's device sends the card to WSPay and the frame receives WSPay's answer. A confirm that asks WSPay to keep the card on file, as Valamar's does on every booking, is paid only as a hotel's EUR 1.00 card guarantee with a card the cardholder stored. Validated in local Chromium against a model of the card frame; no WSPay sandbox run or live merchant purchase yet. See [Pay a WSPay Components checkout](#pay-a-wspay-components-checkout) |
+| Shiji STS (MyCheck Wallet V3; Wyndham's booking pages) | dark launch, mode `cse` under a pinned key, and only for an org Agentcard has enabled. The card token a hotel booking mints guarantees the stay, so the cardholder approves with a card they stored, under a line that says the hotel can keep it on file. See [Shiji STS](#shiji-sts-mycheck-wallet-v3) |
+| 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" |
 
 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()`),
@@ -284,7 +285,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`
+`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`
 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,
@@ -307,7 +308,9 @@ cardholder's device and fails every other post your browser makes to NMI, so
 NMI never sees the card your agent typed. 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
-Acceptance.
+Acceptance. So is Gravy's session fields `PUT` (`gravy_session_fields_put`):
+this build pauses that `PUT` and only that method, and for every other company
+the request continues to Gravy untouched.
 
 ## Modes
 
@@ -355,10 +358,12 @@ mode; the difference matters if you drive `authorize()` yourself.
   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
+  `substituteFiservEnvelope(body, substitutions, url)`, `url` being the paused
+  capture's own, 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 one Agentcard
+  pinned for that capture, and for a capture under a credentials session's key
+  when `url` is absent or is not the capture endpoint. 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, Authorize.Net DPM and SIM). The processor's
@@ -397,13 +402,16 @@ mode; the difference matters if you drive `authorize()` yourself.
   per-session key that the paused request does not carry: it came in the
   Payrails init payload the merchant's backend handed the page. The adapters
   read that payload from the page's own XHR and fetch answers and send its key
-  with the create as `request.payrails.encryption_public_key`; a caller that
-  runs its own interception passes it the same way, and a Payrails save
-  without it throws before anything is created. The cardholder's device
-  encrypts the real card under that key and sends the save to Payrails
-  itself, and `authorize()` resolves with `{ mode: 'device_encrypt', status,
-  headers, body }`: Payrails' 201, rebuilt from an allow-list, to fulfill the
-  paused request with as in `token`. The ciphertext the device made never
+  with the create as `request.payrails.encryption_public_key`, and for a
+  card-form payment its `holderReference` as `request.payrails.holder_reference`;
+  a caller that runs its own interception passes them the same way, and a
+  Payrails request without them throws before anything is created. The
+  cardholder's device encrypts the real card under that key and sends the save
+  or payment to Payrails itself, and `authorize()` resolves with
+  `{ mode: 'device_encrypt', status, headers, body }`: Payrails' 201 for a save,
+  or for a payment its 202 naming the authorize action of that same payment (its
+  own execution, on its own host), rebuilt from an
+  allow-list, to fulfill the paused request with as in `token`. The ciphertext the device made never
   reaches your runtime. Any other answer throws `PaymentOutcomeUnknownError`
   (`payrails_answer_unconfirmed`), and autopilot never runs this mode. See
   [Pay a Payrails checkout](#pay-a-payrails-checkout).
@@ -573,13 +581,15 @@ one. `amountAuthority` on every replay is `stripe_payment_intent`,
 
 ### Shiji STS (MyCheck Wallet V3)
 
-La Quinta by Wyndham takes the card through MyCheck's wallet, whose Shiji proxy
+Wyndham's booking pages (every brand on `www.wyndhamhotels.com`, La Quinta and
+Days Inn among them) take the card through MyCheck's wallet, whose Shiji proxy
 (`sts.proxy.v2.1.js`) encrypts the PAN and the `MM/YY` expiry with RSA PKCS#1
-v1.5 under a key Shiji hardcodes and posts
-`{accessToken, pan, expires, keySequence}` to
+v1.5 under a key Shiji hardcodes and posts `{accessToken, pan, expires}` to
 `/v1/token/getTokenId` on `iframe.vault.eu.prod.shijipayment.com` (sandbox:
 `iframe.vault.eu.uat.shijipayment.com`), then the CVV the same way to
-`/v1/token/getCvvId`. The processor ships dark: `syncRegistry()` declares
+`/v1/token/getCvvId` under the merchant's `client_key`. Wyndham's wallet sends
+no `keySequence` on `getTokenId`, and the API admits that shape only from
+Wyndham's booking page. The processor ships dark: `syncRegistry()` declares
 `shiji_sts_pinned_key` (`SUPPORTED_CAPABILITIES`), and the API serves the
 recognizer only to an org Agentcard has enabled for it. Every other org's SDK
 recognizes neither URL, and the page's requests go through untouched, as
@@ -601,15 +611,20 @@ anything pauses:
   is answered from it. Shiji uses one key for every merchant, so a request of
   the same shape could name another merchant's `accessToken` and
   `keySequence`, and the proxy's own request never times out.
-- While Agentcard cannot ask the cardholder for consent to a hotel keeping the
-  card, every such `getTokenId` is refused before any create or prompt:
+- The hotel keeps the card token to guarantee the stay. The approval page says
+  the merchant can keep the card on file and charge it again later without
+  another approval, and it offers only a card the cardholder stored: the API
+  refuses a card a company added (409 `card_not_stored`), at the create when
+  the runtime names one and at the approval. If Agentcard turns the card-on-file
+  rule off, every such `getTokenId` is refused before any create or prompt:
   `unsupported_checkout` with reason `shiji_sts_keep_on_file`, and the
   attachment reads `unsupported`. Nothing reaches Shiji.
 - A `getCvvId` never prompts. It continues with the device's CVV only when it
   follows the `getTokenId` this attachment continued, from the same frame,
-  with the same `accessToken`, under a `keySequence` the API reviewed as the
-  booking page's own `getCvvId` key and served with the approval, within 120
-  seconds, and only once (a `companion_continued` event). Every other
+  with the same `accessToken`, under a `keySequence` whose SHA-256 the API
+  reviewed as the booking page's own `getCvvId` key and served with the
+  approval (`shiji_sts_companion.key_sequence_sha256`), within 120 seconds, and
+  only once (a `companion_continued` event). Every other
   `getCvvId` is refused as `shiji_sts_companion_unbound`,
   `shiji_sts_companion_expired` or `shiji_sts_companion_used`, so the agent's
   placeholder CVV never rides beside a real card and the real one goes to no
@@ -683,15 +698,23 @@ is gone resolves as `PaymentOutcomeUnknownError` with reason
   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. An Authorize.Net DPM or SIM form adds more
-  reasons (`duplicate_field`, `not_a_card_payment`, `relay_response_off`,
-  `form_step`, `special_flow`, `merchant_credential`,
-  `test_request_on_live_host`, `malformed_field`), terminal the same way,
+  `reason` of `stored_credential`, `not_a_sale`, `special_flow` 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, installments or recurring
+  billing, a callback URL off the merchant's host other than the processor's
+  own result page: name the merchant by its hostname when the form carries
+  callback URLs); all three are terminal for that page. A Tranzila form is
+  also refused with `duplicate_field` (a field posted twice with different
+  values: Tranzila acts on the last copy) or `malformed_field` (a field name
+  Tranzila's server reads as another name, such as `cred.type`, or an
+  `altcha` field holding anything but the ALTCHA proof of work Tranzila's
+  own page writes there before it submits), terminal the same way. That
+  proof is the only filled-in challenge field the cardholder's device sends
+  with the card. An Authorize.Net DPM or SIM form adds more reasons
+  (`duplicate_field`, `not_a_card_payment`, `relay_response_off`,
+  `form_step`, `merchant_credential`, `test_request_on_live_host`,
+  `malformed_field`), terminal the same way,
   and `stale_fingerprint`, which is not: `CheckoutApiError.isStaleFingerprint`
   is true, the adapters quiet the page for `approvalCooldownMs`, and the form
   the page renders after a reload is judged afresh. `duplicate_submission` (409,
@@ -834,9 +857,10 @@ is gone resolves as `PaymentOutcomeUnknownError` with reason
   `invalid_wspay_request`, `wspay_keep_on_file_unsupported`, `amount_required`,
   `sandbox_host_on_live_row` or `live_host_on_sandbox_row` (400;
   `proxy-test.wspay.biz` takes only a test-mode client and `proxy.wspay.biz`
-  only a live one). The adapters abort the requests behind
-  `invalid_wspay_request` and `wspay_keep_on_file_unsupported` themselves, and
-  `authorize()` refuses a missing amount, all before any create.
+  only a live one), or `card_not_stored` (409, a card guarantee pinned to a
+  card a company added). The adapters abort the requests behind
+  `invalid_wspay_request` themselves, and `authorize()` refuses a missing
+  amount, both before any create.
 - `PlaceholderCardError`: `placeholderCard()` found no such stored card
   (`card_not_found`), no placeholder for its network (`brand_unsupported`), or
   no expiry on it (`expiry_unknown`). Nothing was created.
@@ -1122,6 +1146,8 @@ await page.getByRole('button', { name: 'Pay', exact: true }).click();
 
 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.
 
+A prepared Bambora checkout has 5 seconds from Pay: Custom Checkout's card frame fails its tokenization request after that. The SDK reads a prepared Bambora approval every 100 ms for its first 10 seconds, so the cardholder's answer reaches the frame within one read of reaching the API. When the frame gives up first, the approval survives, as an unprepared one does: once the device answers, the controller reads `ready_to_submit` with reason `awaiting_merchant_retry`, and when the merchant's next Pay click sends the same request again from the same card frame, the SDK answers it from the same approval with no second prompt. The approval belongs to that card frame: the SDK refuses the same request from any other frame, and removing the card frame stops the attachment, as it does while the request is paused. A Bambora token pays nothing until the merchant's server charges it, and an approval the page never asks for again is retired as `merchant_never_retried`.
+
 Prepare a Checkout.com checkout before the agent clicks Pay:
 
 ```ts
@@ -1145,7 +1171,7 @@ Prepare a Fiserv checkout before the agent clicks Pay:
 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.
+`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. Blinds.com and homedepot.com pay under `homedepot_orangepay`, whose merchant is `Home Depot`. Their card frame encrypts under a session key Home Depot's server hands it, which changed twice between 2026-09-30 and 2026-10-11; the cardholder's device seals the approved card under the key Home Depot publishes instead, and the capture continues naming that key. 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`.
 
@@ -1162,14 +1188,24 @@ Initial coverage includes the hosted iframe's new-card request. Saved-card CVV u
 Prepare an Amadeus Checkout card step before the agent clicks Pay:
 
 ```ts
+const card = await vault.placeholderCard({ user: 'your-user-id', cardId: 'vc_...' }); // what the agent types
+const controller = await attachToPlaywright(page, {
+  vault, user: 'your-user-id', merchant: 'Air France', amount: 1100, currency: 'usd',
+  cardId: card.cardId, // required: the stored card that pays, locked to the approval
+  onApprovalUrl: deliverPrivatelyToCardholder,
+});
+// Once the payment step shows, type card.number and card.securityCode into Amadeus's card number and
+// security code fields, and card.expiryMonth and card.expiryYear into the airline's own expiry field.
 await controller.prepare({ psp: 'amadeus_checkout', environment: 'production' }); // 'sandbox' for Amadeus's test platforms
 ```
 
+Air France and KLM keep the expiry in a field of their own, outside Amadeus's card fields, and send it to their own server with the booking, so the add Amadeus receives carries an empty expiry. Type the stored card's real expiry into that field: `placeholderCard()` reads it from `GET /api/v2/vault_cards`, with a documented test number of the card's network for Amadeus's own fields. The cardholder's device writes the same month and year into the add beside the real card, so Amadeus and the airline hold one expiry. `cardId` is required (`card_required`), and the approval is locked to that card: the cardholder cannot approve another, and `prepare()` reads a ready checkout that names another card as `ready_unconfirmed`.
+
 Amadeus Checkout ships dark: `syncRegistry()` declares `amadeus_checkout_actions.v1`, and the API serves the recognizer only to an org Agentcard enabled for it, so every other org's Amadeus pages run as before. The Checkout Web SDK sends every action to one URL through its tunnel iframe, starting with `load` as the payment step opens. Only the card `add` pauses. `load`, the BIN lookup and every other action continue untouched in every state, and none of them spends or blocks the preparation, so call `prepare()` once the payment step shows. The add binds when its `Amadeus-Checkout-Sdk-Host` header names the prepared page's host; the cardholder's device fills in the card and sends it, and the page's tunnel receives Amadeus's answer. The add names no amount, so the amount you pass is the one the cardholder approves.
 
 The tunnel gives up on the add 30 seconds after sending it, so the device has 20 seconds from the pause. When they pass with no answer on its way, the SDK asks the API to retire the authorization, or, while the create has not answered, the preparation and any request already bound to it. The API confirms a retirement only while the card is still on the device. Once it does, nothing was sent and nothing can be: the SDK fails the page's request, and the controller reads `failed` with reason `amadeus_send_window_closed`. The cardholder's device keeps an earlier boundary of its own, 12 seconds after it last saw the checkout unbound: past it the device sends nothing and declines the request with the same reason, and the SDK and the controller read it the same way. A prepared checkout is used once, so attach again and prepare again to retry. When the API cannot confirm, the card can already be on its way, so the SDK waits for the device's answer, and the tunnel's own 30 seconds still end the request.
 
-The SDK refuses some requests itself, before any row or prompt, and the controller reads `failed` with the reason: Air France's and KLM's add, whose expiry their own form keeps (`amadeus_merchant_held_expiry`), a Data Collection Page store until the merchant's field configuration is reviewed (`amadeus_dcp_field_config_unreviewed`), and an add whose Host header names another page (`amadeus_header_binding`). Card saving, split payments, installments, currency conversion and Amadeus 3-D Secure data are refused the same way. The SDK judges an add before a card is chosen, so it cannot see the card's network: an add naming another network reaches the cardholder's device, which refuses it after approval (`vendor_mismatch`), with nothing sent. An add with no preparation is refused with `PreparationRequiredError`. An add that pays with a card the merchant saved carries no card number and continues untouched, and so does Air France's Nuvei payment with a `ccTempToken` after the add. Autopilot never pays an Amadeus payment.
+The SDK refuses some requests itself, before any row or prompt, and the controller reads `failed` with the reason: a Data Collection Page store until the merchant's field configuration is reviewed (`amadeus_dcp_field_config_unreviewed`), and an add whose Host header names another page (`amadeus_header_binding`). Card saving, split payments, installments, currency conversion and Amadeus 3-D Secure data are refused the same way. The SDK judges an add before a card is chosen, so it cannot see the card's network: an add naming another network reaches the cardholder's device, which refuses it after approval (`vendor_mismatch`), with nothing sent. An add with no preparation is refused with `PreparationRequiredError`. An add that pays with a card the merchant saved carries no card number and continues untouched, and so does Air France's Nuvei payment with a `ccTempToken` after the add. Autopilot never pays an Amadeus payment.
 
 Prepare Recurly before clicking the merchant's payment button:
 
@@ -1194,9 +1230,9 @@ await controller.prepare({ psp: 'aci', environment: 'production' }); // 'sandbox
 Type a placeholder card of the approved card's network (a Mastercard-range placeholder for an Agentcard-issued card), then click Pay once. The cardholder's device refuses a placeholder of another network before any card leaves it, and the authorization ends `declined` with reason `aci_brand_mismatch`. The SDK:
 
 - pauses the card-number request and binds it to the preparation. The cardholder's device sends it to ACI with the real number, CVC and expiry, and the page receives ACI's answer.
-- holds the page's own CVC and expiry requests and answers them with that answer, so the placeholder values never reach ACI (`aci_leg_absorbed`). They fail when the card-number request fails, or when none begins within 5 seconds, which is what a one-click stored-card form that sends a CVC request alone gets.
-- lets the holder request through untouched.
-- lets the page's `/payment` submission continue once, only as the widget's own form post into its hidden iframe (a frame navigation) and only after its checkout's card-number request was answered (`aci_payment_continued`). In classic mode the placeholder expiry the page put there is removed (`stripped: true`). `paymentBrand` must be the brand of the placeholder you typed, and `shopperResultUrl` must be on the prepared merchant origin.
+- holds the page's own CVC and expiry requests and answers them with that answer, so the placeholder values never reach ACI (`aci_leg_absorbed`). They fail when the card-number request fails, or when none begins within 5 seconds, which is what a one-click stored-card form that sends a CVC request alone gets. A refused request that carries no card number, such as a device fingerprint longer than ACI takes, leaves them waiting for the card-number request.
+- lets the holder request and the ReD Shield device fingerprint the widget posts on load (`customer.browserFingerprint.value` alone, up to the 4,096 characters ACI takes) through untouched.
+- lets the page's `/payment` submission continue once, only as the widget's own form post into its hidden iframe (a frame navigation) and only after its checkout's card-number request was answered (`aci_payment_continued`). In classic mode the placeholder expiry the page put there is removed (`stripped: true`). `paymentBrand` must be the brand of the placeholder you typed, `shopperResultUrl` must be on the prepared merchant origin, and `shopperResultTarget`, when the page sets one, must be `_top`, ACI's own default.
 
 The SDK removes that expiry only on a browser that sends the body it replaced on a navigation, which the SDK's tests show on Chromium. `attachToCdp` drives Chromium. `attachToPlaywright` reads the page's browser engine, or, for a persistent context, checks whether a CDP session opens, which only Chromium allows. On Firefox or WebKit it refuses a classic-mode `/payment` as `aci_expiry_unstrippable` rather than send the placeholder expiry. A SAQ-A-mode `/payment` has nothing to remove and continues on any engine.
 
@@ -1205,7 +1241,7 @@ The `blocked` events the SDK adds for ACI, by `detail`:
 | `detail` | When |
 |---|---|
 | `aci_card_on_file_refused` | A request asks ACI to keep the card or pay with a stored one (`createRegistration`, `registrationId`, `registrations[...]`, standing instructions, the `/registration` endpoint). A ready preparation is retired too. |
-| `aci_unsupported_request` | A leg the widget never sends, or a `/payment` that a page script sends itself instead of the widget's form. |
+| `aci_unsupported_request` | A leg the widget never sends, a device fingerprint longer than ACI takes, a `/payment` whose `shopperResultTarget` is not `_top`, or a `/payment` that a page script sends itself instead of the widget's form. |
 | `aci_checkout_reused` | A second card-number request arrives on a checkout whose first one is running or was answered in this attachment. |
 | `aci_leg_unanswered` | A CVC or expiry request's card-number request failed, or none began within 5 seconds. |
 | `aci_payment_unapproved` | A `/payment` arrives before its checkout's card-number request was answered. |
@@ -1240,14 +1276,21 @@ Braintree's native `ClientConfiguration` GraphQL query can run before, during or
 
 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 or a Shiji STS 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.
+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 other than Bambora's or a Shiji STS 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
+does not revoke a pending approval link or undo a processor payment. Cancelling
+an attempt still under way (a card request in flight, or an authorization not
+yet settled) therefore reads `outcome_unknown` with reason `local_cancel` until
+reconciled. A checkout that already ended keeps its state and reason:
+`completed`, `declined`, `failed`, `timed_out`, `unsupported`, `cancelled` and
+`outcome_unknown` read the same after `cancel()` once no card request is in
+flight, or once the request in flight has its own outcome recorded, as when
+your code cancels from `onStateChange` or the `failed` event. A cleanup that
+cancels never hides a processor refusal or a confirmed payment. A cancelled
 attachment cannot restart.
 
 ### Adyen merchants that take the card on their own server
@@ -1598,6 +1641,15 @@ const checkout = await attachToPlaywright(page, {
   sets its CVV length and contact fields by that brand, so the cardholder's
   device refuses a card whose brand differs, before anything is sent.
   Agentcard-issued cards are Mastercard: type a Mastercard test number.
+- **An expiry the merchant keeps.** RaiseNow's donation widget (Tamaro)
+  collects the expiry in its own field and sends it to RaiseNow beside the
+  token, so its card post carries no `expm` or `expy`. Such a post pauses like
+  any other, and the cardholder's device writes the card number and CVV and
+  adds no expiry, as the page sent none. Type the card's real expiry from
+  `placeholderCard()` into the merchant's own expiry field: the merchant
+  charges with the expiry its form holds. A post with only one of the two, or
+  with no expiry while it asks to keep the card on file, is refused as
+  `invalid_datatrans_request`.
 - **Merchant accounts.** A token minted into a Datatrans account can be read
   back as the card number by that account's holder, so the API refuses a
   merchant account Agentcard has not reviewed (`datatrans_merchant_unregistered`).
@@ -1745,34 +1797,53 @@ The other requests on Primer's hosts:
 
 A client session the merchant created to save every card after payment (Printful
 does this for a signed-in shopper) shows nothing in the request, so the SDK
-cannot detect that save. Until the cardholder can consent to it, Primer pays
-only for a test-mode client: for a live client the API answers 400
-`invalid_primer_request` with reason `live_keep_on_file` before anything is
-created, the SDK aborts the paused request with nothing sent, and the attachment
-reads `failed`.
+cannot detect that save. A live payment therefore goes ahead only with a card
+the cardholder stored, on an approval that says the merchant keeps the card on
+file. Nothing in the request names the Primer merchant whose session keeps it,
+so the approval names the merchant as the `merchant` you sent and says Agentcard
+cannot confirm it. The SDK sends the checkout page's origin as `checkout_origin`
+when the browser exposes it, and a live payment needs an https one. Without it,
+the API answers 400 `invalid_primer_request` with reason
+`checkout_origin_required` before anything is created, the SDK aborts the paused
+request with nothing sent, and the attachment reads `failed`. A card a company
+added never pays a live Primer payment (409 `card_not_stored`).
 
 ### Pay a Payrails checkout
 
-Payrails (web SDK v6 secure fields, as on Blacklane's consumer booking checkout)
-launches dark: `syncRegistry()` asks for the `device_encrypt` mode and declares
+Payrails (web SDK secure fields, as on Blacklane's consumer booking checkout and
+FlixBus's guest checkout) launches dark: `syncRegistry()` asks for the `device_encrypt` mode and declares
 the `payrails_device_encrypt` capability, and the API serves the Payrails
 recognizer only to an org Agentcard has enabled for Payrails. For every other
 org nothing changes: no answer is read, no Payrails host is intercepted, and
 Payrails' requests go through untouched.
 
-For an enabled org, the SDK pauses one request: the card form's save, a `POST`
-to the session's `saveInstrument` link (`https://api-pub.payrails.io/public/payment/instruments`;
-test hosts `api-pub.staging.payrails.io` and `sandbox-api-pub.staging.payrails.io`)
-that carries the whole card as one JWE. The key it was encrypted under is not in
-that request, so the adapters read the Payrails init payload (`{version, data}`)
-from the page's own XHR and fetch answers and keep, in memory only, up to eight
-sessions for fifteen minutes. A paused save binds to the one session whose token,
-save link, `holderReference` and `providerConfigId` it names, seen at most nine
-minutes before, and that session's key rides on the create. The cardholder's
-device encrypts the real card under it and sends the save to Payrails itself;
-the page receives Payrails' 201 rebuilt from an allow-list (the instrument, its
-status, the network, the BIN cut to six digits, the last four, the expiry, the
-holder name and the fingerprint). Call `syncRegistry()` before attaching, or the
+For an enabled org, the SDK pauses two requests, each carrying the whole card as
+one JWE: the card form's save, a `POST` to the session's `saveInstrument` link
+(`https://api-pub.payrails.io/public/payment/instruments`; test hosts
+`api-pub.staging.payrails.io` and `sandbox-api-pub.staging.payrails.io`), and the
+card form's payment, a `POST` to the session's execution authorize link
+(`/public/merchant/workflows/payment-acceptance/executions/{id}/authorize`), which
+FlixBus's Pay now button sends. Either may go to a merchant's own Payrails host,
+`api-pub.<merchant>.payrails.io` (FlixBus's is `api-pub.flix.payrails.io`). The key
+the card was encrypted under is not in the request, so the adapters read the
+Payrails init payload (`{version, data}`) from the page's own XHR and fetch
+answers, at the top of an answer or anywhere in its first eight levels (FlixBus
+nests it inside `/payment/configuration/list`), and keep, in memory only, up to
+eight sessions for fifteen minutes. A paused save binds to the one session whose
+token, save link, `holderReference` and `providerConfigId` it names, and a paused
+payment to the one whose token, execution, host and `providerConfigId` it names,
+seen at most nine minutes before. That session's key rides on the create, and for
+a payment its `holderReference` too. The cardholder's device encrypts the real
+card under the key and sends the request to Payrails itself. For a save the page
+receives Payrails' 201 rebuilt from an allow-list (the instrument, its status, the
+network, the BIN cut to six digits, the last four, the expiry, the holder name and
+the fingerprint); for a payment, Payrails' 202 rebuilt to the authorize action's
+name, id, time and execution link, which the page's own Payrails SDK polls for the
+issuer's answer and any 3-D Secure challenge. That link must name the payment the
+page sent, its own execution on its own host: an action naming another execution,
+or this one on another host, would have the page poll another payment's result, so
+it never reaches the page and `authorize()` throws `PaymentOutcomeUnknownError`
+(`payrails_answer_unconfirmed`). Call `syncRegistry()` before attaching, or the
 page's session answers are not read.
 
 ```ts
@@ -1785,7 +1856,8 @@ const controller = await attachToPlaywright(page, {
 
 A save names no amount (the merchant charges the saved card later), so pass
 `amount` and `currency`, or a `pageAmount` reader: without either, the save
-throws before anything is created.
+throws before anything is created. A payment names the amount it authorizes, and
+the API holds the amount you pass, if any, to it.
 
 What the SDK refuses, before anything is created, with the reason on the
 `unsupported_checkout` event:
@@ -1798,17 +1870,30 @@ What the SDK refuses, before anything is created, with the reason on the
   `payrails_not_card_save`, `payrails_jwe_malformed`) are refused too. The
   attachment reads `unsupported` with that reason and holds, since the merchant's
   integration decides that shape.
-- Paying with the card form or a stored card with a CVC field, which sends the
-  card inside `paymentComposition` to any Payrails host:
-  `unsupported_payrails_card_payment`. The attachment holds, and the agent's
+- A card-form payment that stores the card at the merchant (`storeInstrument`,
+  enrollment in a network offers program, or `meta.order.processingType`
+  `CardOnFile` or `UnscheduledCardOnFile`):
+  `payrails_card_on_file_consent_required`; one that sets up a subscription
+  (`meta.subscription`, or `processingType` `Subscription`):
+  `payrails_future_usage_refused`. Any other payment that sends the card
+  inside `paymentComposition` in a shape the SDK does not take over (a stored
+  card with a CVC field, a split or installment payment, a preferred scheme,
+  another link than the execution's authorize link, or a `meta` member outside
+  the reviewed list): `unsupported_payrails_card_payment`. The reviewed `meta`
+  is the SDK's `clientContext` facts, `risk.sessionId` or `sessions`,
+  `risk.threeDSMode` `Default`, a `risk` skip flag set `false`, an `order` with
+  only `processingType` `Regular`, and an empty `customer`. Payrails reads keys
+  in any case, so a key spelled in another case, or two keys of one object that
+  differ only in case, are refused as well. The attachment holds, and the agent's
   placeholder card never reaches an authorization.
-- A save no captured session matches (`payrails_session_unavailable`), or whose
-  captured key is not the one the page's secure frame used (`payrails_key_invalid`,
-  `payrails_key_mismatch`): that request alone is aborted, the event carries
-  `message: 'Payrails session expired, reload the checkout'`, and the save after
-  a reload is judged afresh.
-
-A save with no card (a dynamic payment-method form posts to the same link)
+- A save or payment no captured session matches (`payrails_session_unavailable`),
+  or whose captured key is not the one the page's secure frame used
+  (`payrails_key_invalid`, `payrails_key_mismatch`): that request alone is aborted,
+  the event carries `message: 'Payrails session expired, reload the checkout'`,
+  and the request after a reload is judged afresh.
+
+A save or payment with no card (a dynamic payment-method form posts to the save
+link; a wallet, a stored card or a redirect method pays on the authorize link)
 continues untouched. A `POST` to a Payrails host with no body the SDK can read,
 whether it has none, an empty one or a streamed one, is aborted alone with a
 `blocked` event, `unreadable_payrails_request`, by both adapters: Playwright
@@ -1816,8 +1901,8 @@ reports all three the same way. The Payrails SDK sends a JSON body with every
 `POST`, so none of its own requests is refused this way. Payrails' static host,
 `assets.payrails.io`, serves only files and takes no payment, so a bodyless
 `POST` another script sends there continues untouched. The matching API,
-Vault and database releases are required, and the API also refuses a save for a
-merchant whose Payrails workspace Agentcard has not reviewed.
+Vault and database releases are required, and the API also refuses a request for a
+merchant whose Payrails workspace or host Agentcard has not reviewed.
 
 ### Pay an Elavon Converge payment page
 
@@ -1829,7 +1914,9 @@ to its own `/hosted-payments/service/payment/hpp/process`. The SDK pauses that
 request, the cardholder approves the amount it names on their phone, their
 device sends the real card to Converge, and the page receives Converge's
 approval, so its own script shows the receipt and returns the buyer to the
-merchant. Converge's demo environment serves the same page on
+merchant. Every Converge Buy Button and pay link opens the same page on
+`www.convergepay.com`, which posts the card to its own origin and is paid the
+same way. Converge's demo environment serves the same page on
 `api.demo.convergepay.com`, which pays in test mode only.
 
 Converge ships dark: `syncRegistry()` asks for the `converge_hpp_process`
@@ -1851,16 +1938,29 @@ const checkout = await attachToPlaywright(page, {
   grant never pays one.
 - Electronic check and financing payments on the same URL carry no card and
   continue untouched.
+- A Buy Button's page sends `recurring` as `"false"` in every request unless the
+  buyer ticked the button's recurring box. That request is a one-time sale and
+  pauses like any other; `"true"`, or any other value, is refused as recurring.
+- A page with its CAPTCHA on, as every Buy Button page read so far has it,
+  sends its card request only after the CAPTCHA is solved, with the answer in
+  `captchaToken`. A person solves it in the browser, never your agent, so a
+  browser that solves CAPTCHAs itself, such as Kernel with stealth on, must not
+  run a Converge page. The SDK
+  pauses that request like any other, and the cardholder's device sends the
+  answer to Converge unchanged beside the card. Google takes the answer once,
+  for two minutes after the solve, so the cardholder approves inside that
+  window.
 - Before any prompt, the SDK refuses every other shape on that URL with
   payment-core's own code (`ConvergeRefusalReason`, listed in
   `CONVERGE_REFUSAL_REASONS`), the one the API and the cardholder's device
   would answer: a wallet, the debit, gift card and push-to-card tabs, a
-  follow-up after a 3-D Secure, Pay Defense or surcharge step, a CAPTCHA, a
-  public-sector service fee, recurring or installment fields, card saving, a
-  tip or cash back, another currency, no amount, no page session, and anything
-  that is not the page's own request. The page's request is aborted, nothing is
-  created, and the attachment is not held, so the page's next payment is judged
-  afresh. The table below gives each code's meaning and the next step.
+  follow-up after a 3-D Secure, Pay Defense or surcharge step, a CAPTCHA
+  answer Google never issued, a public-sector service fee, recurring or
+  installment fields, card saving, a tip or cash back, another currency, no
+  amount, no page session, and anything that is not the page's own request.
+  The page's request is aborted, nothing is created, and the attachment is not
+  held, so the page's next payment is judged afresh. The table below gives each
+  code's meaning and the next step.
 - A terminal with 3-D Secure 2, Pay Defense or a surcharge answers the first
   request with a step instead of a result. The Vault never hands that answer to
   the page: the authorization ends declined as a processor refusal with
@@ -1903,7 +2003,7 @@ of the same code. `converge_step_unsupported`, `converge_declined` and
 | `converge_gift_card_refused` | The payment came from the page's gift card tab. | Pay with the credit card form. |
 | `converge_push_to_card_refused` | The payment would send money to the card instead of charging it. | None: an Agentcard card never receives money. |
 | `converge_payment_type_refused` | The body names a payment type other than a credit card sale, or an electronic check or financing payment carries a card number. | Pay with the credit card form. |
-| `converge_captcha_refused` | The page sent a CAPTCHA answer with the payment. | The buyer pays this merchant without Agentcard: the cardholder's device cannot answer a CAPTCHA. |
+| `converge_captcha_refused` | The request's `captchaToken` is not a solved reCAPTCHA answer: it is empty, not text, longer than 4,096 characters, or holds a character other than `A-Z`, `a-z`, `0-9`, `_` and `-`. | Have a person solve the page's CAPTCHA, then let the page send its own request. |
 | `converge_service_fee_refused` | The merchant adds a public-sector service fee, which Converge charges as a second payment. | The buyer pays this merchant without Agentcard: a one-time card cannot pay the second charge. |
 | `converge_3ds_follow_up_refused` | The body follows a 3-D Secure or Pay Defense step the page already ran. | Start a new checkout from the merchant's page. A terminal that runs the step on every payment cannot be paid through Agentcard yet. |
 | `converge_surcharge_refused` | The body follows a surcharge quote, or skips it with the debit bypass. | Start a new checkout from the merchant's page. A surcharging terminal cannot be paid through Agentcard yet. |
@@ -2200,8 +2300,8 @@ const checkout = await attachToPlaywright(page, {
   `charged_amount_mismatch`. A 3-D Secure step names no amount, so nothing is
   compared on that path (below). Without `amount` and `currency` the confirm
   fails with `AmountRequiredError` before anything is created.
-- **What pauses.** Only the frame's confirm of a new card for a one-time
-  payment, with the frame's own headers and body. A saved card (`saved_card`),
+- **What pauses.** Only the frame's confirm of a new card, with the frame's
+  own headers and body. A saved card (`saved_card`),
   a card tokenized earlier (`temp_card_id`), a card-shaped object the page
   built into the transaction, or any other request on that URL is aborted with
   a `blocked` event, detail `unsupported_wspay_payment_method`. Nothing is
@@ -2209,12 +2309,21 @@ const checkout = await attachToPlaywright(page, {
   page's next confirm is judged afresh. The frame's other requests (`/show`,
   `/status`, `/pan-info`) continue untouched.
 - **Keep on file.** A confirm with `tokenize_pan: true` asks WSPay to keep the
-  card so the merchant can charge it later without another approval. Only the
-  cardholder can agree to that and no approval asks them yet, so such a
-  confirm is aborted with a `blocked` event, detail
-  `wspay_keep_on_file_unsupported`, and nothing is created. Valamar sets it on
-  every booking, so a Valamar checkout is refused this way until the approval
-  asks the cardholder for that consent.
+  card so the merchant can charge it later without another approval. Valamar
+  sets it on every booking: its payment step is a card guarantee that
+  authorizes EUR 1.00 and keeps the card for the stay. Such a confirm pauses
+  like any other, and the API pays it only as that guarantee: pass `amount:
+  100, currency: 'eur'` when the merchant's payment step is a EUR 1.00
+  guarantee. Any other amount fails the create with
+  `wspay_keep_on_file_unsupported` and nothing is created. The cardholder's
+  approval says the merchant keeps the card on file, and it pays only with a
+  card the cardholder stored: a card a company added fails with
+  `card_not_stored`. When WSPay approves, the frame receives the token WSPay
+  keeps for the merchant (`pan_token`), as it would without Agentcard, and
+  never the card's expiry or masked number. The API serves that answer for 15
+  minutes after the approval, the SDK's default window, and then drops it, so
+  a later read gets `response_expired`. The stay itself is charged later,
+  outside this approval.
 - **3-D Secure.** When WSPay answers with its 3-D Secure step, the frame runs
   the bank's challenge in your browser, and nothing is charged until the
   cardholder completes it there. The controller reads `requires_user_action`
@@ -2236,7 +2345,7 @@ const checkout = await attachToPlaywright(page, {
 Some merchants (The Container Store) have Verifone's verifone.js encrypt the card in the page, under the merchant's own Verifone key, and post the result to the merchant's own server. As for the Adyen merchants above, the card request goes to no processor host, so Agentcard reviews each such merchant as a Verifone profile: its checkout page, its card request and the key verifone.js must encrypt the card under. Verifone ships off. `syncRegistry()` declares `verifone_card_capture`, and the API serves the Verifone profiles only to a build that declares it, for a company Agentcard turned Verifone on for. Until a sync serves one, the adapters pause no request at a Verifone merchant, as before. A served profile arms every request to the merchant's origin in both adapters:
 
 - A request that carries no verifone.js blob (a page, a basket call, a preflight, a request with no body) continues as before. When the browser holds a body it did not hand over, such as a blob or a file, `attachToCdp` aborts the request as one the profile cannot pay, except on a `GET`, `HEAD` or `OPTIONS`. `attachToPlaywright` cannot tell such a body from no body, so it reads one as no body.
-- A profile in `observe` never pays. The adapters abort a request that carries a blob before it reaches the merchant, and report `verifone_profile_observed` with the profile, the URL (the origin and a reviewed path template, never a query), the verdict and `keyPathSha256`, then `unsupported_checkout`. The controller reads `unsupported` with reason `merchant_profile_observe`. `containerstore_checkout` ships in `observe`: Agentcard has reviewed neither its card request nor its key.
+- A profile in `observe` never pays. The adapters abort a request that carries a blob before it reaches the merchant, and report `verifone_profile_observed` with the profile, the URL (the origin and a reviewed path template, never a query), the verdict and `keyPathSha256`, then `unsupported_checkout`. The controller reads `unsupported` with reason `merchant_profile_observe`. `containerstore_checkout` ships in `observe`: Agentcard has reviewed its card request (`POST /checkout/api/submit`) but not its key.
 - The adapters abort a blob request the profile cannot pay (another path, a second card, saving the card, a gift card, a key Agentcard did not pin) and report `unsupported_checkout` with the reason.
 - The profile's reviewed card request, once Agentcard enables the profile for your client and this build, pays only through a preparation for that profile. Without one, the adapters abort it before any pause, prompt or authorization, as for an Adyen merchant.