@agent-cards/sdk 0.21.0 → 0.22.0

package/README.md

@@ -160,7 +160,21 @@ Playwright: `agentcard.checkout.attachToPlaywright(page, { user, merchant, amoun
 
 `amount` is your hint. The processor's own amount is the higher authority: Agentcard reads it from the paused request or from the Stripe intent the request names, right before the cardholder's device replays, and the company's caps are judged on it. A hint more than one smallest unit away from the processor's amount is refused with nothing charged (`AmountMismatchError`), and after the replay the charge is reconciled against the approval (`ReplayResponse.amountVerified`, `chargedAmount`, `chargedKind`, plus the `checkout_authorization.amount_mismatch` webhook when the charge disagreed). Every result carries `amountAuthority`: `processor`, `agent`, `page`, or `none`.
 
-Merchant timeouts still apply to the request itself: Square's observed tokenization deadline is about 10 seconds, Braintree's native request timeout is 60 seconds, and Adyen Web's own request timeout abandons its Sessions payment call 60 seconds after Pay. These are the processors' limits; the SDK's own authorization wait stays 15 minutes. The approval outlives the page's own request: when the page's script gives up on its paused card request while the cardholder is still deciding, the SDK keeps the approval pending (state `awaiting_approval`, reason `merchant_request_lost`) and answers the page's next request for the same purchase from it; when the approval lands first, the controller reads `ready_to_submit` with reason `awaiting_merchant_retry`, and one more Pay click completes the purchase. The wait for that request is bounded (`merchantRetryWaitMs`, two minutes by default); an approval the page never asks for again is retired as `merchant_never_retried`. For a short-deadline processor, `controller.prepare()` before the first Pay finishes the request inside its own deadline.
+An `amount` in neither form, such as the string `"2667"`, is refused before anything is created, and the error names what you passed and each amount it can mean, in the forms the API accepts:
+
+```text
+amount is an integer in the currency's smallest unit (2306 for $23.06), or a decimal string in normal units ("23.06"). You passed the string "2667". For 26.67 USD, send the number 2667 or the string "26.67". For 2667.00 USD, send the number 266700 or the string "2667.00".
+```
+
+Attach with the amount as a number in the smallest unit, and the SDK accepts it:
+
+```ts
+await agentcard.checkout.attachToCdp(cdp, pageSessionId, { user: 'usr_123', merchant: 'vanman.shop', amount: 2667, currency: 'usd' });
+```
+
+`prepare()` refuses the same amount with `CheckoutPreparationError` reason `amount_required`, and its message carries the same sentences. A value below zero is named as such and never offered back as a positive amount.
+
+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
 
@@ -218,6 +232,12 @@ what this package encapsulates.
 | Agentcard servers | **no**, a request template and a token |
 | Cardholder's device | yes, decrypts locally, calls the merchant directly |
 
+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
+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.
+
 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.
@@ -235,11 +255,26 @@ Coverage is specific to the processor request format, merchant setup, browser tr
 | Mercado Pago | Card tokenization and prepared checkout are implemented. Guest Checkout Pro in Mexico also corrects the issuer for one native card association when the selected card has the same brand and type. One live MXN 40 Lotería Chida purchase with published SDK 0.10.0 completed automatically through Pay; the merchant confirmed paid status and PDF fulfillment. The historical SDK result remains unknown because the private receipt adapter rejected a relative download URL; a separate read with the corrected adapter confirms that same paid receipt. Independent processor capture/settlement and other country or integration paths remain unverified. |
 | VGS Collect (Very Good Security; Wolt) | not supported: VGS's proxy aliases only submissions from its own iframe, so a replay from the cardholder's device is refused by the merchant (verified on Wolt, 2026-09-03). Not recognized, so the agent's browser is not paused there |
 | Adyen | supported (mode `cse`): the vault encrypts the card for Adyen on the cardholder's device and your browser sends it. Sessions flow: the paused request is `/checkoutshopper/v1/sessions/{id}/payments` on Adyen's own hosts. A merchant that posts the encrypted fields to its own server pauses only when Agentcard reviewed it as a merchant profile (Dunelm and Cinemark so far); both profiles are in `observe`, so their card requests are reported and aborted and nothing pays there yet (see "Adyen merchants that take the card on their own server"). Without a preparation, approval starts at Pay and must land before Adyen Web's own request timeout (observed at 60 seconds on Adyen Web 6.41 and 6.44; not enforced by the SDK); `prepare({ psp: 'adyen' })` moves the approval before Pay |
+| 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 |
 | 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) |
+| Reviewed merchant card endpoints: AT&T, Italo, Universal Orlando, Target Optical, Opus Virtual Offices | recognized in mode `card_endpoint`, every one in observe: the adapters pause each merchant's own card request and refuse it as `unsupported_checkout` before any authorization, so the dummy card never reaches the merchant. A profile takes payments only after a reviewed partner HAR, a reviewed release of this SDK and the API, and per-org enablement |
+| Datatrans Secure Fields (PCI Proxy; British Airways) | dark launch: the card-number iframe's TOKENIZE card post only, after `vault.syncRegistry()`, and only for an org Agentcard has enabled (see [Pay a Datatrans Secure Fields checkout](#pay-a-datatrans-secure-fields-checkout)). The cardholder's device sends the card to Datatrans and the iframe receives the token and its `cardInfo`. A post that asks PCI Proxy to keep the card on file, which British Airways's Nexus checkout sends for every new card, is refused before any prompt while Agentcard's card-on-file policy refuses it, so a Nexus checkout does not complete yet |
+| Authorize.Net Direct Post Method and SIM | dark launch (mode `hosted_form`, capability `authorize_net_dpm_form`): served only to an org Agentcard enabled for it. The card form posts one form navigation to `transact.dll` on `secure2`, `secure` or `test.authorize.net`; the cardholder's device submits it, and you poll the merchant's order state. Not eligible for auto-approval |
+| 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" |
 
 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()`),
@@ -247,17 +282,29 @@ so new processors work without you shipping a release. `attachToCdp` derives the
 `Fetch.enable` url patterns from that same list rather than a constant, which is
 why the sync call belongs before the attach. `agentcard.checkout.cardUrlPatterns()` returns
 those patterns if you arm a CDP connection yourself. Call
-`GET /v2/checkout/recognizers?modes=token,cse,hosted_form&capabilities=fiserv_card_capture`
+`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`
 for the list this build syncs. The API serves Fiserv's card capture only to a
 build that lists `fiserv_card_capture`, and only for a company Agentcard turned
 Fiserv on for. An older SDK never pauses a Fiserv request it could not finish,
-and no SDK pauses one for a company Fiserv is off for.
+and no SDK pauses one for a company Fiserv is off for. The API serves Juspay's
+card flow the same way, behind `juspay_txns.v1`, Datatrans's Secure Fields
+card post behind `datatrans_secure_fields_tokenize`, the Authorize.Net DPM
+or SIM form behind `authorize_net_dpm_form`, Pelecard's card submission
+behind `pelecard_transaction`, ACI's split card behind `aci_split_card.v1`,
+CreditGuard's hosted page submit behind `creditguard_pps_process`,
+Primer's card tokenization behind `primer_payment_instruments`, WSPay's card
+confirm behind `wspay_confirm`, Shiji STS's card leg behind
+`shiji_sts_pinned_key`, Amadeus Checkout's card add behind
+`amadeus_checkout_actions.v1`, Worldline MyCheckout's card form behind
+`worldline_mycheckout_form`, and Payrails' card save behind
+`payrails_device_encrypt` to a build that also asks for `device_encrypt`. The
+same holds for the Verifone profiles and `verifone_card_capture`.
 
 ## Modes
 
 Each recognizer carries a `mode` (absent means `token`), and every authorization
-carries the mode it was handled in. The adapters do the right thing for all
-three; the difference matters if you drive `authorize()` yourself.
+carries the mode it was handled in. The adapters do the right thing for each
+mode; the difference matters if you drive `authorize()` yourself.
 `ReplayResponse` is a union, so branch on `mode`.
 
 - **`token`** (every processor but Adyen and Fiserv). The cardholder's device calls the
@@ -305,8 +352,9 @@ three; the difference matters if you drive `authorize()` yourself.
   paused capture or the envelope names another key than the capture does. The
   API serves a Fiserv envelope only in the moments after the approval; a later
   read raises `PaymentOutcomeUnknownError` with reason `cse_substitutions_expired`.
