@agent-cards/sdk 0.23.10 → 0.23.12

package/dist/client.js

@@ -14,6 +14,7 @@ import { creditguardPageProcessUrl, creditguardPpDomainHost, creditguardPreparat
 import { CONVERGE_CAPABILITY } from './elavon-converge.js';
 import { SHIJI_STS_CAPABILITY, SHIJI_STS_PSP, isShijiStsServedCompanion, isShijiStsServedSubstitution } from './shiji-sts.js';
 import { AMADEUS_CHECKOUT_CAPABILITY, AMADEUS_CHECKOUT_PSP } from './amadeus-checkout.generated.js';
+import { PADDLE_VGS_CAPABILITY, PADDLE_VGS_PSP } from './paddle-vgs.generated.js';
 import { classifyStripeCheckoutRequest, encodeStripeCheckoutContext, hasStripeCheckoutMarker, parseStripeCheckoutContext, parseStripeCheckoutResponse, STRIPE_CHECKOUT_CONTEXT_HEADER, } from './stripe-checkout.generated.js';
 import { VoiceModule } from './voice.js';
 import { BuyModule } from './buy.js';
@@ -185,8 +186,16 @@ export const SUPPORTED_REGISTRY_FEATURES = ['card_fields', 'checkout_sessions'];
  * the same terms: only to a build that lists it, for a company Agentcard turned
  * Moneris on for. A gated recognizer never sits in BUILTIN_REGISTRY, so it is paused
  * only after a sync.
+ *
+ * `paddle_vgs_cards`: the card request Paddle's checkout frame sends to its VGS card
+ * vault (vault.paddle.com/cards) on a checkout that names VGS, only through a prepared
+ * checkout: the frame aborts the request 10 seconds after Pay and sends it once more,
+ * and this build answers that second request from the same approval. The cardholder's
+ * device sends the card itself and the frame gets back the stored card's id alone.
+ * Served on the same terms: only to a build that lists it, for a company Agentcard
+ * turned Paddle on for.
  */
-export const SUPPORTED_CAPABILITIES = ['fiserv_card_capture', GMO_CAPABILITY, CYBERSOURCE_FLEX_CAPABILITY, JUSPAY_CAPABILITY, DATATRANS_CAPABILITY, 'authorize_net_dpm_form', PELECARD_CAPABILITY, ACI_CAPABILITY, 'creditguard_pps_process', PRIMER_CAPABILITY, PAYRAILS_CAPABILITY, CONVERGE_CAPABILITY, EPROTECT_CAPABILITY, WSPAY_CAPABILITY, SHIJI_STS_CAPABILITY, AMADEUS_CHECKOUT_CAPABILITY, 'worldline_mycheckout_form', 'verifone_card_capture', 'ekashu_hosted_payment_page', SECURE_ACCEPTANCE_CAPABILITY, 'gravy_session_fields_put', 'moneris_hosted_tokenization'];
+export const SUPPORTED_CAPABILITIES = ['fiserv_card_capture', GMO_CAPABILITY, CYBERSOURCE_FLEX_CAPABILITY, JUSPAY_CAPABILITY, DATATRANS_CAPABILITY, 'authorize_net_dpm_form', PELECARD_CAPABILITY, ACI_CAPABILITY, 'creditguard_pps_process', PRIMER_CAPABILITY, PAYRAILS_CAPABILITY, CONVERGE_CAPABILITY, EPROTECT_CAPABILITY, WSPAY_CAPABILITY, SHIJI_STS_CAPABILITY, AMADEUS_CHECKOUT_CAPABILITY, 'worldline_mycheckout_form', 'verifone_card_capture', 'ekashu_hosted_payment_page', SECURE_ACCEPTANCE_CAPABILITY, 'gravy_session_fields_put', 'moneris_hosted_tokenization', PADDLE_VGS_CAPABILITY];
 /**
  * Processors whose paused request names no amount at all, so the pair the
  * agent passes is the amount the cardholder approves: authorize() refuses one
@@ -207,13 +216,15 @@ export const SUPPORTED_CAPABILITIES = ['fiserv_card_capture', GMO_CAPABILITY, CY
  * no more than that (the API's card rule). Moneris Hosted Tokenization's
  * request.php carries the card and no price: the merchant's server charges the
  * token later, so the agent's pair, above zero (MONERIS_PSP below), is the one
- * figure the approval shows.
+ * figure the approval shows. Paddle VGS's card request carries none either: Paddle
+ * charges the stored card at /pay for what the checkout says, so the agent's pair,
+ * which the prepared checkout carries, is the total the cardholder approves.
  */
 const MONERIS_PSP = 'moneris';
-const AGENT_AMOUNT_PROCESSORS = [GMO_PSP, PELECARD_PSP, WSPAY_PSP, SECURE_ACCEPTANCE_PSP, MONERIS_PSP];
+const AGENT_AMOUNT_PROCESSORS = [GMO_PSP, PELECARD_PSP, WSPAY_PSP, SECURE_ACCEPTANCE_PSP, MONERIS_PSP, PADDLE_VGS_PSP];
 /** How AmountRequiredError names a processor. */
 const PROCESSOR_NAMES = { [GMO_PSP]: 'GMO', [PELECARD_PSP]: 'Pelecard', [WSPAY_PSP]: 'WSPay',
-    [SECURE_ACCEPTANCE_PSP]: 'CyberSource Secure Acceptance', [MONERIS_PSP]: 'Moneris' };
+    [SECURE_ACCEPTANCE_PSP]: 'CyberSource Secure Acceptance', [MONERIS_PSP]: 'Moneris', [PADDLE_VGS_PSP]: 'Paddle' };
 /**
  * Processors whose request and answer name no amount at all, so the total the
  * payment page shows (`pageAmount`) is the one figure that ties the agent's pair
@@ -423,6 +434,35 @@ const PLACEHOLDER_NUMBERS = Object.freeze({
     discover: '6011000990139424',
     jcb: '3566111111111113',
 });
+/**
+ * The placeholder number a processor needs in place of its network's default above, by processor
+ * (the recognizer's `psp`) and network. A processor whose page reads the typed number's IIN to
+ * pick a card product can read the default as another product than the card that pays:
+ * Worldline MyCheckout read 4111111111111111 as Visa Electron (122), not Visa (1), on CLZ's live
+ * page on 2026-10-12, and switched its form's product. The SDK refuses that submit
+ * (worldline-mycheckout.ts), so until this table names a Visa number Worldline reads as product 1,
+ * a Visa card cannot pay on a MyCheckout page that offers Visa Electron. The default table stays
+ * as it is: CyberSource Flex's Microform rule, ACI's brand check and EBANX's eligibility guard
+ * read its Visa and Mastercard numbers.
+ *
+ * TODO(Felipe): pick worldline_mycheckout's Visa number from Worldline Connect's own test-card
+ * list, then confirm it with one production IIN check on a MyCheckout card form that offers
+ * products 1 and 122: type it, wait for the IIN answer, read paymentProductId and the logo, clear
+ * the field, never Pay. Add it here as `worldline_mycheckout: { visa: '<number>' }`, with the
+ * check's date and merchant, and to the live runner's placeholder allowlist.
+ */
+const PROCESSOR_PLACEHOLDER_NUMBERS = Object.freeze({});
+/**
+ * The placeholder number for a network (lowercase, as GET /api/v2/vault_cards names it) on a
+ * processor's page: the processor's own number for that network when `overrides` names one, else
+ * the network's default, else undefined for a network with no placeholder.
+ */
+export function placeholderNumber(brand, psp, overrides = PROCESSOR_PLACEHOLDER_NUMBERS) {
+    const own = psp !== undefined && Object.prototype.hasOwnProperty.call(overrides, psp) ? overrides[psp] : undefined;
+    if (own && Object.prototype.hasOwnProperty.call(own, brand))
+        return own[brand];
+    return Object.prototype.hasOwnProperty.call(PLACEHOLDER_NUMBERS, brand) ? PLACEHOLDER_NUMBERS[brand] : undefined;
+}
 /**
  * The recognizer says this processor is preparation-required, and no preparation
  * was passed. Its card may be sent only after the cardholder approved a
@@ -920,6 +960,71 @@ function maskCreditguardTxId(path) {
 const PATH_SECRET_HOSTS = ['proxy.wspay.biz', 'proxy-test.wspay.biz', 'ipg.monri.com', 'ipgtest.monri.com'];
 /** The segment after a `payment` segment, in any case (the WSPay proxy is IIS) or after an escaped slash. */
 const PATH_SECRET = /(\/payment(?:\/|%2f))[^/]*/gi;
