@agent-cards/sdk 0.23.12 → 0.23.14

package/dist/pre-claim.d.ts

@@ -13,6 +13,8 @@ import { type CardEndpointProfile } from './card-endpoint.js';
 import { type PayrailsSessionCapture, type PayrailsSidecar } from './payrails.js';
 import { type VerifoneProfile } from './verifone.js';
 import { type WorldlineMyCheckoutProducts } from './worldline-mycheckout.js';
+import { type PaddleVgsPayGate } from './paddle-vgs-pay.js';
+import { type EbanxFollowUps } from './ebanx.js';
 /** The native Stripe step the gate claimed, or null when none was: exactly what StripeCheckoutGate.claim returns. */
 type StripeStep = ReturnType<StripeCheckoutGate['claim']>;
 /** A synthetic response a gate fulfills locally. The effect applies CORS and encoding. */
@@ -97,6 +99,20 @@ export interface PreClaimContext {
         verifoneProfileOf?(url: string): VerifoneProfile | null;
         cardOnFilePolicy?(url: string, method?: string): string | null;
         withoutCard?(url: string, body: string | null | undefined): 'continue' | 'refuse' | null;
+        /** VaultClient.sendEbanxFollowUp: a send an approved EBANX token request covers, from the cardholder's device. */
+        sendEbanxFollowUp?(authorizationId: string, request: {
+            url: string;
+            method: 'POST';
+            headers: Record<string, string>;
+            body: string;
+        }, options?: {
+            signal?: AbortSignal;
+            until?: number;
+        }): Promise<{
+            status: number;
+            headers: Record<string, string>;
+            body: string;
+        }>;
     };
     guards: {
         matches(url: string, method?: string): boolean;
@@ -116,11 +132,15 @@ export interface PreClaimContext {
     eprotect?: EprotectGate;
     readDocumentUrl: () => Promise<string>;
     lifecycle: CheckoutLifecycle;
-    /** isEngaged and observeUnprepared are called only for an armed merchant profile's card request or a Fiserv card capture. */
+    /**
+     * isEngaged and observeUnprepared are called only for an armed merchant profile's card request or a Fiserv card capture.
+     * creditguardStanding, only for a request on a CreditGuard PPS host (PreparationGate.creditguardStanding); absent reads as 'none'.
+     */
     preparationGate: {
         invalidate(reason: string): void;
         isEngaged(): boolean;
         observeUnprepared(): void;
+        creditguardStanding?(txId: string): 'none' | 'ready' | 'refuse';
     };
     effects: PreClaimEffects;
     onEvent?: (event: PreClaimEvent) => void;
@@ -189,6 +209,18 @@ export interface PreClaimContext {
      * Absent, no MyCheckout card submit is held to a product here.
      */
     worldlineMyCheckout?: WorldlineMyCheckoutProducts;
+    /**
+     * The attachment's binding of Paddle's /pay to the stored card's id it handed a frame (paddle-vgs-pay.ts),
+     * judged by the request's frame (`frame`). Absent, or for an org the API did not serve Paddle VGS to, Paddle's
+     * checkout services are not this gate's.
+     */
+    paddleVgsPay?: PaddleVgsPayGate;
+    /**
+     * The attachment's approved EBANX token request and the sends claimed under it (ebanx.ts EbanxFollowUps).
+     * Absent, or holding no approval whose read named a window, and every EBANX 3-D Secure call and card confirm
+     * is refused, as before the approval covered them.
+     */
+    ebanx?: EbanxFollowUps;
 }
 /**
  * The URL an event may name for a request. For an armed merchant profile's
@@ -207,10 +239,23 @@ export type PreClaimGate = (ctx: PreClaimContext) => PreClaimDecision | undefine
 export declare const MERCHANT_BODY_UNREADABLE = "the paused request carries no body the SDK could read, so Agentcard cannot tell whether it carries a card";
 export declare const verifonePreClaim: PreClaimGate;
 export declare const fiservPreClaim: PreClaimGate;
+/**
+ * Whether an adapter must hand this request to the pre-claim gates as a CreditGuard page's own call
+ * beside its submit: a companion endpoint (payment-core creditguardCompanionCall, as loosely as a
+ * request could spell one) while this build's registry serves CreditGuard. The CDP adapter pauses
+ * them already through the recognizer's host-wide URL patterns; attachToPlaywright's route predicate,
+ * which otherwise sees only the submit, asks this.
+ */
+export declare function isArmedCreditguardCall(vault: {
+    recognizesProcessor?(psp: string): boolean;
+} | undefined, url: string): boolean;
 export declare const ekashuPreClaim: PreClaimGate;
+export declare const redsysPreClaim: PreClaimGate;
 export declare const paypalHostedFieldsPreClaim: PreClaimGate;
 export declare const cybersourceSecureAcceptancePreClaim: PreClaimGate;
 export declare const worldlineMyCheckoutPreClaim: PreClaimGate;
+export declare const paddleVgsPayPreClaim: PreClaimGate;
+export declare const ebanxPreClaim: PreClaimGate;
 /** The processor gates, in order. A new family adds one entry here; the terminal
  * arbiter runs after all of them and is not part of this list. A gate appended
  * after Stripe is never offered a step Stripe claimed: Stripe answers, aborts or

package/dist/pre-claim.js

@@ -15,10 +15,12 @@
 // Converge's hpp/process URL, which also carries wallet, debit, follow-up and
 // card-saving bodies, WSPay's confirm URL, which also carries bodies with
 // no new card, Shiji STS's getTokenId and getCvvId, which also carry
-// requests the vault must never pay, and PayPal's legacy Hosted Fields
+// requests the vault must never pay, PayPal's legacy Hosted Fields
 // confirm and CyberSource Secure Acceptance's Silent Order POST, whose card
-// no Vault mode takes over, and Worldline MyCheckout's card form, held to the
-// card product its page chose.
+// no Vault mode takes over, Worldline MyCheckout's card form, held to the
+// card product its page chose, and EBANX's 3-D Secure calls and hosted confirm,
+// which send the card again after its token and leave only from the
+// cardholder's device, under the token request's approval.
 // The first three used to be
 // written inline in Fetch.requestPaused and again in the page.route handler, so
 // a decision could drift between the two adapters and a new family had to be
@@ -63,7 +65,7 @@ import { DATATRANS_INVALID_REQUEST } from './datatrans.generated.js';
 import { isPelecardHost, pelecardRefusal } from './pelecard.js';
 import { ACI_CHECKOUT_REUSED } from './aci.js';
 import { ACI_EXPIRY_UNSTRIPPABLE } from './aci.generated.js';
-import { CREDITGUARD_PPS_HOSTS, classifyCreditguardRequest, creditguardNuveiRefusal, creditguardProcessRefusal } from './creditguard.generated.js';
+import { CREDITGUARD_PPS_HOSTS, classifyCreditguardRequest, creditguardCompanionAnswer, creditguardCompanionCall, creditguardNuveiRefusal, creditguardProcessRefusal, creditguardProcessTxId, } from './creditguard.generated.js';
 import { isPrimerPciHost, primerRequestVerdict } from './primer.js';
 import { convergeRefusal, isConvergeHost } from './elavon-converge.js';
 import { isWspayHost, wspayRefusal } from './wspay.js';
@@ -76,9 +78,12 @@ import { cardEndpointStoppedPage, refusedNavigationOutcome } from './card-endpoi
 import { PAYRAILS_HOLDING_REASONS, PAYRAILS_SESSION_MESSAGE, isPayrailsHost, isPayrailsPaymentUrl, isPayrailsStaticHost, payrailsKeyRefusal, payrailsPaymentRefusal, payrailsRequestKind, payrailsSaveRefusal, } from './payrails.js';
 import { classifyVerifoneProfileRequest, verifoneTemplatedUrl } from './verifone.js';
 import { ekashuEntryUrl, isEkashuEntry, isEkashuHost } from './ekashu.js';
+import { isRedsysEntry, isRedsysHost, redsysEntryUrl } from './redsys.js';
 import { PAYPAL_HOSTED_FIELDS_REASON, isPaypalHostedFieldsConfirm, paypalHostedFieldsBody } from './paypal-hosted-fields.js';
 import { CYBERSOURCE_SECURE_ACCEPTANCE_REASON, CYBERSOURCE_SECURE_ACCEPTANCE_RECIPIENT, cybersourceSecureAcceptanceRequest, isCybersourceSecureAcceptanceUrl, isSecureAcceptanceFramePost, } from './cybersource-secure-acceptance.js';
 import { isWorldlineMyCheckoutEndpoint } from './worldline-mycheckout.js';
+import { paddleVgsPayEventUrl } from './paddle-vgs-pay.js';
+import { EBANX_RESEND_REASON, EbanxFollowUpError, ebanxResendRefusalOf, isEbanxResendUrl, } from './ebanx.js';
 /**
  * The URL an event may name for a request. For an armed merchant profile's
  * endpoint or a sibling of it: the endpoint origin, the path TEMPLATE and the
@@ -1057,18 +1062,31 @@ async function aciRefuse(ctx, code) {
     await ctx.effects.abort();
     return { kind: 'abort' };
 }
-// CreditGuard's hosted payment page (Hyp PPS), in two parts the generic card
+// CreditGuard's hosted payment page (Hyp PPS), in three parts the generic card
 // path cannot judge. Every other request on the PPS hosts (the page, its
-// transaction read, /card/details, /cg3ds, assets) and the stock new-card
-// submit defer, synchronously, and the terminal arbiter continues or pauses
-// them; the pause then needs a ready preparation for this page's transaction.
+// transaction read, assets) and the stock new-card submit defer, synchronously,
+// and the terminal arbiter continues or pauses them; the pause then needs a
+// ready preparation for this page's transaction.
+//   - The page's own calls beside the submit that carry the placeholder card:
+//     its /card/details lookup and, on a 3-D Secure transaction, /cc/ddc/init,
+//     /cg3ds/process/init and /cg3ds/process/outcome (payment-core
+//     creditguardCompanionCall). Under a ready preparation for this page's own
+//     transaction each is answered here, nothing sent: a foreign card, so the
+//     page asks the agent for no Israeli ID; no device check; no challenge; and
+//     an outcome that is not cancelled (creditguardCompanionAnswer). The page
+//     then sends its submit, and the cardholder's device runs CreditGuard's 3-D
+//     Secure with the real card before it sends its own. With no preparation
+//     asked for, each goes on to CreditGuard as it always has; under any other
+//     preparation, or in a shape the page does not send, it is aborted.
 //   - A /process submit the cardholder's device would not fill (a saved card,
 //     a wallet, "save my card", installments, DCC, an Israeli ID, a gift card,
 //     another method, an unreadable body or other headers) is aborted with the device's own
 //     reason, before any claim, create or prompt. A ready preparation stays
-//     ready, so the page's corrected submit can still pay.
-//   - PPS runs 3-D Secure itself, sending the placeholder card to Nuvei from
-//     inside its frame. The nuvei recognizer would pause that as a Nuvei
+//     ready, so the page's corrected submit can still pay. Under a ready
+//     preparation for its own transaction the encrypted submit (jwePayload)
+//     defers like the plaintext one; the API holds it to the transaction's key.
+//   - PPS runs Nuvei's 3-D Secure itself, sending the placeholder card to Nuvei
+//     from inside its frame. The nuvei recognizer would pause that as a Nuvei
 //     payment. A request to a Nuvei host that a PPS document sent, or that any
 //     frame inside a PPS document sent, is aborted instead, the checkout
 //     becomes unsupported and any preparation is retired: the page's flow is
@@ -1099,14 +1117,84 @@ const creditguardPreClaim = (ctx) => {
     // Any method reaches the /process check: payment-core blocks a non-POST, a query or an unreadable
     // body there as well, so nothing but the stock POST ever continues to CreditGuard.
     const verb = method.toUpperCase();
-    const verdict = classifyCreditguardRequest(url, verb, body ?? '', undefined);
+    const companion = creditguardCompanionCall(url, verb, body ?? '');
+    if (companion !== null)
+        return creditguardCompanionPreClaim(ctx, companion);
+    // The encrypted submit is the page's own only for a transaction that carries a key, which the API
+    // reads; here it may defer only under a ready preparation for its own transaction.
+    const txId = creditguardProcessTxId(url);
+    const options = txId !== null && creditguardStanding(ctx, txId) === 'ready' ? { jwe: true } : undefined;
+    const verdict = classifyCreditguardRequest(url, verb, body ?? '', options);
     if (verdict === null)
         return undefined;
-    const refusal = creditguardProcessRefusal({ url, method: verb, headers: ctx.request.headers, body: body ?? '' }, undefined);
+    const refusal = creditguardProcessRefusal({ url, method: verb, headers: ctx.request.headers, body: body ?? '' }, options);
     if (verdict === 'card' && refusal === null)
         return undefined;
     return creditguardBlock(ctx, refusal ?? 'malformed_body');
 };
+/**
+ * Whether an adapter must hand this request to the pre-claim gates as a CreditGuard page's own call
+ * beside its submit: a companion endpoint (payment-core creditguardCompanionCall, as loosely as a
+ * request could spell one) while this build's registry serves CreditGuard. The CDP adapter pauses
+ * them already through the recognizer's host-wide URL patterns; attachToPlaywright's route predicate,
+ * which otherwise sees only the submit, asks this.
+ */
+export function isArmedCreditguardCall(vault, url) {
+    if (typeof vault?.recognizesProcessor !== 'function' || !vault.recognizesProcessor('creditguard'))
+        return false;
+    try {
+        return creditguardCompanionCall(url, 'POST', '') !== null;
+    }
+    catch {
+        return false;
+    }
+}
+/** The preparation's standing for a CreditGuard transaction (PreparationGate.creditguardStanding); 'none' where the context has none. */
+function creditguardStanding(ctx, txId) {
+    try {
+        return ctx.preparationGate.creditguardStanding?.(txId) ?? 'none';
+    }
+    catch {
+        return 'refuse';
+    }
+}
+/**
+ * A CreditGuard page's own call beside its submit (see the comment above): with no preparation asked
+ * for it defers and goes on as before; under a ready preparation for its own transaction it is
+ * answered here when it is the page's own call, in its own microtask's decision, and refused when it
+ * is not; under any other preparation it is refused. A refused call never names a body field.
+ */
+function creditguardCompanionPreClaim(ctx, companion) {
+    let engaged = true;
+    try {
+        engaged = ctx.preparationGate.isEngaged();
+    }
+    catch {
+        engaged = true;
+    }
+    const standing = companion.txId !== null ? creditguardStanding(ctx, companion.txId) : engaged ? 'refuse' : 'none';
+    if (standing === 'none')
+        return undefined;
+    if (standing !== 'ready')
+        return creditguardBlock(ctx, 'preparation_mismatch');
+    if (companion.refusal !== null || companion.step === null)
+        return creditguardBlock(ctx, companion.refusal ?? 'not_companion_request');
+    return creditguardCompanionAnswered(ctx, companion.step);
+}
+async function creditguardCompanionAnswered(ctx, step) {
+    const answer = creditguardCompanionAnswer(step);
+    if (answer && !ctx.interceptionAborted() && !ctx.lifecycleAborted() && !ctx.terminal()) {
+        try {
+            await ctx.effects.answer(answer);
+            ctx.onEvent?.({ type: 'creditguard_call_answered', detail: { step } });
+            return { kind: 'answer' };
+        }
+        catch { /* the page's request is gone; nothing was forwarded */ }
+    }
+    ctx.onEvent?.({ type: 'blocked', detail: { reason: 'creditguard_call_unanswered', step } });
+    await ctx.effects.abort();
+    return { kind: 'abort' };
+}
 /**
  * Who sent a request to a Nuvei host, as far as it decides the request:
  *   1. The browser sets Origin and Referer, and no page can make either name another page's
@@ -1503,9 +1591,10 @@ export const ekashuPreClaim = (ctx) => {
         return undefined;
     if (isEkashuEntry(url, method))
         return undefined;
-    return ekashuAbort(ctx);
+    return processorPageAbort(ctx);
 };
-async function ekashuAbort(ctx) {
+// The stop for a card post into a processor's own page that only the cardholder's device may pay (NMI's, Redsys's).
+async function processorPageAbort(ctx) {
     const { url, method } = ctx.request;
     ctx.preparationGate.invalidate('unsupported_checkout');
     ctx.lifecycle.unsupported('processor_card_page');
@@ -1513,6 +1602,30 @@ async function ekashuAbort(ctx) {
     await ctx.effects.abort();
     return { kind: 'abort' };
 }
+// Redsys's hosted payment page (redsys.ts). Once this build's registry serves Redsys's entry (a
+// capability the API serves only to a company Agentcard turned Redsys on for), every request to
+// Redsys's hosts pauses, and this gate judges the POSTs:
+//   - the merchant's entry (/sis/realizarPago or its /utf-8 twin on sis.redsys.es) defers, and the
+//     terminal arbiter pauses it for the claim flow like any card request: the cardholder's device pays it;
+//   - every other POST to Redsys (the card page's own post, the older page's 3-D Secure card lookup,
+//     InSite's card post, and an entry on Redsys's test platform, which Agentcard pays nothing on and
+//     whose page asks for a card) aborts as an unsupported checkout, and Redsys never sees the card the
+//     agent typed. The agent's browser only reaches Redsys's card page when the entry was not paused (an
+//     attachment made too late, say), and then only the cardholder's device can pay.
+// A GET (the card page's scripts and images) is not this gate's and continues. With Redsys not served,
+// the entry is no card request, the gate defers, and every request continues as before. Synchronous
+// until it must abort, like every gate. Exported for the gate registry's tests.
+export const redsysPreClaim = (ctx) => {
+    const { url, method } = ctx.request;
+    if (String(method).toUpperCase() !== 'POST' || !isRedsysHost(url))
+        return undefined;
+    const entry = redsysEntryUrl(url);
+    if (!entry || !ctx.vault.isCardRequest(entry, 'POST'))
+        return undefined;
+    if (isRedsysEntry(url, method))
+        return undefined;
+    return processorPageAbort(ctx);
+};
 // PayPal's legacy Hosted Fields (paypal-hosted-fields.ts). Its tokenization frame posts the card the
 // agent typed to the Orders v2 confirm-payment-source on cors.api.paypal.com (or its sandbox), which
 // no Vault mode takes over, so every company's adapters hand each POST there to this gate:
@@ -1737,6 +1850,214 @@ async function worldlineMyCheckoutBlock(ctx, reason) {
     await ctx.effects.abort();
     return { kind: 'abort' };
 }
+// Paddle's /pay (paddle-vgs-pay.ts), held only on an attachment the API served Paddle VGS to: a POST to /pay
+// that names a stored card continues with the approved card's first six, last four, expiry and brand written
+// over the ones the frame read from the agent's placeholder, when this attachment handed that frame the stored
+// card's id within the minute and this is its first /pay; otherwise it aborts as an unsupported checkout, with
+// the gate's reason, so Paddle never receives the real card's id beside the placeholder's facts. Anything else
+// on Paddle's checkout services (its create, the buyer's first step, 3-D Secure's follow-up, a PayPal or wallet
+// /pay naming no stored card) defers, and the terminal arbiter continues it untouched. Synchronous until the
+// continue or the abort.
+export const paddleVgsPayPreClaim = (ctx) => {
+    const { url, method } = ctx.request;
+    if (!ctx.paddleVgsPay?.holds(url, method))
+        return undefined;
+    let body;
+    // A reader that throws (Playwright's postData() can) proves nothing: judged as a body that is not the frame's.
+    try {
+        body = ctx.request.body;
+    }
+    catch {
+        body = null;
+    }
+    const judged = ctx.paddleVgsPay.judge(ctx.frame, url, method, body);
+    if (judged === null)
+        return undefined;
+    return 'reason' in judged ? paddleVgsPayRefused(ctx, judged.reason) : paddleVgsPayContinued(ctx, judged.body);
+};
+async function paddleVgsPayRefused(ctx, reason) {
+    const { url, method } = ctx.request;
+    ctx.preparationGate.invalidate('unsupported_checkout');
+    ctx.lifecycle.unsupported(reason);
+    ctx.onEvent?.({ type: 'unsupported_checkout', detail: { url: paddleVgsPayEventUrl(url), method, reason } });
+    await ctx.effects.abort();
+    return { kind: 'abort' };
+}
+async function paddleVgsPayContinued(ctx, body) {
+    try {
+        await ctx.effects.continueRequest(body);
+    }
+    catch (error) {
+        ctx.onEvent?.({ type: 'failed', detail: ctx.failureSummary(error) });
+        await ctx.effects.abort().catch(() => { });
+        return { kind: 'abort' };
+    }
+    ctx.onEvent?.({ type: 'companion_continued', detail: { url: paddleVgsPayEventUrl(ctx.request.url), psp: 'paddle_vgs',
+            fields: ['card_first_six', 'card_last_four', 'expiry_month', 'expiry_year', 'card_brand'] } });
+    return { kind: 'continue' };
+}
+// EBANX after its card token (ebanx.ts, payment-core ebanx.js). Once the cardholder's device has sent the card to
+// /ws/token, EBANX's hosted payment page and EBANX.js send the card the page holds again: its 3-D Secure calls post
+// the card, and the hosted page's confirm posts its code beside EBANX's token. On a page this SDK is attached to that
+// card is the agent's placeholder, so every company's adapters hand each POST there to this gate:
+//   - one the approved token request on this attachment covers (EbanxFollowUps.claim) goes to the cardholder's
+//     device under that approval (ebanxFollowUp below), and the page receives EBANX's answer to the real card;
+//   - any other 3-D Secure call, or a confirm whose payment.card names a card code or number, aborts as an
+//     unsupported checkout, reason `unsupported_ebanx_card_resend`, with no claim, create or prompt, so EBANX never
+//     receives the placeholder as a card. The attachment then holds: the page's next try would send the placeholder
+//     again. A checkout whose token request was already approved keeps that approval's state (lifecycle.unsupported),
+//     and its follow-ups stop (EbanxFollowUps.stop): a later request the approval would cover is refused too, so the
+//     page cannot finish 3-D Secure and pay through the confirm after a refusal. A failed send stops them the same way.
+//     A send goes on only while the checkout itself names the remembered approval (ebanxMaySend): it awaits the
+//     merchant, reports the bank's challenge, or holds that approval's answer for the page (awaiting_approval while
+//     the token's answer is on its way, since the adapters remember the approval before they hand the answer over, or
+//     ready_to_submit while the approval waits for the page's retry). A new token request awaiting the person, a new
+//     attempt after a merchant failure (idle), another approval and every final merchant result refuse it, and
+//     nothing more reaches the device;
+//   - a confirm whose body the adapter could not read, an empty one, or one that is not a JSON object aborts that
+//     request alone with a `blocked` event, `unreadable_ebanx_request`, and does not hold the attachment;
+//   - any other request (a confirm for a bank transfer, cash or a wallet, -record) defers, and the arbiter continues
+//     it untouched.
+// A request the synced registry recognizes as a card request defers too, so the arbiter pauses it for that
+// recognizer; no build serves one today. A GET or a preflight is not this gate's. Synchronous until it must abort or
+// send, like every gate. Exported for the gate registry's tests.
+export const ebanxPreClaim = (ctx) => {
+    const { url, method } = ctx.request;
+    if (String(method).toUpperCase() !== 'POST' || !isEbanxResendUrl(url) || ctx.vault.isCardRequest(url, method))
+        return undefined;
+    const refusal = ebanxResendRefusalOf(url, 'POST', () => ctx.request.body);
+    if (refusal === null)
+        return undefined;
+    if (refusal === 'unreadable')
+        return ebanxUnreadable(ctx);
+    let body;
+    try {
+        body = ctx.request.body;
+    }
+    catch {
+        body = null;
+    }
+    const claim = ctx.ebanx && typeof ctx.vault.sendEbanxFollowUp === 'function' && ebanxMaySend(ctx)
+        ? ctx.ebanx.claim({ url, method: 'POST', headers: ctx.request.headers ?? {}, body }) : null;
+    return claim ? ebanxFollowUp(ctx, claim) : ebanxResendRefused(ctx, refusal);
+};
+/**
+ * The checkout states in which a send may go on under the remembered approval, an allowlist: the checkout awaits the
+ * merchant, the application reported the bank's challenge (requestUserAction), the token's answer is still on its way
+ * to the page (awaiting_approval: the page may send its first 3-D Secure call the moment the answer lands), or the
+ * approval waits for the page's retry (ready_to_submit). Every other state refuses, idle and the final ones among them.
+ */
+const EBANX_SENDING_STATES = new Set(['awaiting_merchant', 'requires_user_action', 'awaiting_approval', 'ready_to_submit']);
+/**
+ * Whether a send may go on: nothing aborted the checkout, no reconciliation of the merchant's order is running (one
+ * that resolves failed while a confirm is out would let the application start another attempt), it is in one of
+ * EBANX_SENDING_STATES, and its state names the approval the attachment remembered. A new token request awaiting the
+ * person (awaiting_approval with no approval, or another one), a new attempt after a merchant failure, a prepared
+ * checkout and another approval's state all refuse.
+ */
+function ebanxMaySend(ctx) {
+    if (ctx.lifecycleAborted() || ctx.terminal() || !ctx.ebanx || ctx.lifecycle.isReconciling())
+        return false;
+    const approval = ctx.ebanx.authorizationId;
+    const state = ctx.lifecycle.getState();
+    return approval !== null && EBANX_SENDING_STATES.has(state.status) && state.authorizationId === approval;
+}
+/**
+ * The checkout's final merchant results: completed, failed, declined, timed out, cancelled, an unknown outcome, or an
+ * unsupported request. A 3-D Secure call, which charges nothing, that fails in one of them leaves that outcome alone.
+ */
+const EBANX_FINAL_STATES = new Set(['completed', 'failed', 'declined', 'timed_out', 'cancelled', 'outcome_unknown', 'unsupported']);
+/** Whether the checkout already ended (EBANX_FINAL_STATES): its state and reason stand, whatever a later 3-D Secure call does. */
+const ebanxCheckoutEnded = (ctx) => EBANX_FINAL_STATES.has(ctx.lifecycle.getState().status);
+/**
+ * A confirm whose card may have reached EBANX and whose answer the page never got: only a payment the merchant
+ * already confirmed (completed) stands, and every other state of this approval turns unknown, since EBANX may have
+ * taken the payment. No other attempt can start while the send is out (both adapters refuse a new card request then,
+ * CheckoutLifecycle.followUpsInFlight), so the state names this approval; one that names another is left alone.
+ */
+function ebanxConfirmUnconfirmed(ctx, authorizationId, reason) {
+    const state = ctx.lifecycle.getState();
+    if (state.status !== 'completed' && state.authorizationId === authorizationId) {
+        ctx.lifecycle.failed(new PaymentOutcomeUnknownError(authorizationId, reason), true);
+    }
+}
+async function ebanxResendRefused(ctx, refusal) {
+    const { url, method } = ctx.request;
+    ctx.preparationGate.invalidate('unsupported_checkout');
+    ctx.ebanx?.stop();
+    ctx.lifecycle.unsupported(EBANX_RESEND_REASON);
+    ctx.onEvent?.({ type: 'unsupported_checkout', detail: { url: eventUrl(ctx.vault, url), method, reason: EBANX_RESEND_REASON,
+            step: refusal === 'three_ds_card' ? 'three_d_secure' : 'confirm' } });
+    await ctx.effects.abort();
+    return { kind: 'abort' };
+}
+async function ebanxUnreadable(ctx) {
+    ctx.onEvent?.({ type: 'blocked', detail: 'unreadable_ebanx_request' });
+    await ctx.effects.abort();
+    return { kind: 'abort' };
+}
+/**
+ * A send the approved token request covers: the cardholder's device sends it with the real card
+ * (VaultClient.sendEbanxFollowUp), and the page receives EBANX's answer, with no second prompt. The events name the
+ * approval and the step, never the request, the card or EBANX's answer. When no answer comes back:
+ *   - a confirm the card may have reached EBANX with ends `outcome_unknown` (ebanx_confirm_unconfirmed): EBANX may
+ *     have charged it, and only the merchant's order can say;
+ *   - anything else (a 3-D Secure call, which charges nothing, or a send that never left the device) holds the
+ *     attachment as the refusal above does, and the page shows EBANX's own payment error.
+ * Either way the page's request fails, so it never waits on a send nobody will answer. A send runs outside the
+ * card-request lifecycle, so it counts as work in flight from its claim until the page has its answer or it failed
+ * (CheckoutLifecycle.followUpStarted): meanwhile reconcile() and retryAfterMerchantFailure() throw, so the application
+ * starts no other attempt while a confirm may pay. A confirm that may have left keeps only a payment the merchant
+ * confirmed (completed); any other state of its approval turns unknown (ebanxConfirmUnconfirmed). Any other send keeps
+ * a final outcome (EBANX_FINAL_STATES) with its reason.
+ */
+async function ebanxFollowUp(ctx, claim) {
+    const settle = ctx.lifecycle.followUpStarted();
+    try {
+        return await sendEbanxFollowUp(ctx, claim);
+    }
+    finally {
+        settle();
+    }
+}
+async function sendEbanxFollowUp(ctx, claim) {
+    const detail = { authorizationId: claim.authorizationId, step: claim.kind };
+    ctx.onEvent?.({ type: 'ebanx_follow_up_requested', detail });
+    let answer;
+    try {
+        answer = await ctx.vault.sendEbanxFollowUp(claim.authorizationId, claim.request, { signal: ctx.lifecycle.abort.signal, until: claim.until });
+    }
+    catch (error) {
+        claim.settle(null);
+        ctx.ebanx?.stop();
+        const reason = error instanceof EbanxFollowUpError ? error.reason : 'follow_up_unavailable';
+        const cardSent = error instanceof EbanxFollowUpError ? error.cardSent : true;
+        ctx.onEvent?.({ type: 'ebanx_follow_up_failed', detail: { ...detail, reason, cardSent } });
+        if (cardSent && claim.kind === 'confirm')
+            ebanxConfirmUnconfirmed(ctx, claim.authorizationId, 'ebanx_confirm_unconfirmed');
+        else if (!ebanxCheckoutEnded(ctx))
+            ctx.lifecycle.unsupported(EBANX_RESEND_REASON);
+        await ctx.effects.abort();
+        return { kind: 'abort' };
+    }
+    claim.settle({ status: answer.status, text: answer.body });
+    try {
+        await ctx.effects.answer({ status: answer.status, headers: answer.headers, body: answer.body });
+    }
+    catch {
+        // EBANX answered the device and the page never received it: a confirm's charge is the merchant's to confirm.
+        ctx.ebanx?.stop();
+        ctx.onEvent?.({ type: 'ebanx_follow_up_failed', detail: { ...detail, reason: 'handoff_failed', cardSent: true } });
+        if (claim.kind === 'confirm')
+            ebanxConfirmUnconfirmed(ctx, claim.authorizationId, 'ebanx_follow_up_handoff_failed');
+        else if (!ebanxCheckoutEnded(ctx))
+            ctx.lifecycle.unsupported(EBANX_RESEND_REASON);
+        await ctx.effects.abort();
+        return { kind: 'abort' };
+    }
+    ctx.onEvent?.({ type: 'ebanx_follow_up_answered', detail: { ...detail, status: answer.status } });
+    return { kind: 'answer' };
+}
 // The terminal arbiter, always last. A request that no gate claimed and that is
 // neither a native Stripe step nor a recognized card request continues, unless
 // it matches a declared payment endpoint we do not support (then it aborts as an
@@ -1770,8 +2091,8 @@ async function unsupportedContinue(ctx) {
  * arbiter runs after all of them and is not part of this list. A gate appended
  * after Stripe is never offered a step Stripe claimed: Stripe answers, aborts or
  * pauses each one itself. */
-export const PSP_PRE_CLAIM_GATES = [cardEndpointResendPreClaim, cardEndpointPreClaim, mercadoPreClaim, juspayPreClaim, braintreePreClaim, stripePreClaim, merchantHostedPreClaim, verifonePreClaim, fiservPreClaim, gmoPreClaim, cybersourceFlexPreClaim, datatransPreClaim, pelecardPreClaim, aciPreClaim, creditguardPreClaim, primerPreClaim, payrailsPreClaim, convergePreClaim, eprotectPreClaim, wspayPreClaim, shijiStsPreClaim, ekashuPreClaim, paypalHostedFieldsPreClaim,
-    cybersourceSecureAcceptancePreClaim, worldlineMyCheckoutPreClaim];
+export const PSP_PRE_CLAIM_GATES = [cardEndpointResendPreClaim, cardEndpointPreClaim, mercadoPreClaim, juspayPreClaim, braintreePreClaim, stripePreClaim, merchantHostedPreClaim, verifonePreClaim, fiservPreClaim, gmoPreClaim, cybersourceFlexPreClaim, datatransPreClaim, pelecardPreClaim, aciPreClaim, creditguardPreClaim, primerPreClaim, payrailsPreClaim, convergePreClaim, eprotectPreClaim, wspayPreClaim, shijiStsPreClaim, ekashuPreClaim, redsysPreClaim, paypalHostedFieldsPreClaim,
+    cybersourceSecureAcceptancePreClaim, worldlineMyCheckoutPreClaim, paddleVgsPayPreClaim, ebanxPreClaim];
 /** Run each gate in order; the first to return a decision wins. If none does,
  * the terminal arbiter decides between continue, abort (unsupported) and pause.
  * Returns synchronously while every gate defers synchronously (an ordinary card

package/dist/preparation.d.ts

@@ -28,6 +28,19 @@ export declare class PreparationGate {
     assertDocument(): Promise<void>;
     private readDocument;
     isEngaged(): boolean;
+    /**
+     * Where a CreditGuard hosted page's own call beside its submit (its card lookup, its 3-D Secure
+     * calls: pre-claim.ts creditguardCompanionPreClaim) stands against this attachment's one
+     * preparation, which it never claims:
+     *   'none'    no preparation was asked for, so the call goes on as it did before the lane held any;
+     *   'ready'   a ready CreditGuard preparation, still inside its window, framed the page of this very
+     *             transaction: the SDK answers the call itself and the placeholder goes nowhere, and the
+     *             same preparation admits the page's encrypted submit (jwePayload) for the claim to bind;
+     *   'refuse'  anything else (a preparation still being made, spent, failed or expired, or one for
+     *             another processor or transaction): the call is refused, so the placeholder never
+     *             reaches CreditGuard on a page the cardholder did not approve.
+     */
+    creditguardStanding(txId: string): 'none' | 'ready' | 'refuse';
     /** Whether the one preparation was bound to a card request (claim() took it). */
     isConsumed(): boolean;
     /**

package/dist/preparation.js

@@ -2,6 +2,7 @@ import { CheckoutPreparationError } from './client.js';
 import { amountRefusal, validAmountInput } from './client.js';
 import { matchesPreparation, validPreparationEnvironment, preparationEndpoint, preparationBindsByShape, preparationRequestMethod, preparedRequestRefusal } from './prepared-processor.js';
 import { SECURE_ACCEPTANCE_PSP, secureAcceptanceCheckoutProfile } from './cybersource-secure-acceptance.js';
+import { creditguardPageProcessUrl, creditguardProcessTxId } from './creditguard.generated.js';
 /** A local, one-use rendezvous. It never starts or retries a merchant request. */
 export class PreparationGate {
     opts;
@@ -216,6 +217,27 @@ export class PreparationGate {
         }
     }
     isEngaged() { return this.state !== 'unused'; }
+    /**
+     * Where a CreditGuard hosted page's own call beside its submit (its card lookup, its 3-D Secure
+     * calls: pre-claim.ts creditguardCompanionPreClaim) stands against this attachment's one
+     * preparation, which it never claims:
+     *   'none'    no preparation was asked for, so the call goes on as it did before the lane held any;
+     *   'ready'   a ready CreditGuard preparation, still inside its window, framed the page of this very
+     *             transaction: the SDK answers the call itself and the placeholder goes nowhere, and the
+     *             same preparation admits the page's encrypted submit (jwePayload) for the claim to bind;
+     *   'refuse'  anything else (a preparation still being made, spent, failed or expired, or one for
+     *             another processor or transaction): the call is refused, so the placeholder never
+     *             reaches CreditGuard on a page the cardholder did not approve.
+     */
+    creditguardStanding(txId) {
+        if (this.state === 'unused')
+            return 'none';
+        const prepared = this.prepared;
+        if (this.state !== 'ready' || !prepared || prepared.psp !== 'creditguard' || !(Date.parse(prepared.expiresAt) > Date.now()))
+            return 'refuse';
+        const processUrl = typeof prepared.paymentPageUrl === 'string' ? creditguardPageProcessUrl(prepared.paymentPageUrl) : null;
+        return processUrl !== null && creditguardProcessTxId(processUrl) === txId ? 'ready' : 'refuse';
+    }
     /** Whether the one preparation was bound to a card request (claim() took it). */
     isConsumed() { return this.state === 'consumed'; }
     /**

package/dist/prepared-processor.js

@@ -177,7 +177,11 @@ function freshCardBody(psp, body) {
  * preparation's, the submit is the /process URL of the page the preparation read, on that page's
  * own host and for its txId, and the request is the page's own new-card submit exactly as the
  * device will judge it, with ppDomain bound to the approved merchant page. A saved card, a wallet,
- * a refused flag, another transaction or another PPS host never spends consent.
+ * a refused flag, another transaction or another PPS host never spends consent. The encrypted
+ * variant (jwePayload) is the page's own submit when the transaction carries a key, so it binds
+ * too: the API's create reads the transaction and holds the body to it (a jwePayload only under a
+ * key, and only while the API admits the encrypted card), and the device seals the approved card
+ * under the key the API's own read hands it.
  */
 function matchesPreparedCreditguard(environment, requestUrl, body, headers, binding) {
     let hostname = '', merchantHost = '';
@@ -194,7 +198,7 @@ function matchesPreparedCreditguard(environment, requestUrl, body, headers, bind
     const txId = creditguardProcessTxId(requestUrl);
     if (page === null || txId === null || page !== requestUrl)
         return false;
-    return creditguardProcessRefusal({ url: requestUrl, method: 'POST', headers, body: body ?? '' }, { merchantHost }) === null;
+    return creditguardProcessRefusal({ url: requestUrl, method: 'POST', headers, body: body ?? '' }, { merchantHost, jwe: true }) === null;
 }
 /**
  * The approved merchant page's host, with its port if it has one: what the Amadeus SDK sends in its