-- **`hosted_form`** (Tranzila). The processor's hosted card form submits the
-  card as a TOP-LEVEL form post, so the paused request is a page navigation
+- **`hosted_form`** (Tranzila, Authorize.Net DPM and SIM). The processor's
+  hosted card form, or the merchant's own card form that posts to the
+  processor, submits the card as a form post, so the paused request is a navigation
   (the adapters arm `Fetch.enable` with no resource-type filter and attach the
   processor's iframe, which is how a Document request on `direct.tranzila.com`
   gets paused at all). The cardholder's device rebuilds that form with the
@@ -336,15 +384,98 @@ three; the difference matters if you drive `authorize()` yourself.
   without a round trip, and once the prior authorization is declined or
   expired the same form is a new question. Confirm the order with the
   merchant, which learns the outcome from the processor.
+- **`device_encrypt`** (Payrails). The page encrypts the card under a
+  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
+  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).
+
+  Authorize.Net's Direct Post Method form (the merchant's own card form) and
+  its SIM hosted form both post to `/gateway/transact.dll`, with the card in
+  `x_card_num`, `x_exp_date` and `x_card_code` beside the merchant's signed
+  fingerprint. Authorize.Net reads field names without regard to case, and so
+  does the SDK: `X_Card_Num` is a card request too. The same URL without a
+  card continues untouched: SIM's first step (`x_show_form=PAYMENT_FORM`,
+  which loads the hosted form), an eCheck and Visa Checkout. The endpoint is
+  the bare URL: a form whose action carries a query string or a fragment is
+  not recognized and continues untouched, exactly as the API refuses it. A
+  fingerprint that Authorize.Net would find stale (more than 40 minutes old
+  at the create, or ahead of the API's clock) is refused for that form only:
+  the page reloads with a fresh fingerprint and pays. Authorize.Net spends a
+  fingerprint once, so never resubmit a form the cardholder's device sent.
+
+- **`card_endpoint`** (a reviewed merchant's own card endpoint). Some
+  merchants post the typed card from their own checkout page straight to
+  their own server, with no processor in between. Agentcard reviews each one
+  and pins a profile in this SDK's copy of the payment core: the checkout
+  page's origin, the exact origin, path and query of the card request, the
+  session headers and cookies it needs, and the answer headers that may come
+  back. The adapters arm every profile's endpoint (`cardEndpointPatterns()`
+  lists the `Fetch.enable` patterns) and pause a POST that is exactly a
+  profile's card request; a GET, a CORS preflight or a look-alike URL
+  continues untouched. While this build's copy of a profile does not take
+  payments (all five are in observe today) the request is refused as
+  `unsupported_checkout` and the controller reads `unsupported` with reason
+  `merchant_card_endpoint_not_enabled`, before any authorization exists. For a
+  profile that takes payments, the adapter captures the request's session:
+  the profile's own header names from the paused request, the endpoint's
+  cookie jar for a cookie profile (`Network.getCookies` or
+  `context.cookies()`, since the paused headers never carry it), and a
+  `Referer` only when it is a page on the checkout origin. It sends them with
+  the paused body, which holds only the dummy card, in the create's
+  `merchant_card_endpoint` member, never in `request`, and checks them first
+  with the same rules the API and the device run. The cardholder's device
+  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
+  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
+  there instead, so it replaces that cookie rather than sitting beside it; one
+  whose `Domain` the endpoint host is not inside is dropped, as a browser
+  drops it. Then the adapters
+  fulfill the paused request with the merchant's status, the profile's
+  answer headers, the CORS headers a cross-origin page needs, and the body.
+  When the device withheld the answer (it carried the card, or a compressed
+  stream the device cannot read), the paused request gets a fixed `502` JSON
+  error with code `agentcard_answer_withheld`, and the controller reads
+  `outcome_unknown` with reason `merchant_answer_withheld`: the merchant has
+  the card, so check the order. Every payment needs the cardholder's
+  approval (no Autopilot, no `prepare()`), and the `amount` you pass is the
+  only amount authority, so an attachment without one is refused. The
+  approval never outlives its request: a card request the page gives up on
+  retires the authorization. After the hand-off the attachment holds, so the
+  page's retry of the card request, or a step-up that sends the card again,
+  is refused until you reconcile the order. Card endpoint events name the
+  `profile` and the `endpoint` origin, never the request's URL, body or
+  session: the URL carries the merchant's cart and booking ids.
 
 `syncRegistry()` asks the API for `SUPPORTED_MODES` only
-(`token,cse,hosted_form`), so a processor whose flow this build cannot finish
-is never paused; the API serves `hosted_form` entries only to callers that ask.
-It also declares `SUPPORTED_CAPABILITIES` (`capture_context`), the dark-launch
-half of the same negotiation: a processor gated behind a capability is served
-only to a build that declares it and never sits in the built-in list, so it is
-paused only after a sync. A registry entry naming a capability this build does
-not declare throws `UnsupportedCapabilityError` before creation.
+(`token,cse,hosted_form,device_encrypt`), so a processor whose flow this build
+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 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
+pauses it only after a sync. A registry entry naming a capability this build
+does not declare throws `UnsupportedCapabilityError` before creation. A runtime
+that calls `GET /v2/checkout/recognizers` itself without that parameter, such as
+a native provider integration, never receives the Fiserv, GMO, CyberSource Flex,
+Juspay, Datatrans, Authorize.Net DPM, Pelecard, Primer, Payrails, Worldpay eProtect,
+WSPay, Shiji STS or Amadeus recognizer. See "Prepare a Worldpay eProtect checkout (dark launch)" and "Pay a
+WSPay Components checkout" below.
 A registry mode this SDK cannot finish throws `UnsupportedModeError` before
 creation. An approval returned in an unexpected mode has an unknown outcome
 and holds the attachment for reconciliation. The `authorized` event's detail names
@@ -355,6 +486,71 @@ detail names the `authorizationId`, `submittedAt` and `outcome:
 one. `amountAuthority` on every replay is `stripe_payment_intent`,
 `hosted_form_sum` (the form's own amount) or `display_only`.
 
+### Shiji STS (MyCheck Wallet V3)
+
+La Quinta by Wyndham takes 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/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
+`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
+before.
+
+For an enabled org, both adapters judge each POST to those two URLs before
+anything pauses:
+
+- A `getTokenId` in the proxy's own shape is the one prompt. The cardholder's
+  device encrypts the real card under the key Agentcard pins (never a key from
+  the page), `authorize()` resolves with `substitutions: { encoding: 'json',
+  at: '', fields: { pan, expires, cvv } }`, and the adapter writes `pan` and
+  `expires` over the page's own at the body root and continues the request
+  from the same browser. The `authorized` event names `fields: ['pan',
+  'expires']`. The ciphertext goes only into the request the approval was
+  created from, byte for byte. If the page gives up on that request while the
+  cardholder decides, the approval is cancelled (`outcome_unknown`, reason
+  `merchant_request_aborted`), as for a hosted form: no later `getTokenId`
+  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:
+  `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
+  `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
+  unreviewed key. An approval served with no reviewed `getCvvId` key resolves
+  as `PaymentOutcomeUnknownError` (`cse_substitutions_malformed`) and nothing
+  continues. The device's CVV ciphertext is dropped from memory as soon as no
+  `getCvvId` can use it: when the attachment is cancelled, the page, the frame
+  or the target that sent the `getTokenId` goes away, or that frame loads a new
+  document (a reload included), which never obtained the approval. The same
+  document changing its path (`history.pushState`), its hash, or following a
+  link answered 204 keeps it, even while a navigation it later cancels is
+  pending. CDP names the new document (`Page.frameNavigated`); Playwright does
+  not, so `attachToPlaywright` reads the frame's `performance.timeOrigin` when
+  the `getTokenId` pauses and again for each `getCvvId`, and continues one only
+  from the same document.
+- Anything else on those URLs (another body shape, a query string, a field
+  encrypted under a larger key) is refused as `unsupported_shiji_sts_request`
+  or `shiji_sts_foreign_key`. A body the adapter cannot read is aborted alone
+  (`blocked`, `unreadable_shiji_sts_request`).
+
+The request names no amount, so pass the booking total as `amount` and
+`currency`: the API refuses a Shiji create without it (`amount_required`).
+Autopilot never pays Shiji. A Shiji set is served once; an approval whose set
+is gone resolves as `PaymentOutcomeUnknownError` with reason
+`cse_substitutions_expired`.
+
 ## Errors worth handling
 
 - `ApprovalTimeoutError`: the server confirms the authorization expired without a replay attempt. A local deadline is different: `PaymentOutcomeUnknownError` means the approval link may still be valid, so reconcile the merchant order before another attempt.
@@ -407,7 +603,13 @@ one. `amountAuthority` on every replay is `stripe_payment_intent`,
   reporting to the merchant you named (a reusable token in or out, a sale
   mode that is not a sale, a callback URL off the merchant's host: name the
   merchant by its hostname when the form carries callback URLs); all three
-  are terminal for that page. `duplicate_submission` (409,
+  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,
+  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,
   with `prior_authorization_id` and `prior_status`) means this exact
   submission already has, or already had, its prompt: the adapters quiet the
   page's re-posts for `approvalCooldownMs` (no second notification for one
@@ -429,20 +631,52 @@ one. `amountAuthority` on every replay is `stripe_payment_intent`,
   page changed, throws `CheckoutPreparationError` with the API's code as its
   `reason`.
 - `AmountRequiredError` (`code: 'amount_required'`): the processor's request
-  names no amount (GMO) and you passed none, so there is nothing for the
+  names no amount (GMO, Pelecard, WSPay) and you passed none, so there is nothing for the
   cardholder to approve. Thrown before anything is created; terminal for that
   page. Pass `amount` and `currency`.
+- Datatrans refusals at create, all terminal for that page: `CheckoutApiError`
+  with `code` `processor_unavailable` (403, Datatrans is not enabled for your
+  org), `invalid_datatrans_request`, `datatrans_card_on_file_refused`,
+  `datatrans_merchant_unregistered` (the post names a merchant account
+  Agentcard has not reviewed), `amount_required` (400; you passed no amount
+  above zero and the page total could not be read), or `sandbox_host_on_live_row` and
+  `live_host_on_sandbox_row` (400; `pay.sandbox.datatrans.com` takes only a
+  test-mode client and `pay.datatrans.com` only a live one). The adapters
+  abort the posts behind `invalid_datatrans_request` and, while the served
+  card-on-file policy refuses card on file,
+  `datatrans_card_on_file_refused` themselves, before any create, and those
+  two do not end interception for the page.
 - `CardEncryptedError`: this processor encrypts the card in-page and its
   registry entry does not (yet) say the vault can produce that ciphertext;
   route the purchase to an Agentcard-issued card instead.
 - `UnsupportedModeError`: the registry requests a mode this SDK cannot finish
   before an authorization exists. Upgrade. An unexpected approved mode instead
   raises `PaymentOutcomeUnknownError` and requires reconciliation.
+- `CheckoutPreparationError`: `reason` names why a preparation stopped. For
+  CreditGuard, the SDK refuses before any request with `payment_page_required`,
+  `unsupported_payment_page`, `payment_page_environment_mismatch` (the page's
+  host is not of the environment you named), `payment_page_unsupported` (a
+  page URL for another processor) or `merchant_origin_invalid`; the API's
+  refusals come through as `creditguard_transaction_refused` (CreditGuard's
+  reason in `detail`), `creditguard_transaction_unavailable`,
+  `amount_mismatch`, `processor_unavailable`, `sandbox_host_on_live_row` and
+  `live_host_on_sandbox_row`. Nothing was created and nothing was charged.
 - `PreparationRequiredError`: a direct `authorize()` call for a processor that
-  pays only through a prepared checkout (Fiserv) passed no preparation. Nothing
-  was created and nothing was charged; call `prepareCheckout()` first. The
-  adapters refuse such a request before it pauses, with the controller reason
-  `preparation_required`.
+  pays only through a prepared checkout (Fiserv, CreditGuard, Worldpay eProtect)
+  passed no preparation. Nothing was created and nothing was charged; call
+  `prepareCheckout()` first. The adapters refuse such a request before it
+  pauses, with the controller reason `preparation_required`. For Worldpay
+  eProtect the refusal is terminal for the attachment: attach again and call
+  `prepare()` before the first Pay action.
+- `PaymentOutcomeUnknownError` with reason `creditguard_response_unconfirmed`:
+  the approved CreditGuard answer is not an approval of the paused
+  transaction, so the page never reads it. Reconcile the order with the
+  merchant before another attempt.
+- `PaymentOutcomeUnknownError` with reason `response_expired`: the API no
+  longer serves the approved answer. A CreditGuard answer carries
+  CreditGuard's card token in its landing url, so the API serves it only for
+  15 minutes after the approval, the default `timeoutMs`. Reconcile the
+  order with the merchant before another attempt.
 - `UnsupportedCapabilityError`: the registry entry is gated behind a
   dark-launch capability this build does not declare. Only a hand-built
   registry can hold one. Upgrade.
@@ -454,12 +688,90 @@ one. `amountAuthority` on every replay is `stripe_payment_intent`,
   `microform_unsupported` or `invalid_cybersource_request` (400). An approved
   Flex authorization whose answer is not a transient token raises
   `PaymentOutcomeUnknownError` with reason `cybersource_flex_token_unconfirmed`.
+- Juspay refusals at create, all terminal for that page: `CheckoutApiError`
+  with `code` `processor_unavailable` (403, not enabled for your org),
+  `invalid_juspay_request` (400, with a `reason`: the paused `/txns` is not the
+  reviewed payment) or `sandbox_host_on_live_row` (400). An approved Juspay
+  authorization whose answer is outside the allowlist raises
+  `PaymentOutcomeUnknownError` with reason `juspay_response_unconfirmed`, and a
+  `ProcessorRefusedError` whose `pspErrorCode` starts with `juspay_tokenize_`
+  means the cardholder's device never sent the payment and nothing was charged.
+- The SDK refuses these Juspay requests in the browser, before the API creates
+  an authorization and before anything reaches Juspay. It throws nothing for
+  them: the attachment's state and its events carry the code.
+
+  | Code | Where it appears | What it means | What to do next |
+  |---|---|---|---|
+  | `juspay_request_unsupported` | `getState().reason`; the `unsupported_checkout` event's `reason` names what the SDK refused, such as `save_to_locker` | The vault cannot pay this Juspay request, such as one that saves the card (`save_to_locker=true`) or pays by EMI. A saved card's payment with its stored token passes. | Untick "save card" and pay in full rather than by EMI, then attach again. |
+  | `juspay_placeholder_fingerprint` | a `blocked` event | The SDK refuses the page's lookup of the placeholder card. | Nothing: the page carries on without it. |
+  | `juspay_unknown_synthetic_token` | a `blocked` event | A `/txns` names a stand-in token this attachment never issued. | Click Pay again on the attached page, so its next tokenize gets a stand-in token from this attachment. |
+  | `juspay_request_body_unreadable` | a `blocked` event | The browser does not hand over the card request's body. | Click Pay again: the SDK judges the next request afresh. |
+
+  `juspay_request_unsupported` holds the attachment as `unsupported` until you
+  attach again. Each `blocked` code refuses only its own request, and the
+  attachment stays as it was. With `onEvent: console.log` on a Playwright
+  attachment, a payment with "save card" ticked logs these three events, and
+  `console.log(checkout.getState())` then prints the last object:
+
+  ```text
+  { type: 'blocked', detail: 'juspay_placeholder_fingerprint' }
+  { type: 'checkout_prepared', detail: { processor: 'juspay' } }
+  {
+    type: 'unsupported_checkout',
+    detail: {
+      url: 'https://api.juspay.in/txns',
+      method: 'POST',
+      processor: 'juspay',
+      reason: 'save_to_locker'
+    }
+  }
+  {
+    status: 'unsupported',
+    authorizationId: null,
+    reason: 'juspay_request_unsupported'
+  }
+  ```
+
+  A page that sends the three requests the SDK refuses alone logs one `blocked`
+  event for each: the placeholder's fingerprint lookup, a `/txns` with a
+  stand-in token this attachment never issued, and a POST with no body.
+  `console.log(checkout.getState())` then prints the last object:
+
+  ```text
+  { type: 'blocked', detail: 'juspay_placeholder_fingerprint' }
+  { type: 'blocked', detail: 'juspay_unknown_synthetic_token' }
+  { type: 'blocked', detail: 'juspay_request_body_unreadable' }
+  { status: 'idle', authorizationId: null }
+  ```
+- WSPay refusals at create, all terminal for that page: `CheckoutApiError`
+  with `code` `processor_unavailable` (403, WSPay was turned off for your org
+  after your last `syncRegistry()`),
+  `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.
 - `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.
 - `SubstitutionError`: a `cse` approval could not be written into the paused
   body (the four encrypted fields were not there). The request is failed and
   the next one is judged afresh.
+- `CardEndpointRefusedError`: a payment to a reviewed merchant's own card
+  endpoint was refused before anything was created or sent. `reason` is
+  `not_enabled` (this build's profile does not take payments),
+  `amount_required`, `approval_required` (the attachment asks for
+  Autopilot), `preparation_unsupported`, or `request_unsupported` (the
+  paused request is not the card request Agentcard reviewed; `detail` names
+  fields, never values). Every reason but `request_unsupported` holds the
+  attachment. The adapters also emit `card_endpoint_refused` with the
+  profile, the endpoint origin and the reason.
+- `PageAmountRequiredError` (`code: 'page_amount_required'`, `psp`): the paused
+  request names no amount and no page total reached the SDK. For Pelecard the
+  total its payment page shows is what ties `amount` to what the page charges,
+  so it is required beside `amount`. Thrown before any authorization exists,
+  and not terminal: the page's next submission reads the total again.
 
 ## Building this package
 
@@ -641,6 +953,29 @@ Allowed, the request continues untouched, the SDK emits `stripe_payment_continue
 and the reason becomes `stripe_payment_continued`. One confirm continues per
 approval; every other follow-up, including an unrelated intent, a changed
 amount and a retry, stays blocked.
+
+A card save can follow a `/v1/payment_methods` approval the same way, once
+Agentcard turns card-save continuations on for your company: the page's
+SetupIntent confirm pays with the approved payment method. A Payment Element
+page that creates the method itself (`paymentMethodCreation: 'manual'`, then
+`confirmSetup({ elements, confirmParams: { payment_method } })`) confirms with
+that method and no card, and the SDK continues the confirm untouched once the
+API allows it. A page whose confirm carries the card again (`confirmCardSetup`
+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
+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
+`{ authorizationId, setupIntentId, rewritten }`, where `rewritten` is true
+when the SDK wrote the approved payment method in place of a card the confirm
+carried, and the reason becomes `stripe_setup_continued`; the merchant then
+keeps the card for later charges. Until your company is turned on, the API
+refuses the check (`continuation_invalid`) and the confirm is aborted, as
+before. Either kind of intent uses up the approval's one continuation.
+
 Unrecognized merchant-server endpoints remain outside this guard unless listed
 in `paymentEndpoints`; this is not a guarantee against a merchant charging a
 saved token on its own server.
@@ -694,6 +1029,8 @@ await page.getByRole('button', { name: 'Pay', exact: true }).click();
 | Adyen | `production` or `sandbox` | The Sessions `/checkoutshopper/v1/sessions/{id}/payments` POST on the matching Adyen host family (`sandbox` is `checkoutshopper-test.adyen.com` with a `test_` client key; `production` is the live hosts with a `live_` key), carrying a fresh card's four encrypted fields |
 | Fiserv | `production` or `sandbox`, with `merchantProfile` | The card frame's `/ch/payments-vas/v1/card-capture` POST on `connect.fiservapis.com` (`production`) or `connect-cert.fiservapis.com` (`sandbox`), carrying a new card's envelope under the key `merchantProfile` names |
 | CyberSource Flex | `production` or `sandbox` | A Microform 2.12.1 card field's `application/jwt` POST to `/flex/v2/tokens` on `flex.cybersource.com` (`production`) or `testflex.cybersource.com` (`sandbox`), sealed under the capture context the field was loaded with |
+| Worldpay eProtect | `production` or `sandbox` | The new-card registration GET to `/eProtect/paypage` on `request.eprotect.vantivcnp.com` (`production`) or `request.eprotect.vantivprelive.com` (`sandbox`), naming the `paypageId` passed to `prepare()`; see "Prepare a Worldpay eProtect checkout (dark launch)" |
+| Amadeus Checkout | `production` or `sandbox` | The Checkout Web SDK's single-card `add` POST to `paypages.payment.amadeus.com/1ASIATP/ARIAPP/pay` (`sandbox`: `paypages.test.payment.amadeus.com/1ASIATP`, `1ASIATPU`, `1ASIATPM` or `1ASIATPK`), whose `Amadeus-Checkout-Sdk-Host` header names the prepared page's host |
 
 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.
 
@@ -734,6 +1071,18 @@ After approval, submit the form once. The Vault replaces the card fields on your
 
 Initial coverage includes the hosted iframe's new-card request. Saved-card CVV updates, Express, wallets, bank accounts and gateway purchase APIs require separate support. A returned card token does not confirm payment; wait for the merchant's result before reporting success. Autopilot is unavailable for Spreedly.
 
+Prepare an Amadeus Checkout card step before the agent clicks Pay:
+
+```ts
+await controller.prepare({ psp: 'amadeus_checkout', environment: 'production' }); // 'sandbox' for Amadeus's test platforms
+```
+
+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`. 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.
+
 Prepare Recurly before clicking the merchant's payment button:
 
 ```ts
@@ -742,6 +1091,49 @@ await controller.prepare({ psp: 'recurly', environment: 'shared' });
 
 After approval, submit the merchant's form once. Recurly's native request timer starts with that submission. The SDK preserves the captured US or EU endpoint and accepts a new-card form only. Legacy JSONP, saved tokens, bank accounts, alternative payments and proactive authentication requests require separate support. Prepared requests also refuse nonempty Worldpay or Cybersource risk results because those sessions can depend on the original card. A nonempty co-badged network preference is also refused until the selected card’s supported networks can be checked. A card token does not confirm a donation, subscription or purchase; confirm the merchant's result before reporting payment success.
 
+### Pay an ACI COPYandPAY checkout
+
+ACI Worldwide's COPYandPAY widget, which Halfords runs, never sends a card in one request. Each of its card iframes posts only its own field to `https://<host>/v1/checkouts/<id>`, and once all of them answered, the page's own form posts `/v1/checkouts/<id>/payment`. ACI launches dark: `syncRegistry()` declares `aci_split_card.v1`, the API serves the ACI recognizer only to an SDK that declares it, and preparation and create answer `processor_unavailable` until Agentcard enables your org.
+
+Prepare before Pay. ACI's widget gives up 60 seconds after Pay:
+
+```ts
+await vault.syncRegistry();
+const controller = await attachToPlaywright(page, { vault, user, merchant, amount: 4210, currency: 'GBP' });
+await controller.prepare({ psp: 'aci', environment: 'production' }); // 'sandbox' for eu-test.oppwa.com and test.oppwa.com
+```
+
+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.
+
+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.
+
+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_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. |
+| `aci_payment_repeated` | A second `/payment` arrives on the same checkout. |
+| `aci_brand_mismatch` | `paymentBrand` is not the brand of the placeholder you typed. |
+| `aci_result_url_refused` | `shopperResultUrl` or `shopOrigin` is off the prepared merchant origin. |
+| `aci_expiry_unstrippable` | The SDK cannot remove the placeholder expiry: the fields are malformed, or the browser is not Chromium. |
+| `aci_payment_unsent` | The browser failed to send a `/payment` the SDK continued. The SDK never sends a second one. |
+| `checkout_interception_not_ready` | A `/payment` arrives after the checkout was cancelled or the attachment stopped. |
+
+An unprepared card-number request throws `PreparationRequiredError` before any create. Click to Pay, wallet and summary-page forms of the widget are not supported.
+
+An attachment keeps no memory of an earlier one. The API reads each checkout from ACI before it creates anything, and on ACI's test platform a paid checkout reads as gone: the API answers a card-number request on it with 409 `aci_checkout_not_payable`, and ACI itself refuses a second card-number request and a second `/payment` on it.
+
+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.
+
 ### Use Checkout Pro in Mexico
 
 Attach the SDK before entering card fields on `www.mercadopago.com.mx`, then prepare the guest card checkout:
@@ -760,7 +1152,7 @@ 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 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 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
@@ -932,6 +1324,663 @@ const checkout = await attachToPlaywright(page, {
 - Autopilot never pays a Flex checkout; the cardholder approves each one on
   their device.
 
+### Pay a Juspay checkout
+
+Swiggy's website pays cards through Juspay Express Checkout, from the page's
+own code. The page first sends the card to Juspay's `/card/tokenize`, then pays
+the order at `/txns` with the token it got back and the security code. A Juspay
+card token pays any order at that merchant for 15 minutes with no merchant
+secret, so the agent's browser never holds a real one, and the placeholder the
+agent typed never reaches Juspay.
+
+```ts
+await vault.syncRegistry(); // the Juspay recognizer is never in the built-in list
+const checkout = await attachToPlaywright(page, {
+  vault, user: 'your-user-id', merchant: 'Swiggy', amount: 49900, currency: 'INR',
+});
+// The agent types a placeholder card and clicks Pay on the merchant's page.
+```
+
+1. The SDK answers the page's `/card/tokenize` itself with a stand-in token
+   (`ctkn_agentcard` and 32 hex digits) that pays nothing anywhere, and refuses
+   the page's `/v2/card/fingerprint` lookup of the placeholder. Swiggy's page
+   carries on without the fingerprint.
+2. The `/txns` that carries that stand-in token pauses, and Agentcard asks the
+   cardholder to approve.
+3. On approval, the cardholder's device tokenizes the real card at Juspay and
+   sends the payment itself. The real token never leaves that device.
+4. The paused `/txns` receives Juspay's answer, cut down to the order id, the
+   transaction id, the status and the bank's verification redirect. The page
+   then opens the bank's check (3DS or a one-time code) in your browser. Report
+   it with `checkout.requestUserAction('3ds')` and confirm the order with the
+   merchant: an approval is not a payment.
+
+- `syncRegistry()` declares `juspay_txns.v1`, and the API serves the Juspay
+  recognizer only for an org Agentcard has enabled, so only then does the SDK
+  take over a Juspay request. For any other org the SDK does not take over
+  Juspay's requests, the same as for a processor it does not pay, and a create
+  for a Juspay request answers `403 processor_unavailable`.
+- Net banking, UPI and wallet payments, a card the shopper saved with the
+  merchant sent with only its stored token and security code, the bank's
+  redirect, CORS preflights and reads pass untouched.
+- The SDK refuses these before any authorization exists: saving the card
+  (`save_to_locker=true`), `tokenize=true`, EMI, a `/txns` that carries the
+  card number, a saved card's payment that carries a new card's fields, and
+  any card request to `api.juspay.io` or `api-ns1.juspay.in`. The controller
+  reads `unsupported` with reason `juspay_request_unsupported`, and the
+  `unsupported_checkout` event names `processor: 'juspay'` and the `reason`.
+  With `onEvent: console.log` on the attachment above, a payment with "save
+  card" ticked logs these three events, and `console.log(checkout.getState())`
+  then prints the last object:
+
+  ```text
+  { type: 'blocked', detail: 'juspay_placeholder_fingerprint' }
+  { type: 'checkout_prepared', detail: { processor: 'juspay' } }
+  {
+    type: 'unsupported_checkout',
+    detail: {
+      url: 'https://api.juspay.in/txns',
+      method: 'POST',
+      processor: 'juspay',
+      reason: 'save_to_locker'
+    }
+  }
+  {
+    status: 'unsupported',
+    authorizationId: null,
+    reason: 'juspay_request_unsupported'
+  }
+  ```
+
+  Untick "save card" and attach again.
+- The SDK refuses three requests alone, each with a `blocked` event: the
+  fingerprint lookup (`juspay_placeholder_fingerprint`), a `/txns` whose
+  stand-in token this attachment never issued (`juspay_unknown_synthetic_token`),
+  and a card request whose body the browser did not hand over
+  (`juspay_request_body_unreadable`).
+- Each `/txns` names its own order. If the page gives up on a paused `/txns`
+  and the agent clicks Pay again, the SDK never answers the new order from the
+  earlier approval: the attachment holds as `outcome_unknown` with reason
+  `merchant_request_aborted` until you reconcile the merchant order.
+- The page decides card eligibility and card offers from the number the agent
+  typed. Type a documented test card of the same network as the stored card,
+  and take no card or bank offers.
+- Juspay's sandbox host (`sandbox.juspay.in`) takes only a test authorization,
+  paid with a documented test card. The API refuses a live authorization naming
+  it with `400 sandbox_host_on_live_row`.
+- Juspay's hosted payment page (HyperCheckout, used by IndiGo) sends the card
+  from Juspay's own page, which the SDK does not take over. Autopilot never
+  pays a Juspay checkout; the cardholder approves each one on their device.
+
+### Pay a Datatrans Secure Fields checkout
+
+British Airways takes cards in Datatrans Secure Fields (PCI Proxy). The card
+number and CVV are Datatrans's own iframes on `pay.datatrans.com`
+(`pay.sandbox.datatrans.com` in test), and the card-number iframe sends the
+whole card in one request: `POST /upp/payment/SecureFields/paymentField`,
+form encoded, in TOKENIZE mode. The SDK pauses that request, the cardholder's
+device sends the real card to Datatrans, and the iframe receives Datatrans's
+token (`transactionId`) and its `cardInfo`: brand, credit or debit, consumer
+or corporate, issuing country and issuer, never a digit of the card.
+
+```ts
+await vault.syncRegistry(); // the Datatrans recognizer is never in the built-in list
+const checkout = await attachToPlaywright(page, {
+  vault, user: 'your-user-id', merchant: 'British Airways', amount: '189.90', currency: 'GBP',
+});
+```
+
+- **Dark launch.** `syncRegistry()` declares the
+  `datatrans_secure_fields_tokenize` capability, and the API serves the
+  Datatrans recognizer only to an org Agentcard has enabled for it. Every
+  other org's SDK leaves Datatrans requests alone, as before.
+- **Pass the amount.** The card request names no amount: the merchant charges
+  the token later, from its own server. The `amount` and `currency` you pass,
+  or the page total when you pass none, are what the approval shows. Without
+  either the create answers `amount_required`.
+- **What pauses.** Only the card-number iframe's TOKENIZE post of a new card.
+  A post Datatrans's own iframe would not send for that flow (another mode, a
+  payment or 3-D Secure post, a key the iframe never writes, a URL variant, a
+  content type other than jQuery's form type) is aborted with a `blocked`
+  event, detail `invalid_datatrans_request`. Nothing is created, nobody is
+  prompted, the controller's state does not change, and the page's next post
+  is judged afresh. Wallet, bank-account and CVV-only posts carry no card
+  number and continue untouched, and so do the iframe documents and the BIN
+  lookup (`paymentField/cardInfo`).
+- **Card on file.** A post with `usage=REGISTRATION` asks PCI Proxy for a
+  reusable alias and a network token, so the merchant could charge the card
+  again without another approval. The API serves Agentcard's card-on-file
+  policy with the Datatrans recognizer (`cardOnFile`), and the SDK reads it at
+  each `syncRegistry()`. While it is `refuse`, as it is today, the post is
+  aborted with a `blocked` event, detail `datatrans_card_on_file_refused`,
+  before any create. British Airways's Nexus checkout sends it for every new
+  card, so a Nexus checkout is refused this way for now. When the policy
+  allows card on file, the post pauses like any other and the approval
+  applies the policy; no SDK release is needed.
+- **The same form, submitted again.** British Airways submits the form again
+  whenever a field loses focus or the expiry changes. Once a post was
+  approved, a later post from the same iframe that differs from it only in
+  the expiry (`expm`, `expy`) and the browser details is answered with the
+  same token and `cardInfo`: no second prompt, no second card sent. The
+  adapters emit `repeat_answered` with the `authorizationId`; it is not a
+  second payment and must not be counted as one. Any other change (a new
+  `formId` from a reloaded iframe, another placeholder card or CVV, another
+  email or phone number) is a new approval. The answer lasts while that
+  approval is the checkout's current one, up to the token's 30-minute
+  lifetime: once the order completes or fails, the attachment stops, or
+  another authorization starts, the form is judged again like any card post.
+  It also ends once the form has posted nothing for five minutes. Once the
+  token reached the page, the merchant can already hold an order paid with
+  it, and the post names no amount or order, so before each later re-submit
+  the SDK calls your `resolveMerchantResult` and answers only while it
+  reports `pending`; that call changes no checkout state. A completed,
+  failed or unknown order, a resolver that throws, or one that has not
+  answered within five seconds makes the re-submit a new question, and an
+  attachment with no `resolveMerchantResult` answers no
+  re-submit after the token reached the page: each one asks the cardholder
+  again.
+- **Type a placeholder of the card's brand.** The iframe names the brand
+  (`paymentMethod`) from the digits the agent types, and British Airways's 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.
+- **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`).
+- Autopilot never pays a Datatrans checkout; the cardholder approves each one
+  on their device. `pay.sandbox.datatrans.com` takes only a test-mode client
+  and `pay.datatrans.com` only a live one.
+
+### Pay a Pelecard checkout
+
+Pelecard's hosted payment page (Iframe/Redirect 2.0) runs at
+`https://gateway21.pelecard.biz/PaymentGW?transactionId=...` (`gateway20` on
+older terminals), in the merchant's iframe or top level. When the buyer clicks
+Pay, the page sends the card in one XHR to its own `/PaymentGW/Transaction`.
+The SDK pauses that request, the cardholder approves on their phone, their
+device sends the real card to Pelecard, and the page receives Pelecard's
+answer, so its own script takes the buyer to the merchant's landing page.
+
+Pelecard ships dark: `syncRegistry()` asks for the `pelecard_transaction`
+capability, and the API serves the recognizer only to an org Agentcard has
+enabled for Pelecard, in test mode only. For every other org the SDK leaves
+Pelecard's requests alone.
+
+```ts
+await vault.syncRegistry();
+const checkout = await attachToPlaywright(page, {
+  vault, user: 'user_123', merchant: 'Uman tourist tax',
+  amount: 2700, currency: 'usd', // required: the request names no amount
+  pageAmount: async () => {
+    // Required: the total Pelecard's page shows, which the API holds against `amount`.
+    const frame = page.frames().find((f) => /^https:\/\/gateway2[01]\.pelecard\.biz\/PaymentGW\b/.test(f.url()));
+    const shown = await frame?.evaluate(() => {
+      const p = (globalThis as any).generalParameters;
+      return p ? { total: p.total, currencyCode: p.currencyCode } : null;
+    });
+    if (typeof shown?.total !== 'number' || typeof shown?.currencyCode !== 'string') return undefined;
+    return { amount: Math.round(shown.total * 100), currency: shown.currencyCode.toLowerCase() }; // two-decimal currencies
+  },
+});
+```
+
+- Pass `amount` and `currency`. Pelecard bound the total, the currency and
+  the action (a charge, a card registration or a hold) to the payment page
+  when the merchant created it, so the submission names none of them. The
+  pair you pass is what the cardholder approves; without it the submission
+  fails with `AmountRequiredError` before anything is created. No Pelecard
+  answer states an amount either, so confirm the order with the merchant.
+- Pass the page's total as `pageAmount`. It is the one figure that ties
+  `amount` to what the merchant bound to the payment page, so a submission
+  without it fails with `PageAmountRequiredError` before anything is created,
+  and the page's next submission reads it again. The API refuses a create
+  without it (`page_amount_required`), a total of 0 (a card registration or a
+  hold of an amount the page does not show) and a total that disagrees with
+  `amount` (`amount_mismatch`).
+- Before any prompt, the SDK refuses a submission that asks Pelecard to keep
+  the card on file (the buyer ticked "save my card", or the body sets
+  `CreateToken`) as `pelecard_keep_on_file_unsupported`: the merchant could
+  charge that card again without another approval, and the approval cannot
+  ask the cardholder yet. Anything else the page's one-time card payment
+  never sends (a saved token, a card track, a phone authorization,
+  installments, a buyer-typed total, a key the page does not build) is
+  `invalid_pelecard_request`. Both arrive as a `blocked` event, the page's
+  request is aborted, nothing is created, and the page's next submission is
+  judged afresh. A merchant can still set `CreateToken` when it creates the
+  payment page, which no request shows.
+- The page's other tabs post to the same URL with no card (Bit, wallets, the
+  PIN pad, bank transfer) and continue untouched.
+- The page waits up to ten minutes for the answer, and Pelecard's payment
+  session is expected to last about as long from page load, so the approval
+  has to land inside it. A 3-D Secure answer is never read as approved:
+  reconcile that payment with the merchant.
+
+### Pay a CreditGuard checkout
+
+CreditGuard's hosted payment page (Hyp PPS, `pps.creditguard.co.il`; SeboCalm frames it) sends the card in one request, `POST /services/v1/txn/{txId}/process`, and that request is the sale itself: it names neither the amount nor the merchant. So a CreditGuard payment always starts with a preparation that names the page the checkout framed, the iframe's own address:
+
+```ts
+const pps = page.frames().find(frame => /^https:\/\/(pps|pps2|ppsuat)\.creditguard\.co\.il\/\?/.test(frame.url()));
+await controller.prepare({ psp: 'creditguard', environment: 'production', paymentPageUrl: pps!.url() });
+// 'sandbox' for CreditGuard's UAT page on ppsuat.creditguard.co.il
+```
+
+Agentcard reads that transaction from CreditGuard before the cardholder is asked. Pass the `amount` and `currency` CreditGuard holds (ILS in agorot: `24000` is 240.00 ILS); another pair is refused as `amount_mismatch`. A page the Vault cannot finish (3-D Secure, OTP, currency conversion, installments, a required Israeli ID, or a form that hides a card field or asks for a field the cardholder's device does not fill) is refused as `creditguard_transaction_refused`, with CreditGuard's reason in `detail`. The merchant page must be HTTPS under a dotted hostname, because every submit names it.
+
+After the approval, click the page's Pay once. Only the page's own new-card submit for that transaction pauses: the cardholder's device sends the real card to CreditGuard, and the page reads CreditGuard's answer, rebuilt from payment-core's allow-list, then moves on to the merchant's landing page. The page's card lookup, its transaction read and every other request continue untouched with your placeholder, so type a foreign test number.
+
+A submit the device would not fill is aborted before anything is created, with a `blocked` event `{ reason: 'creditguard_request_unsupported', refusal }`: `keep_on_file` ("save my card"), `installments`, `dcc`, `personal_id`, `saved_card`, `wallet` and the like. The preparation stays ready, so untick the option and click Pay again. Without a ready preparation the submit is refused with `PreparationRequiredError`. CreditGuard's own 3-D Secure call to Nuvei, from its page or from any frame inside it, is refused, and the attachment reads `unsupported` with reason `creditguard_three_d_secure`; it is never approved as a Nuvei payment. Autopilot never pays CreditGuard.
+
+### Pay a Primer checkout
+
+Primer launches dark: `syncRegistry()` declares the
+`primer_payment_instruments` capability (in `SUPPORTED_CAPABILITIES`), and the API
+serves the Primer recognizer only to an org Agentcard has enabled for Primer.
+For every other org nothing changes: Primer's requests are never paused and
+never refused.
+
+For an enabled org, the SDK pauses one request: the card tokenization that
+Primer Web SDK v2 (Printful loads v2.63.0) sends from its hidden api-controller
+frame on `https://sdk.primer.io` when the shopper pays with a new card. That is a
+`POST` to `https://sdk.api.primer.io/payment-instruments` (sandbox
+`sdk.api.sandbox.primer.io`) as JSON, with the card at
+`paymentInstrument.number`. The frame is cross-origin, and both adapters pause
+the request inside it. The cardholder's device fills the real card into the
+paused body and sends it to Primer itself. The page receives only Primer's
+answer: one single-use card token, rebuilt from an allow-list and handed over
+under a JSON content type. Any other answer on an approved authorization, such
+as a multi-use token or a saved card, throws `PaymentOutcomeUnknownError` with
+reason `primer_token_unconfirmed`.
+
+```ts
+await vault.syncRegistry();
+const controller = await attachToPlaywright(page, {
+  vault, user: 'usr_123', merchant: 'Printful',
+  amount: 2599, currency: 'usd', // Primer's request names no amount
+});
+```
+
+Primer's request names no amount: Primer's SDK or the merchant's server charges
+the token later. Pass `amount` and `currency`, or let the page total
+(`pageAmount`, or `[data-agentcard-amount]`) name the price: that is what the
+cardholder approves. With neither, the API answers 400 `amount_required` before
+anything is created, and the attachment reads `failed`. A 3-D Secure challenge
+that follows the token runs in your browser: call `requestUserAction('3ds')`
+when you see one.
+
+Primer's SDK stamps `preferredNetwork` from the digits typed, and the
+cardholder's device refuses one that is not the paying card's own network. Type
+a placeholder of the same network as the card that pays.
+
+The other requests on Primer's hosts:
+
+- A wallet tokenization with no card (PayPal, Apple Pay, Google Pay, Klarna) and
+  a saved-card exchange continue untouched.
+- A tokenization that asks Primer to save the card (`tokenType: "MULTI_USE"` or
+  `paymentFlow: "VAULT"`) is aborted alone, with a `blocked` event,
+  `primer_keep_on_file`. The attachment is not held: clear the page's save-card
+  choice and pay again.
+- A card request from Primer Checkout (`@primer-io/primer-js`), whose frame gives
+  up on its own request after 30 seconds, is aborted as `unsupported_checkout`
+  with reason `unsupported_primer_sdk`, and any other card request the v2 frame
+  would not send with `unsupported_primer_request`. The attachment reads
+  `unsupported` with that reason and holds, since the merchant's integration
+  decides that shape.
+- A request whose body the SDK cannot read is aborted alone, with a `blocked`
+  event, `unreadable_primer_request`.
+
+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`.
+
+### 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
+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
+page's session answers are not read.
+
+```ts
+await vault.syncRegistry();
+const controller = await attachToPlaywright(page, {
+  vault, user: 'usr_123', merchant: 'Blacklane',
+  amount: 8900, currency: 'eur', // the save names no amount: this, or the page total, is what the cardholder approves
+});
+```
+
+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.
+
+What the SDK refuses, before anything is created, with the reason on the
+`unsupported_checkout` event:
+
+- A save that keeps the card on file (`storeInstrument: true` or
+  `UnscheduledCardOnFile`, which Blacklane sends on every save):
+  `payrails_card_on_file_consent_required`, until the cardholder can consent to
+  it. A `Subscription` save (`payrails_future_usage_refused`) and a body that is
+  not the Payrails SDK's own (`payrails_request_malformed`,
+  `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
+  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)
+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
+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.
+
+### Pay an Elavon Converge payment page
+
+Elavon Converge's Hosted Payment Page is where NY DMV's payment apps send the
+browser: Converge's own page at
+`https://api.convergepay.com/hosted-payments/?ssl_txn_auth_token=...`, at top
+level. When the buyer clicks Pay, the page posts the card as one JSON request
+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
+`api.demo.convergepay.com`, which pays in test mode only.
+
+Converge ships dark: `syncRegistry()` asks for the `converge_hpp_process`
+capability, and the API serves the recognizer only to an org Agentcard has
+enabled for Converge. For every other org the SDK leaves Converge's requests
+alone.
+
+```ts
+await vault.syncRegistry();
+const checkout = await attachToPlaywright(page, {
+  vault, user: 'user_123', merchant: 'NY DMV',
+  // No amount: the request names its own (ssl_amount, US dollars), and that is what the cardholder approves.
+});
+```
+
+- No `amount` is needed. The request's `ssl_amount` is the amount the
+  cardholder approves; an `amount` and `currency` you pass must agree with it.
+- Every Converge payment waits for the cardholder's own approval. An autopilot
+  grant never pays one.
+- Electronic check and financing payments on the same URL carry no card and
+  continue untouched.
+- 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.
+- 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
+  `converge_step_unsupported` and nothing charged, `authorize()` throws
+  `ProcessorRefusedError` with that `pspErrorCode`, and the page shows its own
+  decline.
+- One payment per payment page. A second authorization for the same page
+  session or invoice gets `duplicate_submission` for 15 minutes after the
+  first card could last have left the device: confirm the payment with the
+  merchant before trying again.
+
+A refused payment reaches your `onEvent` as a `blocked` event whose `detail` is
+the code. This is what `onEvent` received when the agent paid with Google Pay
+on Converge's page, printed by the SDK's own Chromium test (in
+`packages/checkout`: `npm run build`, then
+`node elavon-converge-browser.test.mjs "playwright Google Pay"`):
+
+```text
+PASS playwright Converge Google Pay, then the card form; onEvent received {"type":"blocked","detail":"converge_wallet_refused"}
+1 local Chromium Converge scenarios passed; no Converge host, demo account or live merchant was contacted.
+```
+
+The page's own request then fails the way a dropped connection does (its XHR
+ends with status 0), and the page keeps its session, so the buyer can pay with
+the card form next.
+
+#### Converge refusal codes
+
+The first 22 codes arrive as the `blocked` event's `detail`, before any
+authorization exists, and the API answers a create that carries one with a 400
+of the same code. `converge_step_unsupported`, `converge_declined` and
+`converge_session_timeout` arrive after the cardholder approved, as
+`ProcessorRefusedError.pspErrorCode`. `duplicate_submission` is the create's
+409, as `CheckoutApiError.code`.
+
+| Code | What it means | What to do next |
+|---|---|---|
+| `converge_wallet_refused` | The buyer paid with a wallet (Google Pay, Apple Pay or Visa Checkout), so the card number came from the wallet, not from a card the cardholder approves. | Pay with the page's card form; the next payment is judged afresh. |
+| `converge_debit_card_refused` | The payment came from the page's debit card tab. | Pay with the credit card form. |
+| `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_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. |
+| `converge_amount_add_on_refused` | The payment adds a tip or cash back to `ssl_amount`. | Pay again without the tip or cash back. |
+| `converge_card_saving_refused` | The body asks Converge to keep the card (`ssl_get_token` or `ssl_add_token`), or pays with a card Converge stored (`ssl_token`). | Pay again with the typed card and card saving off. |
+| `converge_recurring_refused` | The body sets up recurring or installment charges. | Pay the amount as one payment. |
+| `converge_currency_refused` | The payment is in a currency other than US dollars. | The buyer pays this one without Agentcard: Agentcard pays Converge in US dollars only. |
+| `converge_amount_missing` | The body names no amount it can read, or an amount of zero. | Start a new checkout from the merchant's page. |
+| `converge_context_missing` | The body carries no payment page session (`context`). | Start a new checkout from the merchant's page. |
+| `converge_body_malformed` | The body is not the page's own JSON, byte for byte, or carries a key the page never writes. | Let the page send its own request; never rewrite it. |
+| `converge_credential_refused` | The body names Converge account credentials, which the page never sends. | Let the page send its own request. |
+| `converge_card_missing` | The body carries no card number. | Type the placeholder card into the page's own card fields. |
+| `converge_card_malformed` | The card number, expiry or security code is not in the page's own format. | Type the placeholder card into the page's own card fields. |
+| `converge_url_refused` | The request is not sent to the exact `hpp/process` URL. | Let the page send its own request. |
+| `converge_method_refused` | The request is not a POST. | Let the page send its own request. |
+| `converge_content_type_refused` | The request's content type is not JSON. | Let the page send its own request. |
+| `converge_step_unsupported` | After the approval, Converge answered with a 3-D Secure 2, Pay Defense, currency, surcharge or debit bypass step, which comes before any authorization. Nothing was charged. | Confirm with the merchant, then have the buyer pay without Agentcard: the Vault cannot complete that step yet. |
+| `converge_declined` | Converge declined the card. | Check the merchant's payment status, then start a new checkout to try again. |
+| `converge_session_timeout` | Converge's payment page session ended before the payment. Nothing was charged. | Start a new checkout from the merchant's page. |
+| `duplicate_submission` | An earlier authorization holds this payment page session or invoice: it awaits the cardholder, was approved, or ended without a recorded outcome. | Wait for that authorization, or confirm the payment with the merchant before trying again. |
+
+### Prepare a Worldpay eProtect checkout (dark launch)
+
+Worldpay eProtect (Vantiv, Litle PayPage) support ships dark. Worldpay's script
+encrypts the card in the page and sends it as the
+query of one JSONP `<script>` GET to `/eProtect/paypage` on
+`request.eprotect.vantivcnp.com`, or on `request.eprotect.vantivprelive.com`
+(Worldpay's pre-live host, the `sandbox` environment), then reads the answer
+from the script's own callback. `syncRegistry()` declares the
+`worldpay_eprotect_jsonp` capability, and the API serves the eProtect
+recognizer to a build that declares it only for an org Agentcard has enabled.
+For every other org the API serves no eProtect recognizer and answers
+`processor_unavailable` to an eProtect preparation or create, so the SDK leaves
+eProtect traffic exactly as it found it, as it does before a sync.
+
+The merchant's script gives up on the registration 10 to 15 seconds after Pay,
+and re-sends it to a failover host after 5, which is too soon for a prompt that
+waits on a person. An eProtect checkout is therefore always prepared:
+
+```ts
+const checkout = await attachToPlaywright(page, {
+  vault, user: 'your-user-id', merchant: 'Example merchant',
+  amount: 4210, currency: 'usd',
+  cardId: 'vc_...', // required: the stored card that pays
+  onApprovalUrl: deliverPrivatelyToCardholder,
+});
+await checkout.prepare({ psp: 'worldpay_eprotect', environment: 'production', paypageId: 'MerchantPaypageId' });
+await page.getByRole('button', { name: 'Place order', exact: true }).click();
+```
+
+- `paypageId` is the merchant's eProtect paypageId: the Worldpay merchant the
+  registration is for, which is also the merchant Worldpay lets charge the card
+  again. It is fixed before the page sends anything, so a registration naming
+  another paypageId never spends the approval. The Worldpay iframe names it in
+  its URL (`/eProtect/payframe_<paypageId>_...`); a JS API merchant carries it
+  in its eProtect configuration.
+- `cardId` is required, and the approval is locked to that card. Worldpay never
+  receives an expiry: the merchant sends the one typed into its form with the
+  registration. The agent types a placeholder number of the stored card's
+  network, the security code `000`, and the stored card's real expiry
+  (`expiry_month` and `expiry_year` from `GET /v2/vault_cards`) before it
+  prepares.
+
+After Pay, the SDK pauses the registration and binds it to the preparation.
+The cardholder's device, still on the approval page, encrypts the approved card
+under Worldpay's key into that same query and sends it through Agentcard's
+encrypted relay. The SDK then answers the paused script as Worldpay would:
+the registration in the script's own callback, under Worldpay's script type,
+with only the fields the merchant needs (no first six or last four digits).
+The SDK reads the authorization every 500 ms for 15 seconds, so the answer
+lands inside the merchant's window. A registration is not a payment: the
+merchant authorizes it with the typed expiry, so confirm the order with the
+merchant.
+
+| Request on eProtect's hosts | What the adapters do |
+| --- | --- |
+| The registration GET naming the prepared `paypageId`, on the prepared environment's host | Paused, bound to the preparation and answered |
+| A registration with no ready preparation | Refused locally with `PreparationRequiredError`; nothing is created |
+| A registration for another `paypageId` or host | Refused, and the preparation is retired (`checkout_changed`) |
+| The vendor's re-send with `targetServer=secondary` (`secondary.eprotect.vantivcnp.com`, or the pre-live host itself) of a registration the attachment saw | Aborted quietly (`blocked` event, `eprotect_failover_aborted`); it never prompts or claims a preparation |
+| Any other request on `/eProtect/paypage`: CVV-only, PIN, wallet or private-label variants, the native-app Mobile API form post, a re-send of nothing the attachment saw | Aborted as `unsupported_checkout` |
+| `/eProtect/ppstats` reporting `900` or `901` for the running registration | The report continues, and the approval ends as `merchant_request_aborted` (event `merchant_request_abandoned`) |
+| The vendor's scripts, the payframe and every other report | Continue untouched |
+
+Worldpay's script sends `900` or `901` when the merchant's timeout passed with
+no answer. The SDK then cancels the authorization, which the API confirms only
+before the device sent the registration, and fails the paused script instead of
+answering it. When the answer had already reached the page, the controller
+moves to `outcome_unknown`.
+
+`prepare()` refuses locally with `CheckoutPreparationError` reason
+`paypage_id_invalid` (missing or not 1 to 64 letters and digits, or passed for
+another processor) or `card_required`, and with `ready_unconfirmed` when the
+API confirms another paypageId or card. A live checkout (`environment:
+'production'`) needs a Worldpay merchant that payment-core pins for its
+paypageId at the merchant origin, and `merchant` must be that pin's name, the
+one the approval shows. The API refuses another name with
+`merchant_profile_mismatch` and a paypageId with no pin with
+`unsupported_checkout`, before any preparation exists; when this release pins
+the paypageId too, the SDK refuses another name first, before any network call.
+Agentcard has pinned no production merchant yet, so the API refuses every live
+eProtect checkout today; the pre-live host needs no pin. An approved answer that is not a
+registration for the paused request raises `PaymentOutcomeUnknownError` with
+reason `eprotect_registration_unconfirmed`: the device may have registered the
+card, so reconcile the merchant before trying again.
+
+The SDK covers only Worldpay's own eProtect hosts, and does not pause a
+registration a merchant sends to an eProtect domain it names itself. The SDK
+does not support a merchant timeout of 5 seconds or less. The pre-live host
+receives only Worldpay's documented test cards. Autopilot never pays eProtect.
+The matching API, Vault and relay releases are required.
+
+### Pay a WSPay Components checkout
+
+Hotel booking pages such as Valamar's take cards in WSPay Components, WSPay's
+build of Monri Components. The card field is WSPay's own iframe on
+`proxy.wspay.biz` (`proxy-test.wspay.biz` in test), and it sends the card in one
+request from that frame: `POST /v2/payment/{client_secret}/confirm`. The SDK
+pauses that request, the cardholder's device sends the real card to WSPay, and
+the frame receives WSPay's answer.
+
+```ts
+await vault.syncRegistry(); // the WSPay recognizer is never in the built-in list
+const checkout = await attachToPlaywright(page, {
+  vault, user: 'your-user-id', merchant: 'Example Hotel', amount: '412.30', currency: 'EUR',
+});
+```
+
+- **Dark launch.** `syncRegistry()` declares the `wspay_confirm` capability,
+  and the API serves the WSPay recognizer only to an org Agentcard has enabled
+  for WSPay. Until then your SDK leaves every WSPay request as it did before
+  this release: none is paused or refused. If Agentcard turns WSPay off for
+  your org after a sync, the next create answers `403 processor_unavailable`
+  and nothing is charged. `proxy-test.wspay.biz` takes only a test-mode client
+  and `proxy.wspay.biz` only a live one.
+- **Pass the amount.** The confirm names no amount: WSPay fixed it when the
+  merchant's server created the payment. The `amount` and `currency` you pass
+  are what the approval shows. When WSPay approves at once, its answer names
+  the amount and the API compares the two: a different amount reads
+  `amountVerified: false` and the controller holds with reason
+  `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`),
+  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
+  created, nobody is prompted, the controller's state does not change, and the
+  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.
+- **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`
+  with reason `3ds`, and `onUserAction` receives the same reason: show the
+  challenge to the cardholder, then `reconcile()` the merchant's order. After
+  the challenge WSPay charges the amount the merchant's server set, and no
+  answer Agentcard receives names it: `amountVerified` stays `null`. Read the
+  charged amount from the merchant's order and compare it with the one the
+  cardholder approved before you report the purchase complete.
+- **The client_secret** in the confirm URL is a per-payment secret. `redactUrl`
+  and every event report the URL as
+  `https://proxy.wspay.biz/v2/payment/{client_secret}/confirm`.
+- Autopilot never pays a WSPay checkout; the cardholder approves each one on
+  their device. Monri Components on `ipg.monri.com` and the WSPay Form hosted
+  page are not covered.
+
+### Verifone merchants that encrypt the card in the 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.
+- 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.
+
+```ts
+await controller.prepare({ psp: 'verifone', environment: 'production', merchantProfile: 'containerstore_checkout' });
+```
+
+The environment is the one of the key the profile pins. The cardholder approves a payment to the merchant the profile names, whatever label the agent passed. After approval, click Pay once. The SDK sends the API the profile id with the paused request (`verifone: { profile }`, never Autopilot). The API checks the body against the profile, holds the agent's amount to the one the body names, and keeps only the SHA-256 of the body and of the page's blob. The cardholder's device encrypts the approved card the way verifone.js does, under the key Agentcard pinned for that merchant, never a key from the page. The approval comes back as a `cse` replay with `kind: 'verifone'`, and the request continues from your browser with the device's blob in place of the page's, but only if the live body still hashes to the body the API checked (`bodySha256`). The blob pays the merchant for 15 minutes, so the API serves it only in the moments after the approval. After hand-off, the merchant's server charges the card and answers its own page, and the outcome rules above for Adyen merchants apply unchanged.
+
+A raw CDP runtime arms `vault.verifoneProfileUrlPatterns()` after `syncRegistry()`, reads `vault.verifoneProfileOf(url)` and `classifyVerifoneProfileRequest(profile, url, method, body)` for each paused request (`body` is `''` for a request with no body), and writes a Verifone approval with `substituteVerifoneBody({ url, method, body }, replay)`. Never continue a body that carries a verifone.js blob to a profile's origin unless `authorize()` paid it.
+
 ### Unsupported endpoints
 
 `paymentEndpoints` is an explicit list supplied by the integrator after observing