@agent-cards/sdk 0.23.28 → 0.24.1

package/dist/client.js

@@ -22,13 +22,14 @@ import { TAP_PAYMENTS_PSP, isTapPaymentsServedSubstitution } from './tap-payment
 import { WIX_PAYMENTS_PSP } from './wix-payments.generated.js';
 import { HIPAY_PSP } from './hipay.generated.js';
 import { OPENPAY_PSP, openpayAnswerOutcome } from './openpay.generated.js';
+import { VTEX_PAYMENTS_PSP } from './vtex-payments.generated.js';
+import { PROCESSOUT_PSP, processoutAnswerOutcome } from './processout.generated.js';
 import { TOAST_PSP, isToastCiphertext } from './toast.generated.js';
 import { classifyStripeCheckoutRequest, encodeStripeCheckoutContext, hasStripeCheckoutMarker, parseStripeCheckoutContext, parseStripeCheckoutResponse, STRIPE_CHECKOUT_CONTEXT_HEADER, } from './stripe-checkout.generated.js';
-import { VoiceModule } from './voice.js';
 import { BuyModule } from './buy.js';
-import { Languages } from './languages.js';
+import { ApprovalsModule } from './approvals.js';
 import { RequestRegistry } from './requests.js';
-import { AgentcardError } from './voice-types.js';
+import { AgentcardError } from './api-types.js';
 import { HYPHEN, SLASH, maskUuids } from './url-mask-parts.js';
 import { URL_MASKS } from './url-masks.generated.js';
 import { DECLARED_CAPABILITIES } from './capabilities.generated.js';
@@ -114,6 +115,15 @@ export const SUPPORTED_REGISTRY_FEATURES = ['card_fields', 'checkout_sessions'];
  * recognizer is never in BUILTIN_REGISTRY, so a build reaches it only through a
  * sync that declares its capability, and whether an org may pay through it
  * stays the API's decision.
+ * `bluesnap_hosted_payment_fields`: BlueSnap's Hosted Payment Fields, whose card
+ * number, expiry and code frames each PUT their own field as JSON to the
+ * merchant's payment-fields token. This build pauses the card number PUT, holds
+ * the expiry and code PUTs and answers them with its answer (aci.ts, the JSON
+ * split card), and the cardholder's device sends the whole card in that one PUT
+ * (payment-core processors/bluesnap.js). The request names no amount, so the
+ * agent's pair, above zero, is the one the cardholder approves. Served on the
+ * same terms: only to a build that lists it, for a company Agentcard turned
+ * BlueSnap on for.
  * `creditguard_pps_process`: CreditGuard's hosted payment page (Hyp PPS), whose
  * card submit this build pays only under a prepared checkout that names the
  * framed page (prepare({ psp: 'creditguard', environment, paymentPageUrl })). The
@@ -452,6 +462,18 @@ export const SUPPORTED_REGISTRY_FEATURES = ['card_fields', 'checkout_sessions'];
  * page the create names. Served on the same terms: only to a build that lists it, for a company
  * Agentcard turned Pin Payments on for.
  *
+ * `paymentwall_card_token`: the card request Paymentwall's card form (Brick) sends, from its number
+ * frame on pwgateway.com inside Paymentwall's hosted widget or from a merchant's own page: a form POST
+ * to https://pwgateway.com/api/token (https://api.paymentwall.com/api/brick/token for a test key)
+ * under the merchant's public key. This build pauses only the card form's own body at those exact
+ * URLs (payment-core processors/paymentwall.js); a stored card's code, a wallet's token, a brand from
+ * the page's select or any other body there fails in the browser before anything is created. The
+ * cardholder's device sends the request itself with the real card, and the page gets the token answer
+ * payment-core's judge rebuilt. The request names no amount, so the agent's pair, above zero, is the
+ * one the cardholder approves, and the API pays only a Paymentwall project payment-core pins for the
+ * checkout page the create names. Served on the same terms: only to a build that lists it, for a
+ * company Agentcard turned Paymentwall on for.
+ *
  * `sbps_token_jsonp`: SB Payment Service's card token request, the JSONP <script>
  * GET its token script sends to /token/generateToken on token.sps-system.com. This
  * build pauses it only as the browser writes it, aborts any other request on that
@@ -468,6 +490,56 @@ export const SUPPORTED_REGISTRY_FEATURES = ['card_fields', 'checkout_sessions'];
  * Served on the same terms, and the API holds the lane to Agentcard's own company
  * until a reviewed change binds the client key to the merchant.
  *