+/**
+ * Gravy (Gr4vy) gives every merchant hosts of its own under gr4vy.app, and Secure Fields sends the
+ * card to /checkout/sessions/<session id>/fields with no auth header, so the session id is that
+ * request's only credential (payment-core definitions.js): with it anyone can write card fields
+ * into the session until it expires. On those hosts the segment after /checkout/sessions/, in any
+ * case or after an escaped slash, reads {session}, as does any other id shaped like Gravy's UUID
+ * session ids.
+ */
+const GRAVY_HOST = /(?:^|\.)gr4vy\.app\.?$/i;
+const GRAVY_SESSION = /(\/checkout\/sessions(?:\/|%2f))[^/]*/gi;
+const GRAVY_SESSION_ID = /[0-9a-f]{8}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{12}/gi;
+function maskGravySession(path) {
+    return path.replace(GRAVY_SESSION, '$1{session}').replace(GRAVY_SESSION_ID, '{session}');
+}
+/**
+ * Rapyd's hosted pages send the card to api.rapyd.net (sandboxapi.rapyd.net in test) with no auth
+ * header: the page's own id in the path, checkout_<id> for a checkout page and hp_card_<id> for a
+ * card page, is the request's only credential (payment-core definitions.js), and with it anyone can
+ * read that page and post a card to it until it expires. On Rapyd's hosts every id of those shapes
+ * (hp_reuse_<id>, a payment link's, too) and the segment after /hosted/collect/card/, in any case or
+ * after an escaped slash, read {token}.
+ */
+const RAPYD_HOST = /(?:^|\.)rapyd\.net\.?$/i;
+const RAPYD_CARD_PAGE = /(\/hosted\/collect\/card(?:\/|%2f))[^/]*/gi;
+const RAPYD_PAGE_ID = /(?:checkout|hp_[a-z]+)_[a-z0-9]+/gi;
+function maskRapydToken(path) {
+    return path.replace(RAPYD_CARD_PAGE, '$1{token}').replace(RAPYD_PAGE_ID, '{token}');
+}
+/**
+ * Stripe Checkout's pages confirm a Checkout Session at /v1/payment_pages/<session id>/confirm on
+ * api.stripe.com with the merchant's publishable key, which is public, so the session id is what
+ * lets anyone confirm a payment on that checkout until it expires. There the segment after
+ * /payment_pages/, in any case or after an escaped slash, reads {session}. A PaymentIntent or
+ * SetupIntent id stays: confirming one also needs its client_secret, which rides in the body.
+ */
+const STRIPE_API_HOST = /^api\.stripe\.com\.?$/i;
+const STRIPE_PAYMENT_PAGE = /(\/payment_pages(?:\/|%2f))[^/]*/gi;
+function maskStripeSession(path) {
+    return path.replace(STRIPE_PAYMENT_PAGE, '$1{session}');
+}
+/**
+ * redactAciCheckoutId (aci.ts) takes the checkout id out of the paths ACI's widget sends. This rule
+ * takes any other copy of it out on ACI's hosts: a trailing dot on the host, an escaped or doubled
+ * slash, another case, a string that is not a URL. The segment after /v1/checkouts/ and any id of
+ * ACI's shape (<32 hex>.<cluster>-vm-tx<nn>) read {checkoutId}.
+ */
+const ACI_HOST = /^(?:eu-prod\.|eu-test\.|test\.)?oppwa\.com\.?$/i;
+const ACI_CHECKOUT = /(\/v1\/checkouts(?:\/|%2f))[^/]*/gi;
+const ACI_CHECKOUT_ID = /[0-9a-f]{32}\.[a-z0-9]{1,16}-vm-tx[0-9]{1,3}/gi;
+function maskAciCheckout(path) {
+    return path.replace(ACI_CHECKOUT, '$1{checkoutId}').replace(ACI_CHECKOUT_ID, '{checkoutId}');
+}
+/**
+ * The processors whose card request carries its own credential in the URL path, with the hosts
+ * that send it, the text that names those hosts in a string that is not a URL, and the mask. The
+ * guard in redact-url.test.mjs fails for a payment-core recognizer that no one has sorted into
+ * this list or out of it.
+ */
+const PATH_CREDENTIALS = [
+    { host: CREDITGUARD_HOST, named: /creditguard\.co\.il/i, mask: maskCreditguardTxId },
+    { host: GRAVY_HOST, named: /gr4vy\.app/i, mask: maskGravySession },
+    { host: RAPYD_HOST, named: /rapyd\.net/i, mask: maskRapydToken },
+    { host: STRIPE_API_HOST, named: /api\.stripe\.com/i, mask: maskStripeSession },
+    { host: ACI_HOST, named: /oppwa\.com/i, mask: maskAciCheckout },
+];
 /**
  * A URL as it may appear in an error message: origin + path only. A paused
  * request's URL can carry a client secret in its query string, and error
@@ -929,8 +1034,13 @@ const PATH_SECRET = /(\/payment(?:\/|%2f))[^/]*/gi;
  * so it reads {txId}, as does any other id-shaped segment there.
  * On the Monri and WSPay hosts the secret is a path segment, so it is replaced
  * with `{client_secret}`: https://proxy.wspay.biz/v2/payment/{client_secret}/confirm.
