@agent-cards/sdk 0.23.6 → 0.23.8

package/dist/client.js

@@ -31,6 +31,7 @@ import { PELECARD_CAPABILITY, PELECARD_PSP } from './pelecard.js';
 import { PRIMER_CAPABILITY, PRIMER_PSP, primerTokenAnswer } from './primer.js';
 import { PAYRAILS_CAPABILITY, payrailsSaveAnswer } from './payrails.js';
 import { WSPAY_CAPABILITY, WSPAY_PSP } from './wspay.js';
+import { SECURE_ACCEPTANCE_CAPABILITY, SECURE_ACCEPTANCE_FAST_POLL_MS, SECURE_ACCEPTANCE_PSP, SECURE_ACCEPTANCE_REPLY_WINDOW_MS, secureAcceptanceCheckoutProfile, secureAcceptanceCheckoutRefusal, secureAcceptanceFrameAnswer, } from './cybersource-secure-acceptance.js';
 /**
  * The modes this SDK can finish. Asked for on syncRegistry (the API serves
  * only recognizers in these modes, so a request this build cannot complete
@@ -158,8 +159,15 @@ export const SUPPORTED_REGISTRY_FEATURES = ['card_fields', 'checkout_sessions'];
  * `ekashu_hosted_payment_page`: NMI's hosted payment page, whose card-free entry this
  * build pauses for the cardholder's device and whose card page this build never lets
  * the agent's browser post to (pre-claim.ts, ekashu.ts); served on the same terms.
+ * `cybersource_sa_token_create`: CyberSource Secure Acceptance's token create
+ * (POST /silent/embedded/token/create), which this build pauses only as the
+ * merchant's hidden frame sends it, binds to a prepared checkout, and answers with
+ * CyberSource's own reply page once neither the API nor the cardholder's device
+ * finds a card in it (cybersource-secure-acceptance.ts). Served on the same terms,
+ * so every other company keeps the stop every build applies to a card posted to
+ * Secure Acceptance.
  */
-export const SUPPORTED_CAPABILITIES = ['fiserv_card_capture', GMO_CAPABILITY, CYBERSOURCE_FLEX_CAPABILITY, JUSPAY_CAPABILITY, DATATRANS_CAPABILITY, 'authorize_net_dpm_form', PELECARD_CAPABILITY, ACI_CAPABILITY, 'creditguard_pps_process', PRIMER_CAPABILITY, PAYRAILS_CAPABILITY, CONVERGE_CAPABILITY, EPROTECT_CAPABILITY, WSPAY_CAPABILITY, SHIJI_STS_CAPABILITY, AMADEUS_CHECKOUT_CAPABILITY, 'worldline_mycheckout_form', 'verifone_card_capture', 'ekashu_hosted_payment_page'];
+export const SUPPORTED_CAPABILITIES = ['fiserv_card_capture', GMO_CAPABILITY, CYBERSOURCE_FLEX_CAPABILITY, JUSPAY_CAPABILITY, DATATRANS_CAPABILITY, 'authorize_net_dpm_form', PELECARD_CAPABILITY, ACI_CAPABILITY, 'creditguard_pps_process', PRIMER_CAPABILITY, PAYRAILS_CAPABILITY, CONVERGE_CAPABILITY, EPROTECT_CAPABILITY, WSPAY_CAPABILITY, SHIJI_STS_CAPABILITY, AMADEUS_CHECKOUT_CAPABILITY, 'worldline_mycheckout_form', 'verifone_card_capture', 'ekashu_hosted_payment_page', SECURE_ACCEPTANCE_CAPABILITY];
 /**
  * Processors whose paused request names no amount at all, so the pair the
  * agent passes is the amount the cardholder approves: authorize() refuses one
@@ -173,11 +181,16 @@ export const SUPPORTED_CAPABILITIES = ['fiserv_card_capture', GMO_CAPABILITY, CY
  * pair is also the figure the API compares with WSPay's answer when that
  * answer names one. A WSPay 3-D Secure step answers with no amount, so on that
  * path nothing Agentcard sees confirms what WSPay charges once the challenge
- * completes.
+ * completes. A CyberSource Secure Acceptance token create signs an amount of 0:
+ * it creates a token and charges nothing, and the merchant's server charges its
+ * own cart total later, so the agent's pair, which the prepared checkout already
+ * carries, is the total the cardholder approves, and the card that pays can spend
+ * no more than that (the API's card rule).
  */
-const AGENT_AMOUNT_PROCESSORS = [GMO_PSP, PELECARD_PSP, WSPAY_PSP];
+const AGENT_AMOUNT_PROCESSORS = [GMO_PSP, PELECARD_PSP, WSPAY_PSP, SECURE_ACCEPTANCE_PSP];
 /** How AmountRequiredError names a processor. */