+ * `iyzico_checkout_form`: the card payment iyzico's Checkout Form posts as one JSON request to
+ * api.iyzipay.com/payment/iyzipos/checkoutform/auth/ecom, or initialize3ds/ecom for 3-D Secure
+ * (sandbox-api.iyzipay.com in test), under the form's X-IYZI-TOKEN. This build pauses only the
+ * form's own payment with a new card at those exact URLs (payment-core processors/iyzico.js); a saved
+ * card, a card kept on file, installments and a currency conversion fail in the browser before
+ * anything is created. The cardholder's device sends the payment itself, and the page gets iyzico's
+ * answer as payment-core's judge rebuilt it: the payment done, or the bank's 3-D Secure page, which
+ * the form then runs in the agent's browser. The payment names its price but not its currency, so
+ * authorize() needs the agent's pair, and the API holds its amount to the price. Served on the same
+ * terms, and the API holds the lane to Agentcard's own company.
+ *
+ * `aurus_one_time_token`: the card request Aurus Pay's ecom card frame (O'Reilly Auto Parts) sends to
+ * pecst<NN>.aurusepay.com/storeservices/ecom/oneTimeToken, the card sealed in the frame under a public key its own
+ * script carries. This build pauses it only when Aurus's card frame sent it (aurus.ts aurusPreClaim); the same
+ * request from the store's page or another frame fails in the browser before anything is created. The request
+ * names no amount, so authorize() needs the agent's pair, above zero. The cardholder's device does not seal for
+ * Aurus yet (payment-core processors/aurus.js), so a paused request opens no approval that pays.
+ *
+ * `viva_smart_checkout_chargetoken`: the card request Viva Wallet's Smart Checkout page sends as one
+ * JSON request to www.vivapayments.com/web2/checkout/v2/chargetokens (demo.vivapayments.com in test),
+ * on Pay, after the page's own reCAPTCHA run. This build pauses only the page's own card body at that
+ * exact URL (payment-core processors/viva_wallet.js); a body that keeps the card, pays with a stored
+ * card, converts the currency or is the page's second try after a decline fails in the browser before
+ * anything is created. The cardholder's device sends the card through Agentcard's checkout relay, since
+ * the page's request answers no other origin, and the page gets Viva's single-use charge token as
+ * payment-core's judge rebuilt it; the page then charges that token card free. The body names its
+ * amount, which the API holds to the agent's pair, and the API pays a live token only for an order
+ * payment-core pins. Served on the same terms, and the API holds the lane to Agentcard's own company.
+ *
+ * `paystack_pinned_key`: the charge Paystack's hosted checkout sends as one form POST to
+ * standard.paystack.co/charge/, the card only as `clientdata`, RSA ciphertext under the one key
+ * Paystack's page carries. This build pauses only the card page's own charge at that exact URL
+ * (payment-core processors/paystack.js); a charge that keeps the card, starts a plan or carries a PIN
+ * fails in the browser before anything is created. The cardholder's device encrypts the real card under
+ * the same pinned key and sends the charge itself, and the page gets Paystack's answer: paid, declined,
+ * or the issuer's 3-D Secure step, which the page then runs in the agent's browser. The charge names
+ * no amount, so authorize() needs the agent's pair, above zero. Served on the same terms, and the API
+ * holds the lane to Agentcard's own company.
+ *
+ * `usaepay_payment_key`: the card request USAePay's Pay.js card frame sends as one JSON request to
+ * www.usaepay.com/api/v2/pub/payment_keys (secure.usaepay.com alike; sandbox.usaepay.com in test), under
+ * the merchant's public key in its Authorization. This build pauses only the frame's own card body at
+ * that exact URL (payment-core processors/usaepay.js); a Google Pay or Apple Pay token and a bank
+ * account on the same URL fail in the browser before anything is created. The cardholder's device sends
+ * the card through Agentcard's checkout relay, since USAePay answers no browser origin, and the frame
+ * gets USAePay's single-use payment key as payment-core's judge rebuilt it; the merchant's server
+ * charges that key afterwards. The request names no amount, so authorize() needs the agent's pair, and
+ * the API pays a live key only to a merchant payment-core pins for the checkout page. Served on the same
+ * terms, and the API holds the lane to Agentcard's own company.
+ *
  * `tap_card_sdk_token`: the token request Tap Payments' card frame sends to sdk.tap.company, carrying
  * the card only as one ciphertext the frame writes under the merchant's own RSA key. This build pauses
  * it and writes over the placeholder's ciphertext the one the cardholder's device wrote under the key
@@ -495,6 +567,41 @@ export const SUPPORTED_REGISTRY_FEATURES = ['card_fields', 'checkout_sessions'];
  * (agent-amount-processors.json), is the one the cardholder approves. Served on the same terms: only
  * to a build that lists it, for a company Agentcard turned Openpay on for.
  *
+ * `processout_card_token`: the card request ProcessOut.js's card frame sends from js.processout.com to
+ * api.processout.com/cards under the store's project id, only through a prepared checkout: the frame
+ * gives the page 20 seconds from the shop's continue press, so the cardholder approves before it. The
+ * card URL names the project in its query, so the claim binds the request by its project's environment
+ * and its shape, never by the prepared URL. The cardholder's device sends the card to ProcessOut itself
+ * and the frame gets back ProcessOut's token alone, rebuilt by payment-core's judge. The request names
+ * no amount, so the agent's pair, above zero (agent-amount-processors.json), is the one the cardholder
+ * approves. Served on the same terms: only to a build that lists it, for a company Agentcard turned
+ * ProcessOut on for.
+ *
+ * `monei_card_token`: the card request MONEI's card frame sends from MONEI's payment page
+ * (secure.monei.com/payments/<id>) to api.monei.com/v1/tokens, with the payment's id and the card. This
+ * build pauses only the frame's own body for a payment at that exact URL (payment-core
+ * processors/monei.js); MONEI's account flow, Click to Pay and a wallet on the same URL fail in the
+ * browser before anything is created. The request names neither the merchant nor the amount, so the API
+ * reads MONEI's own record of the payment and holds the agent's pair, above zero
+ * (agent-amount-processors.json), to MONEI's amount exactly. The cardholder's device sends the card to
+ * MONEI itself and the frame gets back MONEI's payment token alone, rebuilt by payment-core's judge.
+ * Served on the same terms: only to a build that lists it, for a company Agentcard turned MONEI on for.
+ *
+ * `frisbii_card_token`: the card request Frisbii Checkout's hosted payment page (checkout.reepay.com or
+ * checkout.frisbii.com, as an overlay, an embedded frame or a full window) sends to
+ * card.reepay.com or card.frisbii.com /v1/token/?session=<id>, with the merchant's public key and the
+ * card. This build pauses only the page's own body at that exact URL (payment-core
+ * processors/frisbii.js); any other body on it, one that keeps the card on file included, fails in the
+ * browser before anything is created. The page's two other card paths, a stored card's token
+ * (/v1/token/cof/) and Click to Pay (/v1/token/create_click_to_pay), are held and refused whatever
+ * their body, so neither leaves the browser either. The request names the amount only when
+ * the session carries 3-D Secure data, so the agent's pair is required, above zero
+ * (agent-amount-processors.json), and the API refuses it when it differs from the page's own. The
+ * cardholder's device sends the card to Frisbii
+ * itself and the page gets back Frisbii's card token or 3-D Secure step alone, rebuilt by payment-core's
+ * judge. Served on the same terms: only to a build that lists it, for a company Agentcard turned Frisbii
+ * on for.
+ *
  * `aps_custom_merchant_page`: Amazon Payment Services' custom merchant page, whose own card form
  * posts top-level to /FortAPI/paymentPage on checkout.payfort.com (sbcheckout.payfort.com on APS's
  * sandbox) with service_command=TOKENIZATION. This build pauses that navigation; the cardholder's