+ * On Gravy's hosts the checkout session id is the credential, so it reads
+ * `{session}`: https://api.<merchant>.gr4vy.app/checkout/sessions/{session}/fields.
+ * On Rapyd's hosts the hosted page's id reads `{token}`: https://api.rapyd.net/v1/checkout/{token}.
+ * On api.stripe.com a Checkout Session id reads `{session}`:
+ * https://api.stripe.com/v1/payment_pages/{session}/confirm.
  * A string that is not a URL keeps the part before any `?` or `#`, with the
- * same segment masked.
+ * same segments masked.
  */
 export function redactUrl(raw) {
     // An ACI checkout id is that checkout's only capability; it never rides on an event.
@@ -940,12 +1050,18 @@ export function redactUrl(raw) {
     try {
         const u = new URL(raw);
         // A trailing dot names the same host, so it cannot let the secret through.
-        const path = PATH_SECRET_HOSTS.includes(u.hostname.replace(/\.$/, '')) ? u.pathname.replace(PATH_SECRET, '$1{client_secret}') : u.pathname;
-        return `${u.origin}${CREDITGUARD_HOST.test(u.hostname) ? maskCreditguardTxId(path) : path}`;
+        let path = PATH_SECRET_HOSTS.includes(u.hostname.replace(/\.$/, '')) ? u.pathname.replace(PATH_SECRET, '$1{client_secret}') : u.pathname;
+        for (const rule of PATH_CREDENTIALS)
+            if (rule.host.test(u.hostname))
+                path = rule.mask(path);
+        return `${u.origin}${path}`;
     }
     catch {
-        const bare = raw.split(/[?#]/)[0].replace(PATH_SECRET, '$1{client_secret}');
-        return /creditguard\.co\.il/i.test(bare) ? maskCreditguardTxId(bare) : bare;
+        let bare = raw.split(/[?#]/)[0].replace(PATH_SECRET, '$1{client_secret}');
+        for (const rule of PATH_CREDENTIALS)
+            if (rule.named.test(bare))
+                bare = rule.mask(bare);
+        return bare;
     }
 }
 /**
@@ -1000,6 +1116,17 @@ const EPROTECT_PREPARATION_REFUSALS = ['merchant_profile_mismatch'];
 const SECURE_ACCEPTANCE_PREPARATION_REFUSALS = [
     'processor_unavailable', 'sandbox_host_on_live_row', 'live_host_on_sandbox_row', 'unsupported_checkout', 'merchant_profile_mismatch',
 ];
+/**
+ * The API's refusals of a Paddle VGS preparation, before any preparation exists, that prepareCheckout
+ * surfaces by name: the lane is held to Agentcard's own account (`processor_unavailable`), the environment
+ * is not the client's test or live mode, a live checkout's merchant is not the name the reviewed seller pin
+ * carries (`merchant_profile_mismatch`), and the locked card is on a network Paddle's card request is not
+ * paid on (`paddle_vgs_card_unsupported`). An unreviewed seller's page answers `unsupported_checkout`, which
+ * PREPARATION_REFUSALS names for every checkout. Only for a Paddle checkout.
+ */
+const PADDLE_VGS_PREPARATION_REFUSALS = [
+    'processor_unavailable', 'sandbox_host_on_live_row', 'live_host_on_sandbox_row', 'merchant_profile_mismatch', 'paddle_vgs_card_unsupported',
+];
 /**
  * The reason the cardholder's device declines a bound prepared row with, per processor, when its own
  * send boundary passed before the card left it (the Vault's sendWindow, 12 seconds after it last saw
@@ -1405,12 +1532,17 @@ export class VaultClient {
      * preselects that card: without a pin the page preselects its own choice (its recommended
      * card, or the first card the cardholder's device can open), which can be another card. After
      * prepare(), pass the prepared checkout's `cardId`, the card the cardholder already approved.
-     * The facts hold only while the cardholder pays with that card. Throws PlaceholderCardError
-     * when there is no such card, its network has no placeholder, or it carries no expiry.
+     * The facts hold only while the cardholder pays with that card. `psp` names the processor
+     * whose card form the agent types into (the recognizer's name, `worldline_mycheckout`): a
+     * processor that needs its own number for the card's network gets it, and every other gets the
+     * network's default. Throws PlaceholderCardError when there is no such card, its network has no
+     * placeholder, or it carries no expiry.
      */
     async placeholderCard(input) {
         if (!input || typeof input.user !== 'string' || !input.user)
             throw new Error('placeholderCard needs the user whose stored card will pay.');
+        if (input.psp !== undefined && (typeof input.psp !== 'string' || !input.psp))
+            throw new Error('placeholderCard takes psp as the processor\'s name, such as worldline_mycheckout.');
         // The card list lives under /api/v2 only: the API aliases /v2/checkout alone without the prefix.
         const list = await this.get(`/api/v2/vault_cards?user_id=${encodeURIComponent(input.user)}`, input.signal);
         const cards = Array.isArray(list?.data) ? list.data : [];
@@ -1418,7 +1550,7 @@ export class VaultClient {
         if (!card || typeof card !== 'object' || typeof card.id !== 'string' || !card.id)
             throw new PlaceholderCardError('card_not_found');
         const brand = typeof card.brand === 'string' ? card.brand.toLowerCase() : '';
-        const number = Object.prototype.hasOwnProperty.call(PLACEHOLDER_NUMBERS, brand) ? PLACEHOLDER_NUMBERS[brand] : undefined;
+        const number = placeholderNumber(brand, input.psp);
         if (!number)
             throw new PlaceholderCardError('brand_unsupported');
         const month = card.expiry_month, year = card.expiry_year;
@@ -1507,6 +1639,12 @@ export class VaultClient {
         const amadeus = input.psp === AMADEUS_CHECKOUT_PSP;
         if (amadeus && !input.cardId)
             throw fail('card_required');
+        // Paddle VGS: Paddle's /pay sends the expiry and the card network the agent typed into Paddle's form
+        // (placeholderCard) beside the card the device stores, so the preparation names that card, and the API
+        // approves no other; refusing here asks nobody to approve a preparation that could never bind.
+        const paddle = input.psp === PADDLE_VGS_PSP;
+        if (paddle && !input.cardId)
+            throw fail('card_required');
         // CyberSource Flex, tokenized before Pay: the loaded card field's capture context and fields,
         // verified here against the keys payment-core pins before anything is created (the API and the
         // cardholder's device verify them again).
@@ -1631,6 +1769,8 @@ export class VaultClient {
                         || (secureAcceptance && (state.secure_acceptance_profile_id !== secureAcceptanceProfileId || state.card_id !== input.cardId))
                         // Amadeus: the card the cardholder approved is the one whose expiry the agent typed.
                         || (amadeus && state.card_id !== input.cardId)
+                        // Paddle VGS: the card the cardholder approved is the one whose facts the agent typed.
+                        || (paddle && state.card_id !== input.cardId)
                         // The API says a preparation tokenizes before Pay exactly when this one carried a capture context.
                         || (state.tokenize_before_pay === true) !== !!flexContext)
                         throw fail('ready_unconfirmed', id);
@@ -1675,6 +1815,7 @@ export class VaultClient {
                 && ((error.status >= 400 && error.status < 500 && (PREPARATION_REFUSALS.includes(error.code)
                     || (input.psp === 'fiserv' && FISERV_PREPARATION_REFUSALS.includes(error.code))
                     || (input.psp === EPROTECT_PSP && EPROTECT_PREPARATION_REFUSALS.includes(error.code))
+                    || (input.psp === PADDLE_VGS_PSP && PADDLE_VGS_PREPARATION_REFUSALS.includes(error.code))
                     || (!!flexContext && CYBERSOURCE_FLEX_PREPARATION_REFUSALS.includes(error.code))))
                     || (input.psp === 'fiserv' && error.status === 502 && error.code === 'cse_key_unavailable')))
                 throw fail(error.code);
@@ -2104,9 +2245,12 @@ export class VaultClient {
         // A prepared CyberSource Secure Acceptance token create too, for 30 seconds:
         // the merchant's page asks its frame for the reply for 30 seconds from Save,
         // and the API names 500 ms as such a row's poll interval.
+        // A prepared Paddle VGS card request too, for 20 seconds: Paddle's frame aborts it 10 seconds after
+        // Pay and sends it once more, and the API names 500 ms as such a row's poll interval.
         const preparedFastPollUntil = preparation?.psp === 'mercado_pago' ? Date.now() + 10_000
-            : preparation?.psp === EPROTECT_PSP ? Date.now() + 15_000
-                : preparation?.psp === SECURE_ACCEPTANCE_PSP ? Date.now() + SECURE_ACCEPTANCE_FAST_POLL_MS : 0;
+            : preparation?.psp === PADDLE_VGS_PSP ? Date.now() + 20_000
+                : preparation?.psp === EPROTECT_PSP ? Date.now() + 15_000
+                    : preparation?.psp === SECURE_ACCEPTANCE_PSP ? Date.now() + SECURE_ACCEPTANCE_FAST_POLL_MS : 0;
         // A preparation that tokenized before Pay: the cardholder's device already holds CyberSource's
         // token and approves as soon as this bind reaches it, while the page may give createToken only
         // seconds (Alaska Airlines' flight checkout gives it three). Poll every 100 ms for 10 seconds,
@@ -2652,11 +2796,12 @@ export class VaultClient {
      * approval produced: a SetupIntent confirm that carries no card and pays with
      * exactly the approved payment method (the page's own, or written by the
      * adapters in place of a card the confirm carries again).
-     * The API allows a card save only for a company Agentcard turned it on for,
-     * for an approval given on the Vault page, not by voice, with no amount, and
-     * a SetupIntent Stripe reports still confirmable on the same Stripe account;
-     * any other answer rejects with a CheckoutApiError whose code says why (for
-     * example `continuation_invalid` where it is off, `amount_mismatch`). Nothing
+     * The API allows a card save for any company, for an approval given on the
+     * Vault page, not by voice, with no amount, and a SetupIntent Stripe reports
+     * still confirmable on the same Stripe account; any other answer rejects with
+     * a CheckoutApiError whose code says why (for example `amount_mismatch`, or
+     * `continuation_invalid` for a confirm that is not a card-free SetupIntent
+     * confirm). Nothing
      * is charged: the adapters continue the page's request once this resolves.
      */
     async checkStripeSetupContinuation(authorizationId, request) {

package/dist/elavon-converge.d.ts

@@ -7,9 +7,12 @@ export declare const CONVERGE_CAPABILITY = "converge_hpp_process";
  * the device refuses with, so an integrator reads one code whichever of them refused.
  *   - A shape the Vault never pays: `converge_wallet_refused`, `converge_debit_card_refused`,
  *     `converge_push_to_card_refused`, `converge_gift_card_refused`, `converge_payment_type_refused`,
- *     `converge_captcha_refused`, `converge_service_fee_refused`, `converge_recurring_refused`,
+ *     `converge_service_fee_refused`, `converge_recurring_refused`,
  *     `converge_card_saving_refused` (ssl_get_token or ssl_add_token), `converge_amount_add_on_refused`
  *     (a tip or cash back) and `converge_currency_refused` (anything but US dollars).
+ *   - A CAPTCHA answer Google never issued: `converge_captcha_refused` (a captchaToken that is not a
+ *     non-empty string of at most 4,096 URL-safe characters). A page with its CAPTCHA on pauses like
+ *     any other once a person solved it, and the answer rides to Converge unchanged.
  *   - A follow-up after a step the Vault cannot complete: `converge_3ds_follow_up_refused` (3-D
  *     Secure or Pay Defense) and `converge_surcharge_refused`.
  *   - A body the cardholder has nothing to approve on: `converge_amount_missing` and

package/dist/elavon-converge.generated.js

@@ -1,6 +1,6 @@
 // @ts-nocheck
 // Generated from @agent-cards/payment-core. Do not edit.
-// artifact-sha256: 009a8b902de51c4dadddae592b32d2edbd5b394f130938e1a41cd62a06a234a8
+// artifact-sha256: 136e1c2b0fd2bdee0cfbf5efbbfaf1a92ace7d1cc52e17a3fd5a4584370e5e53
 // src/elavon-converge.js
 var CONVERGE_HOSTS = /* @__PURE__ */ Object.freeze(["api.convergepay.com", "api.demo.convergepay.com", "www.convergepay.com"]);
 var CONVERGE_DEMO_HOST = "api.demo.convergepay.com";
@@ -77,6 +77,7 @@ var ONE_TIME_RECURRING_FLAG = "false";
 var CARD_SAVING_FLAGS = /* @__PURE__ */ Object.freeze(["ssl_get_token", "ssl_add_token"]);
 var CREDENTIAL_FIELDS = /* @__PURE__ */ Object.freeze(["ssl_account_id", "ssl_merchant_id", "ssl_user_id", "ssl_pin", "ssl_vendor_id"]);
 var AMOUNT_ADD_ON_FIELDS = /* @__PURE__ */ Object.freeze(["ssl_tip_amount", "ssl_cashback_amount"]);
+var SOLVED_CAPTCHA = /^[A-Za-z0-9_-]{1,4096}$/;
 var CARD_NUMBER = /^\d{12,19}$/;
 var EXPIRY_MMYY = /^(0[1-9]|1[0-2])\d{2}$/;
 var CVC = /^\d{3,4}$/;
@@ -132,7 +133,7 @@ function convergeBodyVerdict(body) {
         return refuse("converge_credential_refused");
     if (WALLET_FIELDS.some((key) => owns(data, key)))
         return refuse("converge_wallet_refused");
-    if (owns(parsed, "captchaToken"))
+    if (owns(parsed, "captchaToken") && !(typeof parsed.captchaToken === "string" && SOLVED_CAPTCHA.test(parsed.captchaToken)))
         return refuse("converge_captcha_refused");
     if (SERVICE_FEE_FIELDS.some((key) => owns(data, key)))
         return refuse("converge_service_fee_refused");

package/dist/elavon-converge.js

@@ -25,9 +25,12 @@ export const CONVERGE_CAPABILITY = 'converge_hpp_process';
  * the device refuses with, so an integrator reads one code whichever of them refused.
  *   - A shape the Vault never pays: `converge_wallet_refused`, `converge_debit_card_refused`,
  *     `converge_push_to_card_refused`, `converge_gift_card_refused`, `converge_payment_type_refused`,
- *     `converge_captcha_refused`, `converge_service_fee_refused`, `converge_recurring_refused`,
+ *     `converge_service_fee_refused`, `converge_recurring_refused`,
  *     `converge_card_saving_refused` (ssl_get_token or ssl_add_token), `converge_amount_add_on_refused`
  *     (a tip or cash back) and `converge_currency_refused` (anything but US dollars).
+ *   - A CAPTCHA answer Google never issued: `converge_captcha_refused` (a captchaToken that is not a
+ *     non-empty string of at most 4,096 URL-safe characters). A page with its CAPTCHA on pauses like
+ *     any other once a person solved it, and the answer rides to Converge unchanged.
  *   - A follow-up after a step the Vault cannot complete: `converge_3ds_follow_up_refused` (3-D
  *     Secure or Pay Defense) and `converge_surcharge_refused`.
  *   - A body the cardholder has nothing to approve on: `converge_amount_missing` and

package/dist/lifecycle.d.ts

@@ -106,7 +106,14 @@ export interface CheckoutController {
     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>;
-    /** Stop locally and best-effort retire an unbound preparation. Does not cancel a processor payment. */
+    /**
+     * Stop locally and best-effort retire an unbound preparation. Does not cancel a processor payment.
+     * A checkout that already ended keeps its state and reason (`completed`, `declined`, `failed`,
+     * `timed_out`, `unsupported`, `cancelled`, `outcome_unknown`) once no card request is in flight, or
+     * once the request in flight has its own outcome recorded (a cancel from onStateChange or the `failed` event).
+     * Any other reads `outcome_unknown` once a card request is in flight or an authorization exists,
+     * and `cancelled` before, with reason `local_cancel`.
+     */
     cancel(): void;
     /** Ask the application's merchant resolver. A rejection records unknown; never automatically retries payment. */
     reconcile(): Promise<Readonly<CheckoutState>>;
@@ -131,6 +138,7 @@ export declare class CheckoutLifecycle implements CheckoutController {
     private state;
     private held;
     private active;
+    private settled;
     private cancelled;
     private merchantAborted;
     private unboundStripeToken;

package/dist/lifecycle.js

@@ -2,6 +2,20 @@ import { AdyenTestPlatformRefusedError, ApprovalDeclinedError, ApprovalTimeoutEr
 import { CardEndpointRefusedError } from './card-endpoint.js';
 import { parseOwnedShopReceipt, OWNED_SHOP_SKU, OWNED_SHOP_AMOUNT_CENTS, OWNED_SHOP_CURRENCY } from './owned-shop.generated.js';
 import { isWspayChallenge } from './wspay.js';
+/**
+ * The statuses that end an attempt: its outcome is known (`completed`, `declined`, `failed`,
+ * `timed_out`, `unsupported`, `cancelled`), or the SDK already reported it unknown with its own
+ * reason (`outcome_unknown`). cancel() stops and holds the attachment but leaves these as they are,
+ * so an application that cancels at cleanup still reads the outcome, once no card request is in
+ * flight or the request in flight has its own outcome recorded. A checkout not started (`idle`) or
+ * still under way (`awaiting_approval`, `ready_to_submit`, `awaiting_merchant`, `requires_user_action`,
+ * or any status while a request whose outcome is not recorded is in flight) has none:
+ * cancelling it reads `outcome_unknown` once a request is in flight or an authorization exists,
+ * since a card or a token may still move, and `cancelled` before.
+ */
+const FINAL_STATUSES = new Set([
+    'completed', 'declined', 'failed', 'timed_out', 'unsupported', 'cancelled', 'outcome_unknown',
+]);
 /** How many times one approval's card-free Stripe confirmation may be checked before it is simply held. */
 export const MAX_STRIPE_CONTINUATION_CHECKS = 3;
 /**
@@ -29,6 +43,10 @@ export class CheckoutLifecycle {
     state = { status: 'idle', authorizationId: null };
     held = false;
     active = false;
+    // The card request in flight has its own outcome recorded (failed(), handedOff(), merchantNeverRetried()), and
+    // the adapter has yet to call end(): it still answers the page and tidies up. An application that cancels
+    // from onStateChange or the `failed` event runs in that window, and the request waits on nothing there.
+    settled = false;
     cancelled = false;
     merchantAborted = false;
     unboundStripeToken = false;
@@ -113,6 +131,7 @@ export class CheckoutLifecycle {
     }
     begin() {
         this.active = true;
+        this.settled = false;
         this.set({ status: 'awaiting_approval', authorizationId: null, ...(this.state.preparationId ? { preparationId: this.state.preparationId } : {}) });
     }
     end() { this.active = false; }
@@ -137,9 +156,20 @@ export class CheckoutLifecycle {
         catch { /* observer only */ }
     }
     cancel() {
+        // A checkout that already ended keeps its outcome: a refusal the processor gave, a payment the
+        // merchant confirmed, an unknown the SDK already named. Stopping the attachment afterwards
+        // changes nothing that happened, so only an attempt still under way reads as stopped here.
+        // A card request still in flight is under way whatever the state says: its authorization can
+        // still be approved on the cardholder's device, so cancelling it reads outcome_unknown as before.
+        // One whose own outcome is recorded (settled) is not: the adapter only has to finish answering
+        // the page, so a cancel from onStateChange or the `failed` event keeps that outcome.
+        // Read before the abort, so the state the application saw decides.
+        const ended = FINAL_STATUSES.has(this.state.status) && (!this.active || this.settled);
         this.cancelled = true;
         this.held = true;
         this.abort.abort();
+        if (ended)
+            return;
         this.set({ ...this.state, status: this.active || this.state.authorizationId ? 'outcome_unknown' : 'cancelled', reason: 'local_cancel' });
     }
     /** The exact browser request is gone; a late approval cannot reopen it. */
@@ -180,6 +210,7 @@ export class CheckoutLifecycle {
     merchantNeverRetried(authorizationId) {
         if (this.cancelled)
             return;
+        this.settled = true;
         this.set({ ...this.state, authorizationId, status: 'declined', reason: 'merchant_never_retried' });
     }
     /**
@@ -324,6 +355,7 @@ export class CheckoutLifecycle {
     handedOff(replay) {
         if (this.merchantAborted)
             return;
+        this.settled = true;
         if (this.ownedShopOrderId) {
             this.held = true;
             this.set({ status: 'completed', authorizationId: replay.authorizationId, mode: 'token', orderId: this.ownedShopOrderId });
@@ -359,6 +391,8 @@ export class CheckoutLifecycle {
     failed(error, handoffStarted = false) {
         if (this.cancelled)
             return;
+        // Before any state is set, so an observer that cancels from onStateChange sees the outcome as recorded.
+        this.settled = true;
         if (this.merchantAborted) {
             this.merchantRequestAborted();
             return;

package/dist/paddle-vgs.generated.d.ts

@@ -0,0 +1,50 @@
+declare var PADDLE_VGS_PSP: string;
+declare var PADDLE_VGS_CAPABILITY: string;
+declare var PADDLE_VGS_OPERATION: string;
+declare var PADDLE_VGS_CONTENT_TYPE: string;
+declare var PADDLE_VGS_CARDS_URLS: Readonly<{
+    production: "https://vault.paddle.com/cards";
+    sandbox: "https://sandbox-vault.paddle.com/cards";
+}>;
+declare var PADDLE_VGS_REFUSAL_CODES: readonly string[];
+declare function paddleVgsEnvironment(url: any): "production" | "sandbox" | null;
+declare function isPaddleVgsCardsUrl(url: any): boolean;
+declare function paddleVgsBodyVerdict(body: any): Readonly<{
+    verdict: "refuse";
+    code: any;
+}> | Readonly<{
+    verdict: "card";
+}>;
+declare function paddleVgsRequestRefusal(request: any): any;
+declare function isPreparedPaddleVgsRequest(url: any, method: any, body: any, environment: any, headers: any): boolean;
+declare var PADDLE_VGS_MERCHANT_PINS: readonly any[];
+declare function paddleVgsMerchantPin(merchantOrigin: any, pins?: readonly any[]): any;
+declare function paddleVgsMerchantRefusal(environment: any, merchantOrigin: any, authorization: any, pins?: readonly any[]): "unsupported_environment" | "paddle_vgs_merchant_unreviewed" | "paddle_vgs_seller_unreviewed" | null;
+declare function paddleVgsSellerClaimsPinned(pins?: readonly any[]): boolean;
+declare function paddleVgsRefusalMessage(code: any): any;
+declare var PADDLE_VGS_CARD_NETWORKS: readonly string[];
+declare function paddleVgsCardRefusal(body: any, card: any): any;
+declare function paddleVgsStoredCardRefusal(brand: any): "paddle_vgs_card_unsupported" | null;
+declare function paddleVgsTypedCardRefusal(body: any, stored: any): any;
+declare function injectPaddleVgsCard(body: any, card: any): {
+    body: string;
+    where: string[];
+};
+declare function paddleVgsRefusalCode(text: any): string | null;
+declare function paddleVgsAnswerOutcome(status: any, text: any, card: any): {
+    outcome: string;
+    reason: string;
+    code?: undefined;
+    body?: undefined;
+} | {
+    outcome: string;
+    code: string;
+    reason?: undefined;
+    body?: undefined;
+} | {
+    outcome: string;
+    body: string;
+    reason?: undefined;
+    code?: undefined;
+};
+export { PADDLE_VGS_CAPABILITY, PADDLE_VGS_CARDS_URLS, PADDLE_VGS_CARD_NETWORKS, PADDLE_VGS_CONTENT_TYPE, PADDLE_VGS_MERCHANT_PINS, PADDLE_VGS_OPERATION, PADDLE_VGS_PSP, PADDLE_VGS_REFUSAL_CODES, injectPaddleVgsCard, isPaddleVgsCardsUrl, isPreparedPaddleVgsRequest, paddleVgsAnswerOutcome, paddleVgsBodyVerdict, paddleVgsCardRefusal, paddleVgsEnvironment, paddleVgsMerchantPin, paddleVgsMerchantRefusal, paddleVgsRefusalCode, paddleVgsRefusalMessage, paddleVgsRequestRefusal, paddleVgsSellerClaimsPinned, paddleVgsStoredCardRefusal, paddleVgsTypedCardRefusal };