@agent-cards/sdk 0.23.13 → 0.23.14

package/dist/paddle-tokenex.js

@@ -0,0 +1,95 @@
+// Paddle TokenEx, the card leg of a Paddle checkout whose frame names the tokenization provider "tokenex",
+// as the SDK sees it (payment-core paddle-tokenex.js has the request's shape, the device encryption and the
+// substitution). Paddle's frame RSA-encrypts the card number and the CVV in the page itself, each on its
+// own, under the account-level TokenEx public key the checkout serves, and carries both inside one request:
+//   POST https://checkout-service.paddle.com/checkout/<id>/pay            (Paddle Classic)
+//   POST https://checkout-service.paddle.com/transaction-checkout/<id>/pay (Paddle Billing)
+// (sandbox-checkout-service.paddle.com in test). The agent's page encrypts a placeholder card, so the /pay
+// names the placeholder's ciphertexts and the placeholder's first six, last four, expiry and brand. This
+// build holds that /pay and writes over them the approved card's own: the two ciphertexts the cardholder's
+// device produced under the key payment-core pins (never a key from a row, a request or a page) and the
+// five metadata facts the device read from the real card. Every other byte goes as the frame wrote it
+// (mode cse), so the full card number never reaches the agent's runtime.
+//
+// The generic Adyen swap writes only the named ciphertext path, not the five metadata facts a sibling of
+// tokenex_card, so this lane is dispatched by psp to substitutePaddleTokenex instead, exactly as Shiji STS
+// is dispatched for its own body root. A production checkout-service refuses the Vault's cross-origin /pay
+// (403 at Cloudflare), so the device cannot send /pay itself and the lane rides in the agent's page.
+//
+// The registry entry ships dark (capability paddle_tokenex_pay). This build declares the capability on
+// syncRegistry, and the API serves the recognizer only to an org Agentcard enabled for paddle_tokenex, so
+// for every other org nothing here fires: isCardRequest never recognizes a TokenEx /pay and Paddle's
+// requests go through untouched. Autopilot never pays this processor: the API, the authority and the
+// enclave refuse it.
+import { PADDLE_TOKENEX_FIELDS, PADDLE_TOKENEX_FACT_KEYS, paddleTokenexPayTarget, substitutePaddleTokenex } from './paddle-tokenex.generated.js';
+/** The PSP id the API and the recognizer name this lane, re-exported so the client dispatches by it. */
+export { PADDLE_TOKENEX_PSP } from './paddle-tokenex.generated.js';
+/** The dark-launch capability a build declares when it fills a Paddle TokenEx /pay with the device's card. */
+export const PADDLE_TOKENEX_CAPABILITY = 'paddle_tokenex_pay';
+/** The holder the two ciphertexts are served at (the frame's tokenex_card), named once so both checks share it. */
+const SERVED_AT = 'data.payment_method_data.card.tokenex_card';
+const CIPHERTEXT_FIELDS = PADDLE_TOKENEX_FIELDS;
+const FACT_KEYS = PADDLE_TOKENEX_FACT_KEYS;
+const STRING_FACTS = ['card_first_six', 'card_last_four', 'card_brand'];
+const NUMBER_FACTS = ['expiry_month', 'expiry_year'];
+/**
+ * Whether an approved Paddle TokenEx authorization's served substitution is one this SDK can continue: JSON
+ * at the frame's tokenex_card holder, no sibling to remove, and exactly the two ciphertext fields, each a
+ * non-empty string and distinct from the other. substitutePaddleTokenex checks each against the pinned key
+ * for the /pay's environment; this is the shape gate the client runs before it acts.
+ */
+export function isPaddleTokenexServedSubstitution(sub) {
+    if (!sub || typeof sub !== 'object' || Array.isArray(sub))
+        return false;
+    const { encoding, at, fields, remove } = sub;
+    if (encoding !== 'json' || at !== SERVED_AT || !fields || typeof fields !== 'object' || Array.isArray(fields))
+        return false;
+    if (remove !== undefined && !(Array.isArray(remove) && remove.length === 0))
+        return false;
+    const named = fields;
+    const names = Object.keys(named);
+    if (names.length !== CIPHERTEXT_FIELDS.length || !CIPHERTEXT_FIELDS.every((name) => typeof named[name] === 'string' && named[name].length > 0))
+        return false;
+    return named.encrypted_card_number !== named.encrypted_cvv;
+}
+/**
+ * Whether the API's `paddle_tokenex_facts` beside an approved set is the five facts this SDK can write over
+ * the placeholder's: exactly the five keys, the three strings as strings and the two expiry parts as
+ * numbers. paddleTokenexSubstitutionOf checks the digits, range and network at the swap; this is the shape
+ * gate the client runs before it acts, so a malformed approval is refused before anything is written.
+ */
+export function isPaddleTokenexServedFacts(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const named = value;
+    const names = Object.keys(named);
+    if (names.length !== FACT_KEYS.length || !FACT_KEYS.every((name) => name in named))
+        return false;
+    return STRING_FACTS.every((name) => typeof named[name] === 'string' && named[name].length > 0)
+        && NUMBER_FACTS.every((name) => typeof named[name] === 'number' && Number.isInteger(named[name]));
+}
+/**
+ * The continuation of an approved Paddle TokenEx /pay: the paused body with the device's two ciphertexts
+ * written over the placeholder's at tokenex_card and the five facts over the placeholder's at metadata
+ * (payment-core substitutePaddleTokenex, which refuses a ciphertext that is not one under the pinned key
+ * for the /pay's environment, or one already in the paused body).
+ *
+ * Only into `approved`, the paused /pay the approval was created from: `url` and `body` must equal it byte
+ * for byte. The account-level TokenEx key is the same for every checkout of that seller, so the device's
+ * ciphertext could be decrypted in any later /pay of the same shape; binding it to the one request keeps
+ * this lane from ever submitting one checkout's ciphertext to another.
+ *
+ * Null when neither URL is a TokenEx /pay, so every other processor keeps the generic swap. Throws for any
+ * other body or URL, and for a substitution or facts the shape gates refuse, in each case before anything
+ * continues.
+ */
+export function paddleTokenexTokenContinuation(url, body, sub, facts, approved) {
+    if (paddleTokenexPayTarget(url) === null && paddleTokenexPayTarget(approved.url) === null)
+        return null;
+    if (url !== approved.url || body !== approved.body)
+        throw new Error('Refusing to substitute: the paused request is not the Paddle TokenEx /pay the cardholder approved.');
+    if (!isPaddleTokenexServedSubstitution(sub) || !isPaddleTokenexServedFacts(facts))
+        throw new Error('Refusing to substitute: the Paddle TokenEx approval is not two ciphertexts and five card facts.');
+    const substitution = { encrypted_card_number: sub.fields.encrypted_card_number, encrypted_cvv: sub.fields.encrypted_cvv, ...facts };
+    return { body: substitutePaddleTokenex(url, body, substitution) };
+}

package/dist/pre-claim.d.ts

@@ -14,6 +14,7 @@ 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. */
@@ -98,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;
@@ -117,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;
@@ -196,6 +215,12 @@ export interface PreClaimContext {
      * 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
@@ -214,11 +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,10 +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
@@ -1058,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
@@ -1100,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
@@ -1504,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');
@@ -1514,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:
@@ -1784,6 +1896,168 @@ async function paddleVgsPayContinued(ctx, body) {
             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
@@ -1817,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, paddleVgsPayPreClaim];
+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'; }
     /**