@@ -515,6 +622,14 @@ export const SUPPORTED_REGISTRY_FEATURES = ['card_fields', 'checkout_sessions'];
  * the cardholder approves, and the API holds its amount to the body's. Served on the same terms: only to a build
  * that lists it, for a company Agentcard turned Nexi Checkout on for.
  *
+ * `oceanpayment_hosted_payment_page`: the card post of Oceanpayment's hosted payment page (secure.oceanpayment.com, where
+ * Oceanpayment's Shopify redirect app sends the buyer), a native form post to /gateway/sendPay;jsessionid=<session> with
+ * the card in clear (test-secure.oceanpayment.com for a test row). This build pauses only that post, exactly as the page's
+ * form action writes it, and aborts every other post to Oceanpayment's two hosts (oceanpayment.ts), so the agent's
+ * placeholder never reaches Oceanpayment; the cardholder's device writes the real card into the paused post and sends it
+ * through the checkout relay. The post names no amount, so the agent's pair, above zero, is the one the cardholder
+ * approves. Served on the same terms: only to a build that lists it, for a company Agentcard turned Oceanpayment on for.
+ *
  * `barion_hosted_payment_page`: Barion's Smart Gateway, whose card-free link
  * (secure.barion.com/Pay?Id=<payment id>, a plain GET the merchant's redirect or script sends
  * the buyer to) this build pauses for the cardholder's device by its exact link (hosted-entry.ts),
@@ -522,6 +637,27 @@ export const SUPPORTED_REGISTRY_FEATURES = ['card_fields', 'checkout_sessions'];
  * send (pre-claim.ts, barion.ts). Served on the same terms as Przelewy24's: only to a build that
  * lists it, for a company Agentcard turned Barion on for.
  *
+ * `payplug_hosted_payment_page`: PayPlug's payment page, whose card-free link
+ * (secure.payplug.com/pay/<payment id>, or /pay/test/<payment id>, a plain GET the merchant's
+ * redirect or script sends the buyer to) this build pauses for the cardholder's device by its exact
+ * link (hosted-entry.ts), and whose card post this build never lets the agent's browser send
+ * (pre-claim.ts, payplug.ts). The link names no amount, so authorize() asks for the agent's, above
+ * zero. Served only to a build that lists it, and the API turns PayPlug on for Agentcard's own
+ * company alone.
+ *
+ * `cardlink_vpos_hosted_payment_page`: Cardlink's VPOS, the payment page of Eurobank, Cardlink and Nexi
+ * Greece, whose card-free signed entry (a form post to /vpos/shophandlermpi on one of the three hosts) this build
+ * pauses for the cardholder's device, and whose card page's post and card check on the same URL this build never
+ * lets the agent's browser send (pre-claim.ts, cardlink-vpos.ts). Served only to a build that lists it, and the API
+ * turns the lane on for Agentcard's own company alone.
+ *
+ * `eghl_hosted_payment_page`: eGHL's payment page (ADAPTIS, formerly eGHL, on securepay.e-ghl.com), whose card-free
+ * entry (a GET of /IPG/payment.aspx with the payment in its query, which the merchant's checkout or eGHL's Shopify app
+ * sends the buyer to) this build pauses for the cardholder's device by its exact URL (hosted-entry.ts), and whose card
+ * page's post to the same address this build never lets the agent's browser send (pre-claim.ts, eghl.ts). The entry
+ * names its amount, and the API holds the agent's pair to it exactly. Served only to a build that lists it, and the API
+ * turns the lane on for Agentcard's own company alone.
+ *
  * `paymob_checkout_pay`: the card payment Paymob's own checkout sends, from Unified Checkout
  * (<country>.checkout.paymob.com) or from the Pixel card frame a merchant's page embeds, as JSON to
  * https://<accept|uae|ksa|oman>.paymob.com/api/acceptance/payments/pay. This build pauses only the
@@ -651,6 +787,8 @@ export const SUPPORTED_CAPABILITIES = DECLARED_CAPABILITIES;
 const REVOLUT_PSP = 'revolut';
 /** Nexi Checkout's card payment names the payment's amount in minor units but not its currency, as Revolut's does. */
 const NEXI_CHECKOUT_PSP = 'nexi_checkout';
+/** iyzico's Checkout Form payment names its price but not its currency, which the form's token holds. */
+const IYZICO_PSP = 'iyzico';
 const AGENT_AMOUNT_PROCESSORS = AGENT_AMOUNT.processors;
 /** The ones a zero amount is refused for, like a missing one (authorize()). */
 const ABOVE_ZERO_PROCESSORS = AGENT_AMOUNT.aboveZero;