-const PROCESSOR_NAMES = { [GMO_PSP]: 'GMO', [PELECARD_PSP]: 'Pelecard', [WSPAY_PSP]: 'WSPay' };
+const PROCESSOR_NAMES = { [GMO_PSP]: 'GMO', [PELECARD_PSP]: 'Pelecard', [WSPAY_PSP]: 'WSPay',
+    [SECURE_ACCEPTANCE_PSP]: 'CyberSource Secure Acceptance' };
 /**
  * Processors whose request and answer name no amount at all, so the total the
  * payment page shows (`pageAmount`) is the one figure that ties the agent's pair
@@ -305,6 +318,22 @@ function creditguardPreparationRefusal(error) {
     const reason = error.details.reason;
     return new CheckoutPreparationError(null, error.code, typeof reason === 'string' && /^[a-z0-9_]{1,64}$/.test(reason) ? reason : undefined);
 }
+/**
+ * The API's refusal of a Secure Acceptance preparation (SECURE_ACCEPTANCE_PREPARATION_REFUSALS, and the
+ * relay's 503), answered before any row or prompt, as its own reason with the API's `details.reason` as
+ * the detail: `unsupported_checkout` (`secure_acceptance_merchant_pending`) tells an agent the merchant is
+ * not on yet, which `preparation_unconfirmed` would hide. Null for any other failure.
+ */
+function secureAcceptancePreparationRefusal(error) {
+    if (!(error instanceof CheckoutApiError) || error.code === null)
+        return null;
+    const named = (error.status >= 400 && error.status < 500 && SECURE_ACCEPTANCE_PREPARATION_REFUSALS.includes(error.code))
+        || (error.status === 503 && error.code === 'cybersource_sa_relay_unavailable');
+    if (!named)
+        return null;
+    const reason = error.details.reason;
+    return new CheckoutPreparationError(null, error.code, typeof reason === 'string' && /^[a-z0-9_]{1,64}$/.test(reason) ? reason : undefined);
+}
 export class CardEncryptedError extends Error {
     psp;
     constructor(psp) {
@@ -932,6 +961,34 @@ const FISERV_PREPARATION_REFUSALS = [
  * holds that pin). Only for an eProtect checkout.
  */
 const EPROTECT_PREPARATION_REFUSALS = ['merchant_profile_mismatch'];
+/**
+ * The API's refusals of a CyberSource Secure Acceptance preparation, before any preparation exists,
+ * that prepareCheckout surfaces by name, with the API's own `details.reason` as the error's `detail`
+ * where it gives one: the company is not one Agentcard turned the lane on for
+ * (`processor_unavailable`), the environment is not the client's test or live mode, the merchant is
+ * not one Agentcard turned on, or is still in review (`unsupported_checkout`, with
+ * `secure_acceptance_merchant_pending`, `secure_acceptance_merchant_observe` and the like), a live
+ * checkout's merchant is not the name the reviewed entry carries (`merchant_profile_mismatch`), and,
+ * as a 503, the relay that carries the cardholder's device to CyberSource is not on yet
+ * (`cybersource_sa_relay_unavailable`). Only for a Secure Acceptance checkout. The card follows the rule
+ * of every prepared checkout, a card the cardholder stored, so its refusal stays
+ * `preparation_unconfirmed`, as for Worldpay eProtect.
+ */
+const SECURE_ACCEPTANCE_PREPARATION_REFUSALS = [
+    'processor_unavailable', 'sandbox_host_on_live_row', 'live_host_on_sandbox_row', 'unsupported_checkout', 'merchant_profile_mismatch',
+];
+/**
+ * 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
+ * the checkout unbound): a prepared Amadeus SDK add and a prepared Secure Acceptance token create. It
+ * names the same known non-payment the adapters' own send window 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".
+ */
+const PREPARED_SEND_WINDOW_DECLINES = Object.freeze({
+    amadeus_checkout: 'amadeus_send_window_closed',
+    [SECURE_ACCEPTANCE_PSP]: 'secure_acceptance_send_window_closed',
+});
 /**
  * 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
@@ -1131,15 +1188,17 @@ export class VaultClient {
         // 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) and
+        // worldline_mycheckout_form, verifone_card_capture, ekashu_hosted_payment_page,
+        // cybersource_sa_token_create) and
         // the caller's company is one Agentcard turned that processor on for, so this
         // build arms Fiserv's card capture, GMO's getToken, CyberSource Flex's card
         // fields, Juspay's card flow, Datatrans's Secure Fields card post, the
         // Authorize.Net DPM or SIM form, Pelecard's card submission, ACI's split card,
         // CreditGuard's hosted page submit, Primer's card tokenization, Payrails' card
         // save, Converge's payment page, Worldpay eProtect's registration, WSPay's
-        // card confirm, Shiji STS's card leg, Amadeus Checkout's card add and
-        // Worldline MyCheckout's card form only for
+        // card confirm, Shiji STS's card leg, Amadeus Checkout's card add,
+        // Worldline MyCheckout's card form and CyberSource Secure Acceptance's token
+        // create only for
         // such a company, and an older build never receives a recognizer it cannot
         // judge. Every other org's registry never recognizes a Flex, Juspay, Datatrans,
         // Pelecard, ACI, CreditGuard, Primer, Payrails, Converge, eProtect, WSPay, Shiji STS, Amadeus or
@@ -1148,8 +1207,10 @@ export class VaultClient {
         // SIM, Pelecard, ACI, CreditGuard, Primer, Payrails, Converge, eProtect, WSPay,
         // Shiji STS, Amadeus and MyCheckout requests go through untouched; the create checks the org again (403
         // processor_unavailable), and the SDK refuses ACI's card-number request,
-        // CreditGuard's submit, an eProtect registration and an Amadeus card add locally
-        // without a prepared checkout.
+        // CreditGuard's submit, an eProtect registration, an Amadeus card add and a
+        // Secure Acceptance token create locally without a prepared checkout. A Secure
+        // Acceptance card post that no served recognizer covers is stopped for every
+        // company (pre-claim.ts).
         const capabilities = SUPPORTED_CAPABILITIES.length ? `&capabilities=${SUPPORTED_CAPABILITIES.join(',')}` : '';
         // merchant_profiles=1 asks for the reviewed Adyen merchant profiles too, each
         // as a `{ merchant_profile }` entry after the recognizers; an API that
@@ -1403,6 +1464,16 @@ export class VaultClient {
             throw fail('paypage_id_invalid');
         if (eprotect && !input.cardId)
             throw fail('card_required');
+        // CyberSource Secure Acceptance: the preparation names the CyberSource merchant profile its token create
+        // may name (secureAcceptanceProfileId, which on the production host this build can fill from the entry
+        // it reviewed for the page's origin) and the paying card, whose billing name and address the agent types
+        // into the merchant's form, where the merchant's server signs them. The API refuses either missing, and a
+        // profile id on any other processor; refusing here asks nobody to approve a preparation that could never bind.
+        const secureAcceptance = input.psp === SECURE_ACCEPTANCE_PSP;
+        if (!secureAcceptance && input.secureAcceptanceProfileId !== undefined)
+            throw fail('secure_acceptance_profile_id_invalid');
+        if (secureAcceptance && !input.cardId)
+            throw fail('card_required');
         // CyberSource Flex, tokenized before Pay: the loaded card field's capture context and fields,
         // verified here against the keys payment-core pins before anything is created (the API and the
         // cardholder's device verify them again).
@@ -1448,6 +1519,17 @@ export class VaultClient {
             merchantOrigin: input.merchantOrigin, merchant: input.merchant }) : null;
         if (eprotectRefusal)
             throw fail(eprotectRefusal);
+        // A Secure Acceptance checkout names a profile id: the one passed, of CyberSource's shape, or on the
+        // production host the one the entry this build reviewed for the page's origin pins. Under a reviewed
+        // entry it names that entry's merchant, the one the API shows on the approval, so the approval, the
+        // handle this returns and every authorization it pays name one merchant. A profile id this build has not
+        // reviewed is the API's to judge (unsupported_checkout); the test host needs no entry.
+        const secureAcceptanceRefusal = secureAcceptance ? secureAcceptanceCheckoutRefusal({ environment: input.environment,
+            profileId: input.secureAcceptanceProfileId, merchantOrigin: input.merchantOrigin, merchant: input.merchant }) : null;
+        if (secureAcceptanceRefusal)
+            throw fail(secureAcceptanceRefusal);
+        const secureAcceptanceProfileId = secureAcceptance ? secureAcceptanceCheckoutProfile({ environment: input.environment,
+            profileId: input.secureAcceptanceProfileId, merchantOrigin: input.merchantOrigin }) : null;
         const timeoutMs = input.timeoutMs ?? 15 * 60_000;
         if (!Number.isInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2_147_483_647)
             throw fail('timeout_invalid');
@@ -1469,6 +1551,7 @@ export class VaultClient {
                 ...(declaration ? { sandbox_declaration: { endpoint: declaration.endpoint, client_key: declaration.clientKey, environment: 'test' } } : {}),
                 ...(input.psp === 'creditguard' ? { payment_page_url: input.paymentPageUrl } : {}),
                 ...(eprotect ? { paypage_id: input.paypageId } : {}),
+                ...(secureAcceptance ? { secure_acceptance_profile_id: secureAcceptanceProfileId } : {}),
                 ...(flexContext ? { capture_context: flexContext.captureContext,
                     microform: { version: flexContext.microform.version, fields: [...flexContext.microform.fields] } } : {}),
             }, AbortSignal.timeout(30_000), signal);
@@ -1511,6 +1594,8 @@ export class VaultClient {
                         || state.checkout_key !== input.checkoutKey
                         // eProtect: the merchant and the card the cardholder approved are the ones asked for.
                         || (eprotect && (state.paypage_id !== input.paypageId || state.card_id !== input.cardId))
+                        // Secure Acceptance: the merchant profile and the card the cardholder approved are the ones asked for.
+                        || (secureAcceptance && (state.secure_acceptance_profile_id !== secureAcceptanceProfileId || state.card_id !== input.cardId))
                         // The API says a preparation tokenizes before Pay exactly when this one carried a capture context.
                         || (state.tokenize_before_pay === true) !== !!flexContext)
                         throw fail('ready_unconfirmed', id);
@@ -1526,6 +1611,7 @@ export class VaultClient {
                         ...(declaration ? { sandboxDeclaration: declaration } : {}),
                         ...(input.psp === 'creditguard' ? { paymentPageUrl: input.paymentPageUrl } : {}),
                         ...(eprotect ? { paypageId: input.paypageId } : {}),
+                        ...(secureAcceptance ? { secureAcceptanceProfileId: secureAcceptanceProfileId } : {}),
                         ...(flexContext ? { cybersourceFlex: Object.freeze({ captureContext: flexContext.captureContext,
                                 microform: Object.freeze({ version: flexContext.microform.version, fields: Object.freeze([...flexContext.microform.fields]) }) }) } : {}),
                     });
@@ -1542,7 +1628,8 @@ export class VaultClient {
         catch (error) {
             if (error instanceof CheckoutPreparationError)
                 throw error;
-            const refusal = input.psp === 'creditguard' && id === null ? creditguardPreparationRefusal(error) : null;
+            const refusal = input.psp === 'creditguard' && id === null ? creditguardPreparationRefusal(error)
+                : secureAcceptance && id === null && !signal.aborted ? secureAcceptancePreparationRefusal(error) : null;
             if (refusal)
                 throw refusal;
             // A refusal the API answered before any preparation existed names its rule: one
@@ -1621,6 +1708,8 @@ export class VaultClient {
      * response to replay into the browser. Your process never sees a card.
      */
     async authorize(input) {
+        // When the paused request reached this call: a Secure Acceptance reply window runs from here.
+        const calledAt = Date.now();
         // A reviewed merchant's own card endpoint is checked whole before anything else
         // (admitCardEndpoint): the profile, the approval, the amount and the session.
         const cardEndpoint = input.request.merchant_card_endpoint === undefined ? null : admitCardEndpoint(input);
@@ -1803,6 +1892,12 @@ export class VaultClient {
         if (cardMethod === 'GET' && !(eprotect && isEprotectRegistration(input.request))) {
             throw new Error(`this ${rec?.psp} GET is not a card registration this version of @agent-cards/checkout can complete: ${redactUrl(input.request.url)}.`);
         }
+        // A CyberSource Secure Acceptance token create (always prepared: its recognizer requires it). The
+        // merchant's page asks its hidden frame for the reply for 30 seconds from Save, so a reply not read
+        // SECURE_ACCEPTANCE_REPLY_WINDOW_MS after the pause will never be read: the outcome is then unknown,
+        // and the authorization is retired when the API confirms the card never moved.
+        const secureAcceptance = rec?.psp === SECURE_ACCEPTANCE_PSP;
+        const secureAcceptanceReplyBy = secureAcceptance ? calledAt + SECURE_ACCEPTANCE_REPLY_WINDOW_MS : Infinity;
         // The amount is a hint: a pair or nothing. Refuse half a pair here, before
         // a network call: the API would too, and a retry loop cannot fix a
         // missing field. The processor's own amount is read by Agentcard.
@@ -1924,6 +2019,17 @@ export class VaultClient {
                 }
                 throw new PaymentOutcomeUnknownError(id, 'preparation_already_bound');
             }
+            // A Secure Acceptance create refused because the relay that carries the cardholder's device to
+            // CyberSource is off (503 cybersource_sa_relay_unavailable): the API answers it before any rule, row
+            // or bind (assertSecureAcceptanceRelayReady at the create, and again inside the bind's transaction),
+            // so nothing was created and the card cannot leave. Named, as prepare() names it, never a create
+            // that may have committed. The preparation, which no request can bind while the relay is off, is
+            // retired so the cardholder's page stops waiting for it.
+            if (secureAcceptance && error instanceof CheckoutApiError && error.status === 503 && error.code === 'cybersource_sa_relay_unavailable') {
+                if (preparation)
+                    await this.cancelPreparation(preparation.id).catch(() => { });
+                throw new CheckoutPreparationError(preparation?.id ?? null, 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
@@ -1945,8 +2051,12 @@ export class VaultClient {
         // A prepared Worldpay eProtect registration too, for 15 seconds: its
         // merchants give up on the paused script 10 to 15 seconds after Pay, so a
         // registration is read every 500 ms instead of waiting out 2 seconds.
+        // A prepared CyberSource Secure Acceptance token create too, for 30 seconds:
+        // the merchant's page asks its frame for the reply for 30 seconds from Save,
+        // 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 === EPROTECT_PSP ? Date.now() + 15_000 : 0;
+            : 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,
@@ -2003,16 +2113,24 @@ export class VaultClient {
                     throw new PaymentOutcomeUnknownError(authorizationId, input.merchantSignal?.aborted ? 'merchant_request_aborted' : 'local_cancel');
                 const pollInterval = Date.now() < preparedFastPollUntil ? Math.min(this.pollIntervalMs, 500)
                     : Date.now() < preparedFlexPollUntil ? Math.min(this.pollIntervalMs, 100) : this.pollIntervalMs;
-                await interruptibleSleep(Math.min(pollInterval, Math.max(0, deadline - Date.now())), stopSignal);
+                // A Secure Acceptance read also wakes when its reply window closes (Infinity for every other processor).
+                await interruptibleSleep(Math.min(pollInterval, Math.max(0, deadline - Date.now()), Math.max(0, secureAcceptanceReplyBy - Date.now())), stopSignal);
                 if (stopSignal?.aborted)
                     throw new PaymentOutcomeUnknownError(authorizationId, input.merchantSignal?.aborted ? 'merchant_request_aborted' : 'local_cancel');
                 let s;
                 const deadlineSignal = AbortSignal.timeout(Math.max(1, deadline - Date.now()));
-                const pollSignal = stopSignal ? AbortSignal.any([stopSignal, deadlineSignal]) : deadlineSignal;
+                // A Secure Acceptance read is also bounded by its reply window, whatever time the caller has left: once
+                // the window closes the merchant's page has stopped asking for the reply, so a read still unanswered then
+                // is late, never a failed poll that could still hand the frame a page.
+                const replySignal = secureAcceptance ? AbortSignal.timeout(Math.max(1, secureAcceptanceReplyBy - Date.now())) : undefined;
+                const pollSignal = stopSignal || replySignal
+                    ? AbortSignal.any([...(stopSignal ? [stopSignal] : []), deadlineSignal, ...(replySignal ? [replySignal] : [])]) : deadlineSignal;
                 try {
                     s = await this.get(`/v2/checkout/authorizations/${authorizationId}`, pollSignal);
                 }
                 catch {
+                    if (replySignal?.aborted && !stopSignal?.aborted)
+                        throw new PaymentOutcomeUnknownError(authorizationId, 'secure_acceptance_reply_late');
                     throw new PaymentOutcomeUnknownError(authorizationId, input.merchantSignal?.aborted ? 'merchant_request_aborted' : 'authorization_poll_failed');
                 }
                 if (input.merchantSignal?.aborted)
@@ -2020,6 +2138,12 @@ export class VaultClient {
                 if (!s || typeof s !== 'object' || Array.isArray(s) || typeof s.status !== 'string') {
                     throw new PaymentOutcomeUnknownError(authorizationId, 'authorization_status_malformed');
                 }
+                // An approval read once the reply window has closed reaches nobody: the merchant's page has stopped asking,
+                // so CyberSource's page is never handed to the frame. The card has reached CyberSource, so the outcome is
+                // unknown, as for a reply that never came.
+                if (secureAcceptance && s.status === 'approved' && (Date.now() >= secureAcceptanceReplyBy || replySignal?.aborted)) {
+                    throw new PaymentOutcomeUnknownError(authorizationId, 'secure_acceptance_reply_late');
+                }
                 execution = executionMetadata(s, authorizationId, execution);
                 checkAutopilotAction(s);
                 if (nativeCheckout && (s.status === 'submitted_on_device' ||
@@ -2202,6 +2326,23 @@ export class VaultClient {
                         response.headers = answer.headers;
                         response.body = answer.body;
                     }
+                    if (secureAcceptance) {
+                        // CyberSource Secure Acceptance: the paused frame navigation is answered with CyberSource's own
+                        // reply page, byte for byte, with status 200 and its one content type, and only a page
+                        // payment-core's reply rule accepts for the paused request (secureAcceptanceFrameAnswer): one
+                        // hidden-input form posting to the receipt page the request signed, the request's own echoes, a
+                        // masked number and a token. The device and the API already checked it for the card. Anything
+                        // else is not an answer to hand the frame, and the card has already reached CyberSource. No
+                        // autopilot run sends one (payment-core, the authority and the API refuse it).
+                        if (execution.executionMode === 'autopilot')
+                            throw new PaymentOutcomeUnknownError(authorizationId, 'autopilot_submission_mode_invalid');
+                        const answer = secureAcceptanceFrameAnswer(input.request, response);
+                        if (!answer)
+                            throw new PaymentOutcomeUnknownError(authorizationId, 'secure_acceptance_reply_unconfirmed');
+                        response.status = answer.status;
+                        response.headers = answer.headers;
+                        response.body = answer.body;
+                    }
                     if (shopOrder) {
                         let receipt;
                         try {
@@ -2312,6 +2453,12 @@ export class VaultClient {
                     if (s.reason === 'processor_refused') {
                         throw new ProcessorRefusedError(String(created.id), typeof s.psp_error_code === 'string' ? s.psp_error_code : null, s.psp === 'razorpay' ? parseProcessorError(s.processor_error) : null);
                     }
+                    // The cardholder's device passed its own send boundary before the card left it and declined the
+                    // row with that window's reason: the checkout failed unsent, as when the adapters' own window
+                    // closes first (PREPARED_SEND_WINDOW_DECLINES), not a decline the cardholder made.
+                    if (preparation && typeof s.reason === 'string' && PREPARED_SEND_WINDOW_DECLINES[preparation.psp] === s.reason) {
+                        throw new CheckoutPreparationError(preparation.id, s.reason);
+                    }
                     throw new ApprovalDeclinedError(s.reason ?? 'no reason given');
                 }
                 if (s.status === 'cancelled') {
@@ -2326,6 +2473,11 @@ export class VaultClient {
                 }
                 if (s.status !== 'awaiting_approval')
                     throw new PaymentOutcomeUnknownError(authorizationId, 'authorization_status_unrecognized');
+                // A Secure Acceptance row neither approved nor declined when its reply window closes: the merchant's
+                // page stopped asking for the reply, and the device may have sent the card. Unknown, never a decline;
+                // the cleanup below retires the row only when the API confirms the card never moved.
+                if (Date.now() >= secureAcceptanceReplyBy)
+                    throw new PaymentOutcomeUnknownError(authorizationId, 'secure_acceptance_reply_late');
             }
             // A local deadline is not server-side expiry; the person may still use the approval link.
             throw new PaymentOutcomeUnknownError(authorizationId, 'local_approval_timeout');

package/dist/creditguard.generated.d.ts

@@ -54,7 +54,7 @@ declare function parseCreditguardTransaction(body: any, txId: any): {
     personalIdAlwaysEnabled: boolean;
     inputs: any;
 } | null;
-declare function creditguardTransactionRefusal(txn: any, expectation: any): "otp" | "keep_on_file" | "dcc" | "installments" | "personal_id" | "jwe_unsupported" | "amount_mismatch" | "environment_mismatch" | "currency_mismatch" | "transaction_unreadable" | "three_d_secure" | "transaction_type" | "form_inputs" | "card_field_hidden" | "no_retries_left" | "jwe_public_key_malformed" | null;
+declare function creditguardTransactionRefusal(txn: any, expectation: any): "otp" | "keep_on_file" | "dcc" | "installments" | "personal_id" | "jwe_unsupported" | "transaction_type" | "amount_mismatch" | "environment_mismatch" | "currency_mismatch" | "transaction_unreadable" | "three_d_secure" | "form_inputs" | "card_field_hidden" | "no_retries_left" | "jwe_public_key_malformed" | null;
 declare function creditguardSendWindowRefusal(timing: any): "timing_unknown" | "page_expired" | "recaptcha_expired" | null;
 declare var CREDITGUARD_REFUSAL_CODES: readonly string[];
 declare function creditguardResponseOutcome(status: any, body: any, options: any): {

package/dist/cybersource-secure-acceptance.d.ts

@@ -1,37 +1,3 @@
-/**
- * CyberSource Secure Acceptance's Silent Order POST, which this SDK refuses for every company.
- *
- * CyberSource's Secure Acceptance Checkout API, formerly Silent Order POST, takes the card from a form
- * on the merchant's own page. The merchant's server signs the order fields, and the shopper's browser
- * posts them, with the card fields left unsigned, to a /silent/ path on one of CyberSource's Secure
- * Acceptance hosts: /silent/pay, /silent/token/create, /silent/token/update, and the iframe form of
- * each under /silent/embedded/ (CyberSource's endpoint table, read 2026-10-08). Arrow Electronics'
- * checkout (its public bundles, read 2026-10-08; no card was sent) builds that form once its server
- * has signed the fields and submits it into a hidden iframe:
- *
- *   <iframe name="secureAcceptanceiFrame" style="display:none">
- *   <form action="https://secureacceptance.cybersource.com/silent/embedded/token/create" method="post"
- *     target="secureAcceptanceiFrame">: access_key, profile_id, transaction_type=create_payment_token,
- *     amount=0 and the other signed fields with their signature, then card_type, card_number,
- *     card_expiry_date (MM-YYYY) and card_cvn
- *
- * No Vault mode takes this post over, so no company can pay it, and an SDK without this guard let the
- * card the agent typed reach CyberSource. Both adapters arm /silent/ on the three hosts whatever the
- * synced registry serves, over https and http, each host also spelled with the trailing dot of a fully
- * qualified name, and the pre-claim gate (cybersourceSecureAcceptancePreClaim, pre-claim.ts) judges
- * each request there, whether a fetch, an XHR or a form navigation of the page or of a frame sent it,
- * by its body and by its URL's query (cybersourceSecureAcceptanceRequest):
- *   - a card_number that holds a value: stop it, so CyberSource never receives the card. A form
- *     navigation is answered with the stopped page (card-endpoint-page.ts), which names CyberSource,
- *     since an aborted page load renders nothing and invites another click on Pay; any other request
- *     fails. The checkout reads `unsupported` with reason `unsupported_cybersource_secure_acceptance`
- *     and holds, as every unsupported refusal does;
- *   - no card_number, or an empty one, as in a payment with a stored payment_token: continue untouched;
- *   - a body the adapter could not read: stop that request alone, since nothing proves it carries no card.
- * A request the synced registry recognizes as a card request belongs to that recognizer instead; no
- * build serves one today. Hosted Checkout, the same hosts without /silent/, takes the card on
- * CyberSource's own page, and neither adapter arms it.
- */
 export declare const CYBERSOURCE_SECURE_ACCEPTANCE_REASON: "unsupported_cybersource_secure_acceptance";
 /** Where the stopped page says the card was going. */
 export declare const CYBERSOURCE_SECURE_ACCEPTANCE_RECIPIENT = "CyberSource";
@@ -76,3 +42,145 @@ export declare function cybersourceSecureAcceptanceRequest(url: string, method:
  * body that also parses as JSON, say, cannot carry the card past the gate.
  */
 export declare function cybersourceSecureAcceptanceBody(body: string | null, contentType?: string): 'card' | 'no_card' | 'unreadable';
+/** The processor id, as the registry and the API name it. */
+export declare const SECURE_ACCEPTANCE_PSP: "cybersource_secure_acceptance";
+/** The dark-launch capability the API serves the Secure Acceptance recognizer behind (payment-core definitions.js). */
+export declare const SECURE_ACCEPTANCE_CAPABILITY: "cybersource_sa_token_create";
+/** How long after the pause a paused token request may still be sent; past it, nothing being handed over, it is retired. */
+export declare const SECURE_ACCEPTANCE_SEND_WINDOW_MS = 20000;
+/** How long after the pause CyberSource's reply may still be read; past it the outcome is unknown. */
+export declare const SECURE_ACCEPTANCE_REPLY_WINDOW_MS = 45000;
+/** How long after the create the authorization is read every 500 ms instead of at the caller's interval. */
+export declare const SECURE_ACCEPTANCE_FAST_POLL_MS = 30000;
+/** How long after the page is delivered the merchant's follow-up request is watched for. */
+export declare const SECURE_ACCEPTANCE_FOLLOW_UP_MS = 10000;
+/** The one content type the paused frame's answer carries, as CyberSource serves its page. */
+export declare const SECURE_ACCEPTANCE_ANSWER_CONTENT_TYPE: string;
+/** A reviewed production merchant, as payment-core's SECURE_ACCEPTANCE_MERCHANTS lists it; the fields this SDK reads. */
+export interface SecureAcceptanceMerchant {
+    id: string;
+    merchant: string;
+    environment: string;
+    status: string;
+    origins: readonly string[];
+    profileIds: readonly string[];
+    accessKeys?: readonly string[];
+    pending?: readonly string[];
+    /** The one request the merchant's page sends once the receipt answered it, watched for after delivery. */
+    followUp?: {
+        method: string;
+        url: string;
+    } | null;
+}
+/** Why prepare() refuses a Secure Acceptance checkout before any network call. */
+export type SecureAcceptanceCheckoutRefusal = 'secure_acceptance_profile_id_invalid' | 'merchant_profile_mismatch';
+/** Why a paused Secure Acceptance request ends with an unknown outcome, beside the reasons every processor shares. */
+export type SecureAcceptanceUnknownReason = 'secure_acceptance_reply_unconfirmed' | 'secure_acceptance_reply_late' | 'response_expired';
+/**
+ * The profile id a Secure Acceptance checkout prepares, or null when it can name none. A profile id the
+ * caller passes must have CyberSource's UUID shape, and is the one the bound request must carry. On the
+ * production host the caller may leave it out when exactly one entry this build reviewed lists the
+ * checkout page's origin, under exactly one profile id: that one is used, so the agent names nothing it
+ * cannot see. The test host has no entries (it takes only CyberSource's test cards), so a sandbox
+ * checkout always names its own. `entries` is for tests.
+ */
+export declare function secureAcceptanceCheckoutProfile(input: {
+    environment: string;
+    profileId?: unknown;
+    merchantOrigin: string;
+}, entries?: readonly SecureAcceptanceMerchant[]): string | null;
+/**
+ * Why a Secure Acceptance checkout may not be prepared under `merchant`, or null when it may:
+ * `secure_acceptance_profile_id_invalid` when it names no profile id this build can stand behind
+ * (secureAcceptanceCheckoutProfile), and, on the production host, `merchant_profile_mismatch` when the
+ * entry this build reviewed for that profile id and origin names another merchant, the one the approval
+ * shows. A profile id this build has not reviewed is the API's to judge (unsupported_checkout), as an
+ * eProtect paypageId is. `entries` is for tests.
+ */
+export declare function secureAcceptanceCheckoutRefusal(input: {
+    environment: string;
+    profileId?: unknown;
+    merchantOrigin: string;
+    merchant: string;
+}, entries?: readonly SecureAcceptanceMerchant[]): SecureAcceptanceCheckoutRefusal | null;
+/**
+ * Whether a paused request is the one shape the lane pays: a POST to the exact token-create URL on one of
+ * the two hosts (payment-core isSecureAcceptanceTokenRequest), sent as a navigation of a frame, as a
+ * merchant's form targeted at its hidden iframe sends it. A top navigation, a fetch and an XHR are not.
+ */
+export declare function isSecureAcceptanceFramePost(request: {
+    url: string;
+    method: string;
+    navigation: 'top' | 'frame' | null | undefined;
+}): boolean;
+/**
+ * The answer a paused token request gets, or null when the approved reply is not one to hand the frame:
+ * CyberSource's own page, byte for byte as the API stored it, with status 200 and the one content type
+ * CyberSource serves it with, and no other header. The page must pass payment-core's reply rule for the
+ * paused request (secureAcceptanceReplyOutcome: one hidden-input form posting to the receipt page the
+ * request signed, the request's own echoes, a masked number, a token, no card), run here with no card and
+ * no last four: the device and the API checked those.
+ */
+export declare function secureAcceptanceFrameAnswer(request: {
+    url: string;
+    body?: string | null;
+}, response: {
+    status: number;
+    headers?: Record<string, string>;
+    body: string;
+}): {
+    status: 200;
+    headers: Record<string, string>;
+    body: string;
+} | null;
+/**
+ * The request a reviewed merchant's page sends once its receipt page answered (Arrow: the payment-method
+ * set), for a production preparation whose profile id and origin an entry lists with one; null otherwise,
+ * the test host included. `entries` is for tests.
+ */
+export declare function secureAcceptanceFollowUp(preparation: {
+    environment: string;
+    secureAcceptanceProfileId?: string | null;
+    merchantOrigin: string;
+}, entries?: readonly SecureAcceptanceMerchant[]): {
+    method: string;
+    url: string;
+} | null;
+/**
+ * The last four digits of the masked number CyberSource's reply page echoes (req_card_number, masked as
+ * x's and the last four), or null when the page carries no single such field. The page passed the reply
+ * rule before it was delivered, so this only reads it back for the follow-up event; it never carries more
+ * than those four digits.
+ */
+export declare function secureAcceptanceReplyLast4(page: string): string | null;
+/**
+ * One attachment's watch for the merchant's follow-up request after a delivered reply. Read-only: it
+ * pauses, changes and delays nothing. The adapters report every request the page sends (CDP
+ * Network.requestWillBeSent, Playwright page.on('request')) through saw(); when none matches the
+ * merchant's follow-up within SECURE_ACCEPTANCE_FOLLOW_UP_MS, the event `secure_acceptance_reply_unused`
+ * names the authorization and the masked number's last four, so the agent can find the card the merchant
+ * may have kept (in its saved cards, ending in those four) before it ever asks for a new checkout.
+ */
+export declare class SecureAcceptanceFollowUpWatch {
+    private readonly onEvent?;
+    private readonly ms;
+    private watching;
+    constructor(onEvent?: ((event: {
+        type: string;
+        detail?: unknown;
+    }) => void) | undefined, ms?: number);
+    /** Start watching for `followUp` after the reply for `authorizationId` was delivered; a watch already running ends unreported. */
+    begin(followUp: {
+        method: string;
+        url: string;
+    }, detail: {
+        authorizationId: string;
+        last4: string | null;
+    }): void;
+    /** A request the page sent: the follow-up, when it is the one being watched for, ends the watch. */
+    saw(method: unknown, url: unknown): void;
+    /** True while a watch runs. */
+    get active(): boolean;
+    /** End the watch with no event. */
+    end(): void;
+}

package/dist/cybersource-secure-acceptance.generated.d.ts

@@ -0,0 +1,67 @@
+declare var SECURE_ACCEPTANCE_PSP: string;
+declare var SECURE_ACCEPTANCE_CAPABILITY: string;
+declare var SECURE_ACCEPTANCE_HOSTS: Readonly<{
+    production: "secureacceptance.cybersource.com";
+    sandbox: "testsecureacceptance.cybersource.com";
+}>;
+declare var SECURE_ACCEPTANCE_TOKEN_CREATE_PATH: string;
+declare var SECURE_ACCEPTANCE_SIGNED_FIELDS: readonly string[];
+declare var SECURE_ACCEPTANCE_OPTIONAL_SIGNED_FIELDS: readonly string[];
+declare var SECURE_ACCEPTANCE_UNSIGNED_FIELDS: readonly string[];
+declare var SECURE_ACCEPTANCE_OPTIONAL_UNSIGNED_FIELDS: readonly string[];
+declare var SECURE_ACCEPTANCE_CARD_TYPES: Readonly<{
+    visa: "001";
+    mastercard: "002";
+    amex: "003";
+    discover: "004";
+}>;
+declare var SECURE_ACCEPTANCE_TEST_PANS: Readonly<Set<unknown>>;
+declare var SECURE_ACCEPTANCE_REQUEST_REFUSALS: readonly string[];
+declare var SECURE_ACCEPTANCE_REFUSAL_REASON_CODES: readonly string[];
+declare var SECURE_ACCEPTANCE_REPLY_REASONS: readonly string[];
+declare var SECURE_ACCEPTANCE_PAGE_CONTENT_TYPE: string;
+declare var SECURE_ACCEPTANCE_MERCHANTS: any;
+declare function secureAcceptanceEnvironment(hostname: any): "production" | "sandbox" | null;
+declare function secureAcceptancePreparationUrl(environment: any): string;
+declare function isSecureAcceptanceTokenRequest(url: any, method: any): boolean;
+declare function secureAcceptanceRequestRefusal(request: any, options: any): "card_fields" | "profile_id" | "access_key" | "currency" | "signed_date_time" | "locale" | "origin_header" | "not_token_create" | "content_type" | "referer_header" | "body_unreadable" | "signed_fields_unreviewed" | "unsigned_fields_unreviewed" | "fields_unreviewed" | "transaction_type" | "amount_not_zero" | "payment_method" | "receipt_page" | "keeps_card" | "edits_saved_card" | "merchant_reference" | "card_type" | "bill_to" | "signature" | "request_ids" | "device_fingerprint" | null;
+declare function secureAcceptanceRequestFacts(request: any): {
+    environment: string | null;
+    profileId: any;
+    accessKey: any;
+    transactionUuid: any;
+    referenceNumber: any;
+    currency: any;
+    signedDateTime: any;
+} | null;
+declare function isPreparedSecureAcceptanceRequest(url: any, method: any, body: any, headers: any, environment: any, binding: any): boolean;
+declare function secureAcceptanceMerchantEntry(profileId: any, merchantOrigin: any, entries?: any): any;
+declare function secureAcceptanceMerchantRefusal(environment: any, profileId: any, merchantOrigin: any, accessKey: any, entries?: any): "unsupported_environment" | "invalid_profile_id" | "secure_acceptance_merchant_unreviewed" | "secure_acceptance_merchant_pending" | "secure_acceptance_access_key_unreviewed" | "secure_acceptance_merchant_observe" | null;
+declare function secureAcceptanceCardType(number: any): "001" | "002" | "003" | "004" | null;
+declare function secureAcceptanceCardRefusal(environment: any, card: any): "unsupported_environment" | "sandbox_host_requires_documented_test_card" | "invalid_card_number" | "live_host_refuses_documented_test_card" | "card_network_unsupported" | "invalid_expiry" | "invalid_cvn" | null;
+declare function isSecureAcceptanceDeviceRequest(templateBody: any, deviceBody: any, environment: any): boolean;
+declare function secureAcceptanceDeviceRequest(request: any, card: any, options: any): {
+    url: any;
+    method: string;
+    headers: {
+        "content-type": string;
+        origin: string;
+    };
+    body: string;
+    where: string[];
+};
+declare function secureAcceptanceScannedPage(bodyText: any, template: any): any;
+declare function secureAcceptanceReplyOutcome(reply: any, template: any, card: any, options: any): {
+    outcome: string;
+    reason: any;
+} | {
+    outcome: string;
+    page: any;
+    code?: undefined;
+} | {
+    outcome: string;
+    code: any;
+    page?: undefined;
+};
+declare function secureAcceptanceRefusalCode(bodyText: any): any;
+export { SECURE_ACCEPTANCE_CAPABILITY, SECURE_ACCEPTANCE_CARD_TYPES, SECURE_ACCEPTANCE_HOSTS, SECURE_ACCEPTANCE_MERCHANTS, SECURE_ACCEPTANCE_OPTIONAL_SIGNED_FIELDS, SECURE_ACCEPTANCE_OPTIONAL_UNSIGNED_FIELDS, SECURE_ACCEPTANCE_PAGE_CONTENT_TYPE, SECURE_ACCEPTANCE_PSP, SECURE_ACCEPTANCE_REFUSAL_REASON_CODES, SECURE_ACCEPTANCE_REPLY_REASONS, SECURE_ACCEPTANCE_REQUEST_REFUSALS, SECURE_ACCEPTANCE_SIGNED_FIELDS, SECURE_ACCEPTANCE_TEST_PANS, SECURE_ACCEPTANCE_TOKEN_CREATE_PATH, SECURE_ACCEPTANCE_UNSIGNED_FIELDS, isPreparedSecureAcceptanceRequest, isSecureAcceptanceDeviceRequest, isSecureAcceptanceTokenRequest, secureAcceptanceCardRefusal, secureAcceptanceCardType, secureAcceptanceDeviceRequest, secureAcceptanceEnvironment, secureAcceptanceMerchantEntry, secureAcceptanceMerchantRefusal, secureAcceptancePreparationUrl, secureAcceptanceRefusalCode, secureAcceptanceReplyOutcome, secureAcceptanceRequestFacts, secureAcceptanceRequestRefusal, secureAcceptanceScannedPage };