@agent-cards/sdk 0.23.28 → 0.24.0

package/dist/hold.js

@@ -17,6 +17,9 @@
 //   - Any request whose body carries the placeholder card number (`placeholderNumbers`): a store's own card post or
 //     an unknown processor. The browser only ever holds the placeholder, so a body with its digits is a card request
 //     wherever it goes. In sandbox it may be released unchanged (it carries the documented test number only).
+//   - With `placeholderNumbers`, any request whose body carries a card a processor's frame encrypted in the page
+//     (Adyen's encryptedCardNumber, Braintree's legacy CSE, Worldline Connect's encryptedCustomerInput) sent to the
+//     merchant's own server instead of the processor (encryptedCardHoldRule). Held, then only cancelled.
 // The hold records the processor and the endpoint (origin and path, any path credential masked), never a body or a
 // header.
 import { redactUrl } from './client.js';
@@ -54,6 +57,36 @@ export function placeholderHoldRule(numbers, deadlineMs = HOLD_DEFAULT_DEADLINE_
         patterns: PLACEHOLDER_RESOURCE_TYPES.map((resourceType) => ({ urlPattern: '*', resourceType })),
     };
 }
+/**
+ * A card a processor's own frame encrypted in the page, sent on inside the merchant's own request (its order or payment
+ * step) instead of to the processor: the placeholder's digits never appear, so placeholderHoldRule cannot see it, and
+ * no recogniser matches the merchant's URL. Adyen's card component on Salesforce Commerce, Magento and other Advanced
+ * (non-Sessions) integrations posts `encryptedCardNumber` (a JWE, `eyJ...`, or the legacy `adyenjs_0_1_...`) to the
+ * store's CheckoutServices-SubmitPayment / PlaceOrder: ca.coach.com's PlaceOrder answered 200 with no hold on
+ * 2026-10-23. Also caught: Braintree's legacy client-side encryption (`$bt4|javascript_...`) and Worldline/Ingenico
+ * Connect's `encryptedCustomerInput`. Matched in JSON, escaped JSON, URL-encoded and form bodies. Held, then only
+ * cancelled: no release can answer a request the vault never encrypted for.
+ */
+const Q = '(?:\\\\?"|%22|%5C%22|\\\\u0022)?';
+const SEP = '\\s*(?::|%3A|=)\\s*';
+// A multipart field: the name's closing quote, the part's remaining header lines, a blank line, then the value.
+// The value is read on its own line only: never across a line break, and never a boundary line (`--...`), so an empty
+// field followed by a long boundary is not a card.
+const PART = '"?[^\\r\\n]{0,80}\\r?\\n(?:[^\\r\\n]{1,200}\\r?\\n){0,4}\\r?\\n[ \\t]*(?!--)';
+const ENCRYPTED_CARD_BODY = new RegExp([
+    `encryptedCardNumber${Q}${SEP}${Q}\\s*(?:eyJ|adyenjs_|[A-Za-z0-9+/_$|.-]{40})`,
+    `encryptedCardNumber${PART}(?:eyJ|adyenjs_|[A-Za-z0-9+/_$|.-]{40})`,
+    `encryptedCustomerInput${PART}[A-Za-z0-9+/_.-]{40}`,
+    'adyenjs_0_[0-9]+_[0-9]+(?:\\$|%24)',
+    '\\$bt[0-9]\\|javascript_|%24bt[0-9](?:\\||%7C)javascript_',
+    `encryptedCustomerInput${Q}${SEP}${Q}\\s*[A-Za-z0-9+/_.-]{40}`,
+].join('|'), 'i');
+export function encryptedCardHoldRule(deadlineMs = HOLD_DEFAULT_DEADLINE_MS) {
+    return {
+        psp: 'encrypted_card', match: /^[a-z]+:\/\//i, body: ENCRYPTED_CARD_BODY, kind: 'store_card_post', deadlineMs, methods: ['POST', 'PUT', 'PATCH'],
+        patterns: PLACEHOLDER_RESOURCE_TYPES.map((resourceType) => ({ urlPattern: '*', resourceType })),
+    };
+}
 /** The hold-only rule a request is a card request under, or null. */
 export function matchHoldOnlyRule(request, rules) {
     for (const rule of rules) {
@@ -127,11 +160,15 @@ export class HoldGate {
         this.sandbox = sandbox;
         this.emit = emit;
         const placeholder = options.placeholderNumbers?.length ? placeholderHoldRule(options.placeholderNumbers) : null;
-        this.rules = [BOLT_HOLD_RULE, ...(placeholder ? [placeholder] : [])];
+        // A page the vault types its placeholder into is watched for every card leaving it, encrypted or not; the
+        // encrypted-card rule shares the placeholder rule's patterns, so it pauses nothing more. It comes first: a body
+        // carrying both the placeholder and an encrypted card is the encrypted card's, and is never continued.
+        this.rules = [BOLT_HOLD_RULE, ...(placeholder ? [encryptedCardHoldRule(), placeholder] : [])];
     }
     get state() { return this._state; }
     get held() { return this._held ? { ...this._held } : null; }
     get refused() { return this._refused; }
+    get covers() { return this.rules.map((r) => r.psp); }
     /** Fetch patterns the hold-only rules need beside the registry's. */
     patterns() { return this.rules.flatMap((r) => r.patterns); }
     deadlineFor(psp, rule) {
@@ -245,7 +282,11 @@ export class HoldGate {
         let settle;
         const settled = new Promise((resolve) => { settle = resolve; });
         if (!held.replayable) {
-            if (held.kind === 'store_card_post' && input.continuePlaceholder && this.sandbox) {
+            // Only the plain placeholder post may be sent on in sandbox: an encrypted card inside a merchant's own order or
+            // payment request (encrypted_card) is the order itself, and is never continued in any mode.
+            if (held.psp === 'encrypted_card')
+                return fail('encrypted_card_post');
+            if (held.kind === 'store_card_post' && held.psp === 'placeholder_card' && input.continuePlaceholder && this.sandbox) {
                 this.decide({ kind: 'continue', settle });
                 this.emit('card_request_released', { psp: held.psp, continued: true, amount: input.amount, currency: input.currency.toLowerCase(), upTo: !!input.upTo });
                 return settled;

package/dist/hosted-entry.js

@@ -18,11 +18,13 @@ import { PRZELEWY24_PSP, isPrzelewy24EntryUrl } from './przelewy24.js';
 import { COMGATE_PSP, isComgateEntryUrl } from './comgate.js';
 import { TRANSBANK_PSP, isTransbankEntryUrl } from './transbank.js';
 import { BARION_PSP, isBarionEntryUrl } from './barion.js';
+import { PAYPLUG_PSP, isPayplugEntryUrl } from './payplug.js';
 const HOSTED_GET_ENTRIES = new Map([
     [PRZELEWY24_PSP, isPrzelewy24EntryUrl],
     [COMGATE_PSP, isComgateEntryUrl],
     [TRANSBANK_PSP, isTransbankEntryUrl],
     [BARION_PSP, isBarionEntryUrl],
+    [PAYPLUG_PSP, isPayplugEntryUrl],
 ]);
 /** Whether this processor's hosted page is entered with a GET this build reads exactly. */
 export function hasHostedGetEntry(psp) {

package/dist/index.d.ts

@@ -14,7 +14,7 @@ export type { SecureAcceptanceCheckoutRefusal, SecureAcceptanceUnknownReason } f
 export type { PausedRequest, ReplayResponse, TokenReplay, CseReplay, MerchantHostedReplay, VerifoneReplay, HostedFormReplay, CardEndpointReplay, DeviceEncryptReplay, AmountAuthority, AuthorizeInput, VaultClientOptions, AgentcardOptions, AdyenTestPlatformRefusal, MerchantTotalRefusal, PrepareCheckoutOptions, PrepareCheckoutInput, PreparedCheckout, RazorpayProcessorError, RuntimeCancelReason, ExecutionMetadata, PlaceholderCard, } from './client.js';
 export type { MicroformField, MicroformSidecar } from './cybersource-flex.js';
 export { attachToCdp, attachToPlaywright, corsHeadersFor, corsDecision, withCorsHeaders } from './cdp.js';
-export { BOLT_HOLD_RULE, HOLD_DEADLINES_MS, HOLD_DEFAULT_DEADLINE_MS, HOLD_DEADLINE_MARGIN_MS, HoldAnsweredError, HoldEndedError, matchHoldOnlyRule, placeholderHoldRule } from './hold.js';
+export { BOLT_HOLD_RULE, HOLD_DEADLINES_MS, HOLD_DEFAULT_DEADLINE_MS, HOLD_DEADLINE_MARGIN_MS, HoldAnsweredError, HoldEndedError, matchHoldOnlyRule, placeholderHoldRule, encryptedCardHoldRule } from './hold.js';
 export type { CardRequestHold, HeldCardRequest, HoldOnlyRule, HoldOptions, HoldReleaseInput, HoldReleaseOutcome, HoldState } from './hold.js';
 export { CheckoutAttachmentError } from './attachment.js';
 export { EbanxFollowUpError } from './ebanx.js';
@@ -28,7 +28,7 @@ export { substituteEncryptedFields, SubstitutionError } from './substitute.js';
 export { PaddleCheckoutWatch, type PaddleCheckoutAnswer, type PaddleCheckoutCapture } from './paddle-checkout-watch.js';
 export type { Substitutions } from './substitute.js';
 export { classifyDeclaredMerchantRequest, classifyMerchantRequest, substituteMerchantHostedBody } from './merchant-hosted.js';
-export type { MerchantProfile, MerchantProfileStatus, MerchantRequestVerdict, MerchantHostedSubstitutions, MerchantHostedFact, JsonPathStep, SandboxMerchantDeclaration } from './merchant-hosted.js';
+export type { MerchantProfile, MerchantProfileStatus, MerchantRequestVerdict, MerchantHostedSubstitutions, MerchantHostedFact, JsonPathStep, JsonTextStep, ProfilePathStep, SandboxMerchantDeclaration } from './merchant-hosted.js';
 export { MerchantExchangeLog, merchantAmountExchanges, merchantAmountFromResponses, merchantChargeReport, merchantProfilePricedBySource, merchantTotalAtRelease, MERCHANT_EXCHANGES_MAX, } from './merchant-total.js';
 export type { MerchantAmountCard, MerchantExchange, MerchantRequestSeen, MerchantTotalApproved, MerchantTotalCapture, MerchantTotalScope } from './merchant-total.js';
 export { substituteFiservEnvelope } from './fiserv.js';
@@ -39,21 +39,15 @@ export type { HostedFormSubmittedPageInput, SyntheticPage } from './hosted-form.
 export { BUILTIN_REGISTRY, cardUrlPatterns, findRecognizer, isLoopbackUrl, LOOPBACK_URL_PATTERNS } from './registry.js';
 export type { Recognizer, CheckoutMode, RecognizerOptions } from './registry.js';
 export type { PayrailsSidecar, PayrailsUnsupportedReason } from './payrails.js';
-export type { CheckoutController, CheckoutState, MerchantResult, MerchantPaymentConfirmation, UserAction, LifecycleOptions, PaymentEndpointGuard, PausedCheckout, ResumeResult } from './lifecycle.js';
+export type { CheckoutController, CheckoutState, MerchantResult, MerchantPaymentConfirmation, UserAction, LifecycleOptions, PaymentEndpointGuard } from './lifecycle.js';
 export { RequestRegistry, BUILTIN_REQUEST_BUILDERS, stripePaymentIntentConfirm, stripePaymentIntentConfirmRequest, stripeCardTokenRequest, stripePaymentMethodRequest } from './requests.js';
 export type { RequestBuilder, BuildInput, MintedIntent } from './requests.js';
-export { VoiceModule, checkoutOriginOf, CANCEL_REASONS, bundleOf, streamAddress, SANDBOX_REQUEST } from './voice.js';
-export type { VoiceOptions, VoiceTransport } from './voice.js';
 export type { ApiTransport } from './api-module.js';
-export { BuyModule, BuyError, isBuyDeclined, isBuyNeedsApproval, isBuyVoiceUnsupported, BUY_TURN_TIMEOUT_MS, VOICE_EXECUTION_UNSUPPORTED } from './buy.js';
-export type { BuyStatus, BuyApproval, BuyVoiceDeclineCode, BuyCart, BuyCartLine, BuyDeliveryAddress, BuyPaymentSource, BuyOutcome, BuyPlacement, BuyCatalog, BuyUnmatched, BuyTurn, BuyDeclined, BuyNeedsApproval, BuyVoiceUnsupported, BuyVoiceTurn, BuyOrder, BuyLastCheckout, BuyConversation, BuyAskInput, BuyConfirmInput, BuyApproveByVoiceInput, BuyConversationInput, BuyCheckoutHandoff, BuyOpenOffer, BuyBrowserCheckout, BuyApiAmount, } from './buy.js';
-export { Languages } from './languages.js';
-export type { Language, LanguageInfo } from './languages.js';
+export { BuyModule, BuyError, isBuyDeclined, BUY_TURN_TIMEOUT_MS } from './buy.js';
+export type { BuyStatus, BuyCart, BuyCartLine, BuyDeliveryAddress, BuyPaymentSource, BuyOutcome, BuyPlacement, BuyCatalog, BuyUnmatched, BuyTurn, BuyDeclined, BuyOrder, BuyLastCheckout, BuyConversation, BuyAskInput, BuyConfirmInput, BuyConversationInput, BuyCheckoutHandoff, BuyOpenOffer, BuyBrowserCheckout, BuyApiAmount, } from './buy.js';
+export { ApprovalsModule, CANCEL_REASONS, SANDBOX_REQUEST } from './approvals.js';
+export type { CreateAuthorizationInput, Authorization, AuthorizationResult, AuthorizationFields, Cancelled, PayingCard, ChoosableCard } from './approvals.js';
 export { verifyWebhook, signWebhook, parseWebhookEvent, parseSignatureHeader, isCheckoutAuthorizationEvent, isVaultEvent, CHECKOUT_AUTHORIZATION_EVENT_TYPES, VAULT_EVENT_TYPES } from './webhooks.js';
 export type { WebhookEvent, AgentcardEvent, CheckoutAuthorizationEvent, CheckoutAuthorizationEventType, CheckoutAuthorizationEventData, VaultEvent, VaultEventType, VaultEventData, OtherEvent, VerifyWebhookOptions } from './webhooks.js';
-export { readReturnLink } from './voice-pkce.js';
-export type { PkceCrypto } from './voice-pkce.js';
-export { AgentcardError } from './voice-types.js';
-export type { Lang, VoiceAsk, ApprovalPosture, Action, ConnectInput, ConnectResult, Connected, Person, Proposed, Done, ActionState, CreateAuthorizationInput, AuthorizationStatus, Authorization, VoiceResetInput, VoiceChallenge, AuthorizationResult, Verdict, AuthorizationDetail, Exchanged, ExchangeInput, Revoked, TerminalReason, DeliveryChannel, InteractionEvidence, Intent, ApprovalRequestFields, CancelReason, Cancelled, Settlement, SessionState, ReturnLink, VoiceResetOutcome, VaultSessionStep, HostApprovalBundle, AppVoiceKeyDescription, HardwareAttestation, RegisteredAppVoiceKey, RevokedAppVoiceKey, PayingCard, ChoosableCard, } from './voice-types.js';
-export { openStream, streamBuffer } from './voice-stream.generated.js';
-export type { Hearing, StreamFormat, StreamHandle, StreamInput, StreamVerdict, ChannelKind } from './voice-stream.generated.js';
+export { AgentcardError } from './api-types.js';
+export type { AuthorizationStatus, TerminalReason, CancelReason, Settlement } from './api-types.js';

package/dist/index.js

@@ -4,7 +4,7 @@ export { Agentcard, Agentcard as VaultClient, CheckoutModule } from './agentcard
 export { CardEncryptedError, UnsupportedModeError, UnsupportedCapabilityError, PreparationRequiredError, AmountRequiredError, PageAmountRequiredError, ApprovalTimeoutError, ApprovalDeclinedError, AmountMismatchError, PresetRefusedError, PRESET_REFUSAL_REASONS, IntentNotConfirmableError, ProcessorRefusedError, CheckoutApiError, CheckoutAuthError, redactUrl, SUPPORTED_MODES, SUPPORTED_CAPABILITIES, PaymentOutcomeUnknownError, CheckoutCancelledError, CheckoutPreparationError, AdyenTestPlatformRefusedError, MerchantTotalError, PlaceholderCardError, } from './client.js';
 export { CONVERGE_REFUSAL_REASONS } from './elavon-converge.js';
 export { attachToCdp, attachToPlaywright, corsHeadersFor, corsDecision, withCorsHeaders } from './cdp.js';
-export { BOLT_HOLD_RULE, HOLD_DEADLINES_MS, HOLD_DEFAULT_DEADLINE_MS, HOLD_DEADLINE_MARGIN_MS, HoldAnsweredError, HoldEndedError, matchHoldOnlyRule, placeholderHoldRule } from './hold.js';
+export { BOLT_HOLD_RULE, HOLD_DEADLINES_MS, HOLD_DEFAULT_DEADLINE_MS, HOLD_DEADLINE_MARGIN_MS, HoldAnsweredError, HoldEndedError, matchHoldOnlyRule, placeholderHoldRule, encryptedCardHoldRule } from './hold.js';
 export { CheckoutAttachmentError } from './attachment.js';
 // EBANX after its card token: why a send an approved token request covers got no answer from the cardholder's device.
 export { EbanxFollowUpError } from './ebanx.js';
@@ -22,14 +22,10 @@ export { hostedFormSubmittedPage, HOSTED_FORM_SUBMITTED_OUTCOME } from './hosted
 export { BUILTIN_REGISTRY, cardUrlPatterns, findRecognizer, isLoopbackUrl, LOOPBACK_URL_PATTERNS } from './registry.js';
 // The request builders: `agentcard.checkout.requests`, and the shipped builders as functions.
 export { RequestRegistry, BUILTIN_REQUEST_BUILDERS, stripePaymentIntentConfirm, stripePaymentIntentConfirmRequest, stripeCardTokenRequest, stripePaymentMethodRequest } from './requests.js';
-// The voice module: `agentcard.voice.*` (a person connected, a purchase approved by voice), its wire shapes and the streaming door. The phone package is `@agent-cards/voice`.
-export { VoiceModule, checkoutOriginOf, CANCEL_REASONS, bundleOf, streamAddress, SANDBOX_REQUEST } from './voice.js';
-// The buy module: `agentcard.buy.*` (the Purchase API from the same client: ask, confirm against an approval the business holds or by voice in its app, read a conversation).
-export { BuyModule, BuyError, isBuyDeclined, isBuyNeedsApproval, isBuyVoiceUnsupported, BUY_TURN_TIMEOUT_MS, VOICE_EXECUTION_UNSUPPORTED } from './buy.js';
-// Languages are data: `agentcard.voice.languages()` lists them, and a tag not on the list is refused before any call.
-export { Languages } from './languages.js';
+// The buy module: `agentcard.buy.*` (the Purchase API from the same client: ask, confirm against an approval the business holds, read a conversation).
+export { BuyModule, BuyError, isBuyDeclined, BUY_TURN_TIMEOUT_MS } from './buy.js';
+// The approvals module: `agentcard.approvals.*` (a purchase your server creates, approved on Agentcard's page).
+export { ApprovalsModule, CANCEL_REASONS, SANDBOX_REQUEST } from './approvals.js';
 // Webhooks: verified and typed.
 export { verifyWebhook, signWebhook, parseWebhookEvent, parseSignatureHeader, isCheckoutAuthorizationEvent, isVaultEvent, CHECKOUT_AUTHORIZATION_EVENT_TYPES, VAULT_EVENT_TYPES } from './webhooks.js';
-export { readReturnLink } from './voice-pkce.js';
-export { AgentcardError } from './voice-types.js';
-export { openStream, streamBuffer } from './voice-stream.generated.js';
+export { AgentcardError } from './api-types.js';

package/dist/lifecycle.d.ts

@@ -1,7 +1,6 @@
 import { CheckoutPreparationError, type PrepareCheckoutOptions, type PreparedCheckout, type ReplayResponse } from './client.js';
 import type { CheckoutMode } from './registry.js';
 import type { PayrailsUnsupportedReason } from './payrails.js';
-import type { Substitutions } from './substitute.js';
 import type { GmoUnsupportedReason } from './gmo.js';
 import type { ShijiStsUnsupportedReason } from './shiji-sts.js';
 import type { PaddleVgsPayRefusal } from './paddle-vgs-pay.js';
@@ -54,64 +53,8 @@ export interface LifecycleOptions {
     /** Hold further card requests after handoff until the merchant result is reconciled. Default false for compatibility. */
     requireMerchantResult?: boolean;
 }
-/**
- * A browser purchase paused for the business to create: what
- * `attachToCdp(…, { pauseOnly: true })` hands `onPaused`. The business creates
- * the authorization from `request` (`voice.authorizations.create` with its
- * posture, user and return link), reads the result, and calls
- * `controller.resume(result)`.
- */
-export interface PausedCheckout {
-    /** The card request the page sent, as the create takes it. */
-    request: {
-        url: string;
-        method: string;
-        headers: Record<string, string>;
-        body: string;
-    };
-    /** The recogniser that claimed the request, by its processor name (`stripe`); null when the pause named none. Nothing to re-match. */
-    recognizer: string | null;
-    /** The checkout page's origin (`https://shop.example`), when the browser exposed it; what `checkout_origin` names. */
-    page_origin?: string;
-    controller: CheckoutController;
-}
-/**
- * The authorization as the business read it, handed to `controller.resume`
- * : `voice.awaitResult`'s answer as it is, or any object with
- * these fields. `approved` with `response` replays the processor's answer into
- * the page (`token`); with `substitutions` the page's own request continues
- * with the ciphertext (`cse`); with `submitted_at` the paused navigation is
- * answered as a hosted form submitted on the device. A terminal status
- * (`declined`, `cancelled`, `expired`, `timeout`) fails the page's request
- * with nothing charged.
- */
-export interface ResumeResult {
-    id?: string;
-    status: string;
-    mode?: string;
-    response?: {
-        status: number;
-        headers: Record<string, string>;
-        body: string;
-    };
-    /**
-     * The read's `processor_context`, as the API serves it. A Paddle VGS read carries the approved card's
-     * details here, which the frame's /pay names; without them the stored card's id is never handed to the page.
-     */
-    processor_context?: unknown;
-    substitutions?: Substitutions;
-    submitted_at?: string;
-    execution_mode?: string;
-    terminal_reason?: string | null;
-    approved_with?: string | null;
-}
 export interface CheckoutController {
     getState(): Readonly<CheckoutState>;
-    /**
-     * Answer the paused card request with the authorization the business created and read (* `attachToCdp(…, { pauseOnly: true })` only). Resolves once the page has its answer, or the request is
-     * failed for a terminal status; rejects when no request is paused or the read is not final.
-     */
-    resume(result: ResumeResult): Promise<void>;
     /** Await device consent before the caller starts the first native Pay action. One use per attachment. */
     prepare(options: PrepareCheckoutOptions): Promise<PreparedCheckout>;
     /**
@@ -163,6 +106,7 @@ export declare class CheckoutLifecycle implements CheckoutController {
     private stripeContinuedReason;
     private approvedPaymentMethod;
     private ownedShopOrderId;
+    private orderRefusal;
     private readonly handoffs;
     private reconciliation;
     /**
@@ -172,7 +116,6 @@ export declare class CheckoutLifecycle implements CheckoutController {
     private followUpsOut;
     private preparationHandler?;
     private preparationUsed;
-    private resumeHandler;
     private holdHandle;
     readonly abort: AbortController;
     constructor(options: LifecycleOptions);
@@ -183,9 +126,6 @@ export declare class CheckoutLifecycle implements CheckoutController {
     setHold(hold: CardRequestHold): void;
     get hold(): CardRequestHold | null;
     release(input: HoldReleaseInput): Promise<HoldReleaseOutcome>;
-    /** The transport's hand while one request is paused for the business; null once it is answered. */
-    setResumeHandler(handler: ((result: ResumeResult) => Promise<void>) | null): void;
-    resume(result: ResumeResult): Promise<void>;
     preparing(): void;
     preparationCreated(preparationId: string): void;
     prepared(preparation: PreparedCheckout): void;
@@ -293,6 +233,14 @@ export declare class CheckoutLifecycle implements CheckoutController {
      * state keeps it, and only the hold changes.
      */
     unsupported(reason?: 'unrecognized_payment_endpoint' | 'merchant_profile_observe' | 'merchant_request_unsupported' | GmoUnsupportedReason | 'microform_unsupported' | 'juspay_request_unsupported' | 'merchant_card_endpoint_not_enabled' | 'merchant_card_endpoint_resend_refused' | 'creditguard_three_d_secure' | 'unsupported_primer_sdk' | 'unsupported_primer_request' | PayrailsUnsupportedReason | ShijiStsUnsupportedReason | 'processor_card_page' | 'unsupported_paypal_hosted_fields' | PaypalCardFormReason | 'unsupported_cybersource_secure_acceptance' | PaddleVgsPayRefusal | 'unsupported_ebanx_card_resend' | 'unsupported_payrexx_card_resend'): void;
+    /**
+     * Nike's order after its card was refused before it left (pre-claim.ts nikeOrderPreClaim): the card reached
+     * Nike's store and the order that would charge it never did, so a checkout still under way ends `failed` with
+     * the refusal's reason, nothing charged, and stays failed when the approval it was waiting on lands after the
+     * refusal (handedOff). A checkout that already ended keeps its state. Either way the attachment holds until the
+     * application starts another attempt.
+     */
+    merchantOrderRefused(reason: string): void;
     /**
      * A card request that only a prepared checkout pays (an Adyen merchant
      * profile's, or a Fiserv card capture) arrived with no preparation on this

package/dist/lifecycle.js

@@ -65,6 +65,8 @@ export class CheckoutLifecycle {
     // The payment method a Stripe /v1/payment_methods approval returned: see approvedStripePaymentMethod.
     approvedPaymentMethod = null;
     ownedShopOrderId = null;
+    // The reason Nike's order was refused while this attempt was under way (merchantOrderRefused): its handoff keeps it failed.
+    orderRefusal = null;
     // Every request this attachment handed the card to: see cardHandoffs().
     handoffs = [];
     reconciliation = null;
@@ -75,7 +77,6 @@ export class CheckoutLifecycle {
     followUpsOut = 0;
     preparationHandler;
     preparationUsed = false;
-    resumeHandler = null;
     holdHandle = null;
     abort = new AbortController();
     constructor(options) {
@@ -98,15 +99,6 @@ export class CheckoutLifecycle {
             return Promise.reject(new Error('No card request hold: attach with hold: true.'));
         return this.holdHandle.release(input);
     }
-    /** The transport's hand while one request is paused for the business; null once it is answered. */
-    setResumeHandler(handler) { this.resumeHandler = handler; }
-    resume(result) {
-        if (!this.resumeHandler)
-            return Promise.reject(new Error('No card request is paused for the business to answer; attach with pauseOnly: true and wait for onPaused.'));
-        if (!result || typeof result !== 'object' || typeof result.status !== 'string')
-            return Promise.reject(new Error('resume takes the authorization as read: an object with a status.'));
-        return this.resumeHandler(result);
-    }
     preparing() {
         this.preparationUsed = true;
         this.set({ status: 'awaiting_approval', authorizationId: null });
@@ -299,6 +291,20 @@ export class CheckoutLifecycle {
             return; // do not hide an outstanding/completed payment behind a later unsupported request
         this.set({ ...this.state, status: 'unsupported', reason });
     }
+    /**
+     * Nike's order after its card was refused before it left (pre-claim.ts nikeOrderPreClaim): the card reached
+     * Nike's store and the order that would charge it never did, so a checkout still under way ends `failed` with
+     * the refusal's reason, nothing charged, and stays failed when the approval it was waiting on lands after the
+     * refusal (handedOff). A checkout that already ended keeps its state. Either way the attachment holds until the
+     * application starts another attempt.
+     */
+    merchantOrderRefused(reason) {
+        this.held = true;
+        if (this.cancelled || FINAL_STATUSES.has(this.state.status))
+            return;
+        this.orderRefusal = reason;
+        this.set({ ...this.state, status: 'failed', reason });
+    }
     /**
      * A card request that only a prepared checkout pays (an Adyen merchant
      * profile's, or a Fiserv card capture) arrived with no preparation on this
@@ -410,6 +416,13 @@ export class CheckoutLifecycle {
         if (this.merchantAborted)
             return;
         this.settled = true;
+        if (this.orderRefusal) {
+            // Nike's order was refused while this approval was on its way: the answer lands, and the checkout stays failed.
+            this.held = true;
+            this.set({ status: 'failed', authorizationId: replay.authorizationId, mode: replay.mode ?? 'token', reason: this.orderRefusal,
+                ...(this.state.preparationId ? { preparationId: this.state.preparationId } : {}) });
+            return;
+        }
         if (this.ownedShopOrderId) {
             this.held = true;
             this.set({ status: 'completed', authorizationId: replay.authorizationId, mode: 'token', orderId: this.ownedShopOrderId });
@@ -600,6 +613,7 @@ export class CheckoutLifecycle {
             throw new Error('This attachment delivered an unbound Stripe token; reconcile the merchant order and use a separately validated checkout flow.');
         this.held = false;
         this.merchantAborted = false;
+        this.orderRefusal = null;
         this.set({ status: 'idle', authorizationId: null });
     }
 }

package/dist/merchant-card-endpoints.generated.d.ts

@@ -41,6 +41,11 @@ declare function merchantCardEndpointFactsRefusal(profile: any, facts: any, agen
     code: any;
     reason: any;
 } | null;
+declare var NIKE_ORDER: any;
+declare var NIKE_ORDER_REFUSALS: any;
+declare function nikeOrderHost(url: any): boolean;
+declare function nikeOrderRequest(url: any, method: any): boolean;
+declare function nikeOrderRefusal(url: any, method: any, body: any, approved: any): "body_unreadable" | "amount_mismatch" | "currency_mismatch" | "request_unrecognized" | "total_unreadable" | "currency_unreadable" | "approval_unknown" | null;
 declare var MERCHANT_CARD_ENDPOINT_LIMITS: Readonly<{
     bodyBytes: number;
     answerBytes: number;
@@ -119,4 +124,4 @@ declare function merchantCardEndpointNavigationAnswer(profile: any, answer: any,
     location: string;
     reason?: undefined;
 };
-export { HILTON_CREATE_RESERVATION_DOCUMENTS, MERCHANT_CARD_ENDPOINT_CLIENT_TABLE, MERCHANT_CARD_ENDPOINT_FACTS_TEXT_MAX, MERCHANT_CARD_ENDPOINT_FACT_READERS, MERCHANT_CARD_ENDPOINT_LIMITS, MERCHANT_CARD_ENDPOINT_MODE, MERCHANT_CARD_ENDPOINT_PROFILES, MERCHANT_CARD_ENDPOINT_PSP, MERCHANT_CARD_ENDPOINT_RECOGNIZERS, SubstitutionError, assertMerchantCardEndpoint, encryptMerchantCardEndpointBody, encryptedMerchantEndpointRequest, matchMerchantCardEndpoint, matchMerchantCardEndpointResend, merchantCardEndpointAmount, merchantCardEndpointAnswer, merchantCardEndpointAnswerRefusal, merchantCardEndpointBodyRefusal, merchantCardEndpointById, merchantCardEndpointCarriesCard, merchantCardEndpointCheckoutKey, merchantCardEndpointEncrypts, merchantCardEndpointFactsRefusal, merchantCardEndpointFactsRole, merchantCardEndpointLive, merchantCardEndpointMatches, merchantCardEndpointNavigationAnswer, merchantCardEndpointPasses, merchantCardEndpointRecognizerById, merchantCardEndpointRequestOrigin, merchantCardEndpointSessionRefusal, merchantCardEndpointSessionTtl, merchantEndpointRequest, projectMerchantCardEndpointFacts, readMerchantCardEndpointFacts, responseCardLeak, substituteMerchantCardEndpoint, trustedMerchantCardEndpoint };
+export { HILTON_CREATE_RESERVATION_DOCUMENTS, MERCHANT_CARD_ENDPOINT_CLIENT_TABLE, MERCHANT_CARD_ENDPOINT_FACTS_TEXT_MAX, MERCHANT_CARD_ENDPOINT_FACT_READERS, MERCHANT_CARD_ENDPOINT_LIMITS, MERCHANT_CARD_ENDPOINT_MODE, MERCHANT_CARD_ENDPOINT_PROFILES, MERCHANT_CARD_ENDPOINT_PSP, MERCHANT_CARD_ENDPOINT_RECOGNIZERS, NIKE_ORDER, NIKE_ORDER_REFUSALS, SubstitutionError, assertMerchantCardEndpoint, encryptMerchantCardEndpointBody, encryptedMerchantEndpointRequest, matchMerchantCardEndpoint, matchMerchantCardEndpointResend, merchantCardEndpointAmount, merchantCardEndpointAnswer, merchantCardEndpointAnswerRefusal, merchantCardEndpointBodyRefusal, merchantCardEndpointById, merchantCardEndpointCarriesCard, merchantCardEndpointCheckoutKey, merchantCardEndpointEncrypts, merchantCardEndpointFactsRefusal, merchantCardEndpointFactsRole, merchantCardEndpointLive, merchantCardEndpointMatches, merchantCardEndpointNavigationAnswer, merchantCardEndpointPasses, merchantCardEndpointRecognizerById, merchantCardEndpointRequestOrigin, merchantCardEndpointSessionRefusal, merchantCardEndpointSessionTtl, merchantEndpointRequest, nikeOrderHost, nikeOrderRefusal, nikeOrderRequest, projectMerchantCardEndpointFacts, readMerchantCardEndpointFacts, responseCardLeak, substituteMerchantCardEndpoint, trustedMerchantCardEndpoint };