@@ -937,11 +1075,12 @@ export class AmountRequiredError extends Error {
     constructor(psp) {
         const processor = PROCESSOR_NAMES[psp] ?? psp;
         // A Payrexx card request names the frame's total, but the merchant's page charges its own total after the token.
-        const lacks = psp === REVOLUT_PSP || psp === NEXI_CHECKOUT_PSP ? 'names its amount but not its currency'
+        const lacks = psp === REVOLUT_PSP || psp === NEXI_CHECKOUT_PSP || psp === IYZICO_PSP ? 'names its amount but not its currency'
             : psp === PAYREXX_PSP ? "only mints a token the merchant's page charges later"
                 : psp === TAP_PAYMENTS_PSP ? 'does not decide the amount charged' : 'names no amount';
-        // "An Omise payment request", "A Clover payment request": the article follows the name's first letter.
-        const article = /^[AEIOU]/.test(processor) ? 'An' : 'A';
+        // "An Omise payment request", "A Clover payment request", "An iyzico payment request": the article follows the
+        // name's first letter, in either case, and "A USAePay payment request" its first sound, a consonant's.
+        const article = /^(?:[AEIO]|U(?!SA))/i.test(processor) ? 'An' : 'A';
         super(`${article} ${processor} payment request ${lacks}, so pass amount and currency: that is the amount the cardholder approves. Nothing was created and nothing was charged.`);
         this.psp = psp;
         this.name = 'AmountRequiredError';
@@ -1365,11 +1504,11 @@ export class CheckoutAuthError extends Error {
     }
 }
 /**
- * A failure as the voice module reports it: an `AgentcardError` carrying the
- * API's code (`invalid_return_url`, `voice_not_enrolled`) or `oauth_failed`;
+ * A failure as the modules report it: an `AgentcardError` carrying the
+ * API's code or `oauth_failed`;
  * a failure to reach Agentcard at all passes through as it came.
  */
-function voiceError(err) {
+function moduleError(err) {
     if (err instanceof CheckoutAuthError)
         return new AgentcardError('oauth_failed', `Could not get a token for the client (${err.status}${err.code ? ', ' + err.code : ''}).`, err.status);
     if (err instanceof CheckoutApiError) {
@@ -1951,6 +2090,27 @@ const HIPAY_PREPARATION_REFUSALS = ['processor_unavailable', 'live_host_on_sandb
  */
 const OPENPAY_PREPARATION_REFUSALS = ['processor_unavailable', 'live_host_on_sandbox_row', 'sandbox_host_on_live_row',
     'merchant_profile_mismatch', 'amount_required'];
+/**
+ * The API's refusals of a VTEX Payments preparation, before any preparation exists, that prepareCheckout passes on by
+ * name: the company is not turned on for VTEX (`processor_unavailable`), the client is in test mode, which VTEX has no
+ * host for (`live_host_on_sandbox_row`), the merchant is not the name the reviewed pin for the checkout's page carries
+ * (`merchant_profile_mismatch`), the currency is not the store's (`unsupported_currency`), and the price is zero
+ * (`amount_required`). A page no reviewed pin lists answers `unsupported_checkout`, which PREPARATION_REFUSALS names for
+ * every checkout. The API holds the pins, so a store a later release reviews needs no new SDK. Only for a VTEX checkout.
+ */
+const VTEX_PAYMENTS_PREPARATION_REFUSALS = ['processor_unavailable', 'live_host_on_sandbox_row', 'merchant_profile_mismatch',
+    'unsupported_currency', 'amount_required'];
+/**
+ * The API's refusals of a ProcessOut preparation, before any preparation exists, that prepareCheckout passes on by
+ * name: the company is not turned on for ProcessOut (`processor_unavailable`), the environment is not the caller's key
+ * mode's (`processout_environment_mismatch`, since a live and a sandbox project share one host), a live checkout's
+ * merchant is not the name the reviewed pin for its origin carries (`merchant_profile_mismatch`), and the price is zero
+ * (`amount_required`), since the card request names no amount. An origin no reviewed pin lists answers
+ * `unsupported_checkout`, which PREPARATION_REFUSALS names for every checkout. The API holds the pins, not this build,
+ * so a store a later release reviews needs no new SDK. Only for a ProcessOut checkout.
+ */
+const PROCESSOUT_PREPARATION_REFUSALS = ['processor_unavailable', 'processout_environment_mismatch', 'merchant_profile_mismatch',
+    'amount_required'];
 /**
  * The reason the cardholder's device declines a bound prepared row with, per processor, when its own
  * send boundary passed before the card left it (the Vault's sendWindow, 12 seconds after it last saw
@@ -1959,7 +2119,9 @@ const OPENPAY_PREPARATION_REFUSALS = ['processor_unavailable', 'live_host_on_san
  * closes on (amadeus.ts), which can close later, so authorize() ends the attempt the way that window
  * does, as a CheckoutPreparationError with that reason, and never as the cardholder's "no". A prepared
  * HiPay token create too, and a prepared Openpay token create, whose device sends the card at most 25
- * seconds after it last saw the checkout unbound, inside the adapters' 30.
+ * seconds after it last saw the checkout unbound, inside the adapters' 30. And a prepared VTEX card post,
+ * whose device sends the card at most 6 seconds after it last saw the checkout unbound, inside the adapters' 8, and a
+ * prepared ProcessOut card request, whose device keeps HiPay's 10 seconds, inside the adapters' 12.
  */
 const PREPARED_SEND_WINDOW_DECLINES = Object.freeze({
     amadeus_checkout: 'amadeus_send_window_closed',
@@ -1967,7 +2129,17 @@ const PREPARED_SEND_WINDOW_DECLINES = Object.freeze({
     [WIX_PAYMENTS_PSP]: 'wix_payments_send_window_closed',
     [HIPAY_PSP]: 'hipay_send_window_closed',
     [OPENPAY_PSP]: 'openpay_send_window_closed',
+    [VTEX_PAYMENTS_PSP]: 'vtex_payments_send_window_closed',
+    [PROCESSOUT_PSP]: 'processout_send_window_closed',
 });
+/**
+ * The reason the API declines a bound VTEX card post with when its send-by passed before the card left the cardholder's
+ * device (backend services/commerce/checkout-vtex-payments.ts): Ollie's checkout gives the post 12 seconds, and the API
+ * counts 8 of them from the pause the create named. A known non-payment, as a closed send window is.
+ */
+const VTEX_PAYMENTS_POST_TIMED_OUT = 'vtex_payments_post_timed_out';
+/** A pause the create can count `paused_ms` from: a whole, non-negative epoch millisecond on this machine's clock. */
+const validPausedAt = (value) => Number.isSafeInteger(value) && value >= 0;
 /**
  * Refusals a CyberSource Flex preparation that tokenizes before Pay answers (4xx) before any
  * preparation exists, surfaced as the CheckoutPreparationError reason: the processor is off for
@@ -2050,22 +2222,22 @@ export class VaultClient {
      * false: a live client.
      */
     get sandbox() { return this.sandboxNamed || this.sandboxLearned === true; }
-    /** What every module shares: the token, the HTTP path, the poll settings and the language list. */
+    /** What every module shares: the token, the HTTP path and the poll settings. */
     transport;
-    /**
-     * Approve purchases by voice inside your own product: connect a person once,
-     * create the purchase, ask for the key word, read the result. Same
-     * credentials, same token as the checkout calls. Approves on Agentcard's
-     * page unless `voice: { approval: 'in_app' }` was named at construction.
-     */
-    voice;
     /**
      * The Purchase API from the same client: ask for a cart on behalf of a
      * person you connected, confirm it by its hash, and name an approval the
-     * person already gave by voice so the API places against it and asks for
-     * nothing a second time. Same credentials, same token as the voice calls.
+     * person already gave so the API places against it and asks for
+     * nothing a second time. Same credentials, same token as the checkout calls.
      */
     buy;
+    /**
+     * Purchases your server creates for a person, approved on Agentcard's page:
+     * create one (`request: 'sandbox'` under a sandbox client), send the person
+     * its `approval_url`, then read the decision or wait for it. Same
+     * credentials, same token as the checkout calls.
+     */
+    approvals;
     /**
      * The request builders: the processor requests a purchase pauses on, the
      * shipped ones and yours (`requests.register`, `requests.build`).
@@ -2090,7 +2262,7 @@ export class VaultClient {
                 });
             }
             catch (err) {
-                throw voiceError(err);
+                throw moduleError(err);
             }
         };
         this.transport = {
@@ -2099,18 +2271,14 @@ export class VaultClient {
                     return await this.accessToken();
                 }
                 catch (err) {
-                    throw voiceError(err);
+                    throw moduleError(err);
                 }
             },
             request,
             pollIntervalMs: this.pollIntervalMs,
-            pollTimeoutMs: opts.voice?.pollTimeoutMs,
-            backoffMs: opts.voice?.backoffMs,
-            wait: opts.voice?.wait,
-            languages: new Languages(request),
         };
-        this.voice = new VoiceModule(this.transport, opts.voice, () => this.sandbox);
         this.buy = new BuyModule(this.transport);
+        this.approvals = new ApprovalsModule(this.transport, () => this.sandbox);
         const declared = (opts.sandboxMerchants ?? []).map(declareSandboxMerchant);
         if (new Set(declared.map((profile) => profile.id)).size !== declared.length) {
             throw new TypeError('sandboxMerchants: declare each profile at most once.');
@@ -2660,6 +2828,8 @@ export class VaultClient {
                     || (input.psp === PAYGENT_PSP && PAYGENT_PREPARATION_REFUSALS.includes(error.code))
                     || (input.psp === HIPAY_PSP && HIPAY_PREPARATION_REFUSALS.includes(error.code))
                     || (input.psp === OPENPAY_PSP && OPENPAY_PREPARATION_REFUSALS.includes(error.code))
+                    || (input.psp === VTEX_PAYMENTS_PSP && VTEX_PAYMENTS_PREPARATION_REFUSALS.includes(error.code))
+                    || (input.psp === PROCESSOUT_PSP && PROCESSOUT_PREPARATION_REFUSALS.includes(error.code))
                     || (!!flexContext && CYBERSOURCE_FLEX_PREPARATION_REFUSALS.includes(error.code))))
                     || (input.psp === 'fiserv' && error.status === 502 && error.code === 'cse_key_unavailable')))
                 throw fail(error.code);
@@ -2778,6 +2948,11 @@ export class VaultClient {
         if (preparation) {
             if (!this.preparations.has(preparation) || this.usedPreparations.has(preparation))
                 throw new CheckoutPreparationError(preparation.id ?? null, 'already_used_or_foreign');
+            // VTEX Payments: the API counts the row's send-by from the pause the create names (`paused_ms`) and refuses a create
+            // that names none, so a caller without `pausedAt` is refused here, before the preparation is spent. The adapters fill it.
+            if (preparation.psp === VTEX_PAYMENTS_PSP && !validPausedAt(input.pausedAt)) {
+                throw new Error('A VTEX Payments card post needs pausedAt: when the card request paused, in epoch milliseconds. Nothing was created.');
+            }
             // Consume locally before any await, including OAuth, and never recycle it.
             this.usedPreparations.add(preparation);
             if (Date.parse(preparation.expiresAt) <= Date.now())
@@ -3065,8 +3240,14 @@ export class VaultClient {
                         ...(payrailsPayment ? { holder_reference: sidecar.holder_reference } : {}) } } : {}),
             },
         };
+        // VTEX Payments: how long ago the post paused, on this machine's clock as each create request leaves, after any wait
+        // for a token or a refresh after a 401, so the API counts the row's send-by from Ollie's own 12 seconds on its own
+        // clock, whatever the offset between the two machines.
+        const pausedAt = input.pausedAt;
+        const atSend = rec?.psp === VTEX_PAYMENTS_PSP && validPausedAt(pausedAt)
+            ? () => ({ paused_ms: Math.max(0, Date.now() - pausedAt) }) : undefined;
         try {
-            created = await this.createAuthorization(payload, input.currency, AbortSignal.any([operationSignal, AbortSignal.timeout(30_000)]), input.merchantSignal);
+            created = await this.createAuthorization(payload, input.currency, AbortSignal.any([operationSignal, AbortSignal.timeout(30_000)]), input.merchantSignal, atSend);
         }
         catch (error) {
             if (error instanceof PaymentOutcomeUnknownError) {
@@ -3095,6 +3276,14 @@ export class VaultClient {
                     await this.cancelPreparation(preparation.id).catch(() => { });
                 throw new CheckoutPreparationError(preparation?.id ?? null, error.code);
             }
+            // A VTEX create the API refused past its send-by (409 vtex_payments_post_timed_out), before any row, bind or
+            // notification: the card never left the cardholder's device, and Ollie stops waiting for the post before one could.
+            // The same known non-payment as the polled decline below. The preparation, which no later post of this attempt can
+            // use, is retired so the cardholder's page stops waiting for it.
+            if (preparation?.psp === VTEX_PAYMENTS_PSP && error instanceof CheckoutApiError && error.status === 409 && error.code === VTEX_PAYMENTS_POST_TIMED_OUT) {
+                await this.cancelPreparation(preparation.id).catch(() => { });
+                throw new CheckoutPreparationError(preparation.id, error.code);
+            }
             // A missing answer or generic 5xx can hide a committed row and a delivered approval link.
             // Only the documented pre-create read-back errors prove it is safe to retry.
             const safeReadFailure = error instanceof CheckoutApiError
@@ -3127,11 +3316,17 @@ export class VaultClient {
         // A prepared Openpay token create too, for 40 seconds: openpay.js gives it 40 seconds from Pay, so the token
         // reaches the page within half a second of the device's answer, and the API names 500 ms as such a row's poll
         // interval.
+        // A prepared VTEX card post too, for 12 seconds: Ollie's container aborts the post 12 seconds after it starts it,
+        // so VTEX's answer reaches the container within half a second of the device's report, and the API names 500 ms as
+        // such a row's poll interval.
+        // A prepared ProcessOut card request too, for 20 seconds: ProcessOut.js gives its card frame 20 seconds from the
+        // shop's press, and the API names 500 ms as such a row's poll interval.
         const preparedFastPollUntil = preparation?.psp === 'mercado_pago' ? Date.now() + 10_000
-            : preparation?.psp === PADDLE_VGS_PSP || preparation?.psp === HIPAY_PSP ? Date.now() + 20_000
+            : preparation?.psp === PADDLE_VGS_PSP || preparation?.psp === HIPAY_PSP || preparation?.psp === PROCESSOUT_PSP ? Date.now() + 20_000
                 : preparation?.psp === OPENPAY_PSP ? Date.now() + 40_000
-                    : preparation?.psp === EPROTECT_PSP ? Date.now() + 15_000
-                        : preparation?.psp === SECURE_ACCEPTANCE_PSP ? Date.now() + SECURE_ACCEPTANCE_FAST_POLL_MS : 0;
+                    : preparation?.psp === VTEX_PAYMENTS_PSP ? Date.now() + 12_000
+                        : preparation?.psp === EPROTECT_PSP ? Date.now() + 15_000
+                            : preparation?.psp === SECURE_ACCEPTANCE_PSP ? Date.now() + SECURE_ACCEPTANCE_FAST_POLL_MS : 0;
         // A preparation that tokenized before Pay: the cardholder's device already holds CyberSource's
         // token and approves as soon as this bind reaches it, while the page may give createToken only
         // seconds (Alaska Airlines' flight checkout gives it three). Poll every 100 ms for 10 seconds,
@@ -3529,6 +3724,19 @@ export class VaultClient {
                         response.headers = { 'content-type': 'application/json' };
                         response.body = judged.body;
                     }
+                    if (rec?.psp === PROCESSOUT_PSP) {
+                        // ProcessOut's answer enters the card frame only as payment-core rebuilds an approved token from the card facts
+                        // the page reads (processout.js processoutAnswerOutcome: HTTP 200 or 201, success and a card token in shape),
+                        // under its approved status and a JSON content type. The frame reads the body of any answer, so anything else, a
+                        // refusal ProcessOut answers inside a 2xx or a pending answer included, is never handed over as an approval;
+                        // the card may have left the device, so the outcome is unknown rather than declined.
+                        const judged = processoutAnswerOutcome(response.status, response.body, null, null);
+                        if (judged.outcome !== 'approved' || typeof judged.body !== 'string')
+                            throw new PaymentOutcomeUnknownError(authorizationId, 'processout_token_unconfirmed');
+                        response.status = response.status === 201 ? 201 : 200;
+                        response.headers = { 'content-type': 'application/json' };
+                        response.body = judged.body;
+                    }
                     if (rec?.psp === PRIMER_PSP) {
                         // Primer's answer enters the page only as one single-use card token rebuilt from
                         // payment-core's allow-list, under a JSON content type (primer.ts primerTokenAnswer).
@@ -3629,6 +3837,10 @@ export class VaultClient {
                     if (preparation && typeof s.reason === 'string' && PREPARED_SEND_WINDOW_DECLINES[preparation.psp] === s.reason) {
                         throw new CheckoutPreparationError(preparation.id, s.reason);
                     }
+                    // The API declined a bound VTEX post past its send-by, counted from the pause this create named: the card
+                    // never left the cardholder's device, so the checkout failed unsent the same way.
+                    if (preparation?.psp === VTEX_PAYMENTS_PSP && s.reason === VTEX_PAYMENTS_POST_TIMED_OUT)
+                        throw new CheckoutPreparationError(preparation.id, s.reason);
                     throw new ApprovalDeclinedError(s.reason ?? 'no reason given');
                 }
                 if (s.status === 'cancelled') {
@@ -3766,9 +3978,9 @@ export class VaultClient {
      * exactly the approved payment method (the page's own, or written by the
      * adapters in place of a card the confirm carries again).
      * The API allows a card save for any company, for an approval given on the
-     * Vault page, not by voice, with no amount, and a SetupIntent Stripe reports
-     * still confirmable on the same Stripe account; any other answer rejects with
-     * a CheckoutApiError whose code says why (for example `amount_mismatch`, or
+     * Vault page, with no amount, and a SetupIntent Stripe reports still
+     * confirmable on the same Stripe account; any other answer rejects with a
+     * CheckoutApiError whose code says why (for example `amount_mismatch`, or
      * `continuation_invalid` for a confirm that is not a card-free SetupIntent
      * confirm). Nothing
      * is charged: the adapters continue the page's request once this resolves.
@@ -3973,13 +4185,17 @@ export class VaultClient {
      * (Stripe did not answer the read-back) is retried on a short backoff
      * instead of being left to the page's own retry loop, and a 409
      * `amount_mismatch` becomes an AmountMismatchError at stage 'create' so the
-     * adapters treat it as an answered request, not a dead page.
+     * adapters treat it as an answered request, not a dead page. `atSend` adds
+     * fields counted as each request leaves, after any token wait, 401 refresh or
+     * backoff, so a field that measures time (VTEX's paused_ms) measures it then.
      */
-    async createAuthorization(payload, currency, signal, stopRetries) {
+    async createAuthorization(payload, currency, signal, stopRetries, atSend) {
         for (let attempt = 0;; attempt++) {
             if (stopRetries?.aborted)
                 throw new PaymentOutcomeUnknownError(null, 'merchant_request_aborted');
             try {
+                if (atSend)
+                    return await this.postAtSend('/v2/checkout/authorizations', () => ({ ...payload, ...atSend() }), signal, stopRetries);
                 return await this.post('/v2/checkout/authorizations', payload, signal, stopRetries);
             }
             catch (err) {
@@ -4065,8 +4281,10 @@ export class VaultClient {
      * Only fetch and a successful response's body read belong to that retry:
      * OAuth, HTTP errors, invalid JSON and every mutation remain outside it.
      * The existing one-time 401 refresh carries the remaining read budget.
+     * `bodyAt`, when given, builds the body as each request leaves, after the
+     * token and on the 401 refresh's resend, in place of `init.body`.
      */
-    async call(path, init = {}, retried = false, stopNewRequests, preparationReadAttempt) {
+    async call(path, init = {}, retried = false, stopNewRequests, preparationReadAttempt, bodyAt) {
         const signal = init.signal ?? AbortSignal.timeout(30_000);
         const token = await withSignal(this.accessToken(), signal);
         // Auth can outlive the merchant request. Stop a create that has not left
@@ -4081,6 +4299,7 @@ export class VaultClient {
             try {
                 r = await withSignal(this.fetch(`${this.baseUrl}${path}`, {
                     ...init,
+                    ...(bodyAt ? { body: bodyAt() } : {}),
                     signal,
                     headers: { ...(init.headers ?? {}), authorization: `Bearer ${token}`, 'content-type': 'application/json' },
                 }), signal);
@@ -4100,7 +4319,7 @@ export class VaultClient {
                 if (stopNewRequests?.aborted)
                     throw new PaymentOutcomeUnknownError(null, 'merchant_request_aborted');
                 await withSignal(this.accessToken(true), signal);
-                return this.call(path, { ...init, signal }, true, stopNewRequests, preparationReadAttempt);
+                return this.call(path, { ...init, signal }, true, stopNewRequests, preparationReadAttempt, bodyAt);
             }
             throw new CheckoutApiError(r.status, path, await withSignal(r.text(), signal));
         }
@@ -4108,6 +4327,10 @@ export class VaultClient {
     post(path, body, signal, stopNewRequests) {
         return this.call(path, { method: 'POST', body: JSON.stringify(body), signal }, false, stopNewRequests);
     }
+    /** A POST whose body is built as each request leaves (call's `bodyAt`), for a body that counts time. */
+    postAtSend(path, body, signal, stopNewRequests) {
+        return this.call(path, { method: 'POST', signal }, false, stopNewRequests, undefined, () => JSON.stringify(body()));
+    }
     get(path, signal) {
         return this.call(path, { signal });
     }
@@ -4209,7 +4432,9 @@ function cardEndpointReplay(s, authorizationId, profile, metadata) {
     const answer = named.answer;
     if (!isRecord(answer) || !Number.isInteger(answer.status) || answer.status < 100 || answer.status > 599)
         throw unknown('merchant_answer_malformed');
-    const base = { mode: CARD_ENDPOINT_MODE, authorizationId, profile, status: answer.status, ...metadata };
+    const approved = Number.isSafeInteger(s.amount) && s.amount > 0 && typeof s.currency === 'string' && /^[a-z]{3}$/i.test(s.currency)
+        ? { approved: { amount: s.amount, currency: s.currency.toLowerCase() } } : {};
+    const base = { mode: CARD_ENDPOINT_MODE, authorizationId, profile, status: answer.status, ...approved, ...metadata };
     if (answer.withheld !== undefined) {
         if (answer.withheld !== 'card_in_response' && answer.withheld !== 'unreadable_in_response' && answer.withheld !== 'refused_step_in_response') {
             throw unknown('merchant_answer_malformed');
@@ -4341,6 +4566,22 @@ function jsonPathOf(value) {
         || (typeof step === 'number' && Number.isSafeInteger(step) && step >= 0));
     return ok ? [...value] : null;
 }
+/** Whether a served step is the step into JSON text, exactly `{text: 'json'}`. */
+const isTextStep = (step) => isRecord(step) && Object.keys(step).length === 1 && step.text === 'json';
+/**
+ * A served holder path: a JSON path that may also step into a string holding JSON text, at most twice, never first
+ * or last and never twice in a row (payment-core json-path.js isProfilePath); null for anything else. The substitution
+ * itself checks it against this build's own profile.
+ */
+function holderPathOf(value) {
+    if (!Array.isArray(value) || value.length > 16)
+        return null;
+    const texts = value.map((step, i) => (isTextStep(step) ? i : -1)).filter((i) => i !== -1);
+    if (texts.length > 2 || texts.some((i) => i === 0 || i === value.length - 1 || texts.includes(i - 1)))
+        return null;
+    const plain = jsonPathOf(value.filter((step) => !isTextStep(step)));
+    return plain ? value.map((step) => (isTextStep(step) ? { text: 'json' } : step)) : null;
+}
 /** Served card facts: a list of {path, value}; null when anything in it is not one. */
 function factsOf(value) {
     if (!Array.isArray(value))
@@ -4386,7 +4627,7 @@ function merchantHostedApproval(s, authorizationId, profile) {
     if (!isRecord(served) || served.profile !== profile.id || typeof served.body_sha256 !== 'string'
         || !/^[0-9a-f]{64}$/.test(served.body_sha256))
         throw malformed();
-    const path = jsonPathOf(sub.path);
+    const path = holderPathOf(sub.path);
     const fields = isRecord(sub.fields) && Object.keys(sub.fields).length > 0
         && Object.values(sub.fields).every((value) => typeof value === 'string' && value.length > 0) ? { ...sub.fields } : null;
     const remove = sub.remove === undefined ? [] : Array.isArray(sub.remove) && sub.remove.every((key) => typeof key === 'string' && key.length > 0)

package/dist/creditguard.generated.d.ts

@@ -14,11 +14,11 @@ declare function isCreditguardPpsDocument(url: any): boolean;
 declare function creditguardNuveiRefusal(requestUrl: any, initiatorUrl: any): "creditguard_three_d_secure" | null;
 declare function isCreditguardJweCompact(value: any): boolean;
 declare function creditguardPpDomainHost(ppDomain: any): string | null;
-declare function creditguardBodyRefusal(body: any, txId: any, options: any): "pp_domain_unbound" | "malformed_body" | "saved_card" | "otp" | "wallet" | "unexpected_field" | "keep_on_file" | "gift_card" | "dcc" | "installments" | "personal_id" | "txid_mismatch" | "pp_domain" | "jwe_fallback" | "jwe_unsupported" | "card_fields" | null;
+declare function creditguardBodyRefusal(body: any, txId: any, options: any): "wallet" | "pp_domain_unbound" | "malformed_body" | "saved_card" | "otp" | "unexpected_field" | "keep_on_file" | "gift_card" | "dcc" | "installments" | "personal_id" | "txid_mismatch" | "pp_domain" | "jwe_fallback" | "jwe_unsupported" | "card_fields" | null;
 declare function classifyCreditguardRequest(url: any, method: any, body: any, options: any): "card" | "unsupported" | null;
-declare function creditguardProcessRefusal(request: any, options: any): "not_process_request" | "headers" | "pp_domain_unbound" | "malformed_body" | "saved_card" | "otp" | "wallet" | "unexpected_field" | "keep_on_file" | "gift_card" | "dcc" | "installments" | "personal_id" | "txid_mismatch" | "pp_domain" | "jwe_fallback" | "jwe_unsupported" | "card_fields" | null;
+declare function creditguardProcessRefusal(request: any, options: any): "wallet" | "not_process_request" | "headers" | "pp_domain_unbound" | "malformed_body" | "saved_card" | "otp" | "unexpected_field" | "keep_on_file" | "gift_card" | "dcc" | "installments" | "personal_id" | "txid_mismatch" | "pp_domain" | "jwe_fallback" | "jwe_unsupported" | "card_fields" | null;
 declare function isCreditguardProcessRequest(request: any, options: any): boolean;
-declare function creditguardReplayRefusal(request: any, options: any): "not_process_request" | "headers" | "pp_domain_unbound" | "malformed_body" | "saved_card" | "otp" | "wallet" | "unexpected_field" | "keep_on_file" | "gift_card" | "dcc" | "installments" | "personal_id" | "txid_mismatch" | "pp_domain" | "jwe_fallback" | "jwe_unsupported" | "card_fields" | null;
+declare function creditguardReplayRefusal(request: any, options: any): "wallet" | "not_process_request" | "headers" | "pp_domain_unbound" | "malformed_body" | "saved_card" | "otp" | "unexpected_field" | "keep_on_file" | "gift_card" | "dcc" | "installments" | "personal_id" | "txid_mismatch" | "pp_domain" | "jwe_fallback" | "jwe_unsupported" | "card_fields" | null;
 declare function creditguardRefusalMessage(reason: any): string;
 declare function injectCreditguardCard(body: any, card: any, options: any): {
     body: string;
@@ -141,7 +141,7 @@ declare function creditguardDeviceThreeDSOutcomeRequest(processUrl: any): {
     };
     body: string;
 };
-declare function creditguardDeviceStepRefusal(request: any, processUrl: any): "headers" | "malformed_body" | "wallet" | "unexpected_field" | "gift_card" | "dcc" | "txid_mismatch" | "card_fields" | "not_companion_request" | null;
+declare function creditguardDeviceStepRefusal(request: any, processUrl: any): "wallet" | "headers" | "malformed_body" | "unexpected_field" | "gift_card" | "dcc" | "txid_mismatch" | "card_fields" | "not_companion_request" | null;
 declare function creditguardCardinalUrl(url: any, purpose: any, environment: any): string | null;
 declare function isCreditguardCardinalOrigin(origin: any): boolean;
 declare function creditguardCardinalMessage(data: any): {