@vonpay/checkout-node 0.15.1 → 1.1.0

package/dist/client.js

@@ -17,6 +17,30 @@ const DEFAULT_API_VERSION = "2026-05-05";
 const DEFAULT_MAX_RETRIES = 2;
 const DEFAULT_TIMEOUT = 30_000;
 const RETRYABLE_STATUS_CODES = new Set([429, 500, 502, 503, 504]);
+// The subset of RETRYABLE_STATUS_CODES whose outcome is AMBIGUOUS — the
+// request may already have been applied at the origin even though we never
+// saw a usable response. 429 is deliberately excluded: a rate-limited request
+// is rejected by the limiter BEFORE the handler runs, so it is not applied and
+// stays safe to repeat with or without an idempotency key.
+//
+// ⚠️ That ordering is a property of the SERVER (vonpay-checkout), which this
+// repo cannot see. It is the documented design, not something verified from
+// here — if a limiter is ever placed behind a money-moving handler, 429 must
+// join the ambiguous set.
+//
+// Ambiguity is the whole problem. A vault-forward charge that times out on our
+// side still lands downstream — measured 2026-08-15, buyer charged, response
+// never seen — and the upstream vendor does no de-duplication on a forward.
+// So a blind retry of an ambiguous state-changing call is a second charge.
+const AMBIGUOUS_STATUS_CODES = new Set([500, 502, 503, 504]);
+//
+// The guard is scoped by an explicit `movesMoney` marker on the call site
+// rather than by HTTP verb. Deliberate: a blanket "never retry a POST" rule
+// would also strip retries from `sessions.create`, `tokens.create` and the
+// webhook-subscription writes, none of which can debit a buyer a second time —
+// a resilience regression bought for no safety. The marked set is exactly the
+// review-rule definition (`api/idempotency-on-money-writes`): a call whose
+// repeat "triggers a charge, refund, credit, or other money movement".
 // Outbound webhook signature freshness window (see docs/webhook-signature-v1.md
 // in vonpay-checkout — the frozen contract). Asymmetric on purpose: a webhook
 // older than 5 min is a stale-at-rest replay; a webhook more than 30 sec in the
@@ -123,26 +147,151 @@ function resolveConfig(config) {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
-// One-time warning when a replayable legacy v1 return signature is accepted
-// (kaiju #425). Module-scoped so it fires once per process, not once per call
-// (verifyReturnSignature is on a hot return-handling path).
+/**
+ * Return-signature schemes this SDK knows how to verify.
+ *
+ * The DEFAULT accepts both, preserving the behaviour every existing caller has.
+ * Deliberately NOT v2-only: whether a merchant's account is issued v2 returns is
+ * a server-side setting they do not control from here, so a strict default would
+ * stop confirmations working for anyone still issued v1 — a revenue-visible
+ * outage arriving on a routine upgrade. v1 retires 2026-11-21; the default flips
+ * at the next major, once the server side is confirmed.
+ */
+/**
+ * Session states that are genuinely FINISHED and not paid.
+ *
+ * ⚠️ Deliberately a denylist of terminal states, not an allowlist of pending
+ * ones. Both express the same thing for the states we know about today
+ * (`pending`/`processing` are in flight; `failed`/`expired` are over), but they
+ * fail in OPPOSITE directions the moment the server adds a state this SDK
+ * predates — and only one of those directions is survivable.
+ *
+ * With an allowlist, an unrecognised future state (say `requires_action`) is
+ * "not pending", so it reads as `not_succeeded` — telling a buyer who is
+ * mid-authentication that their payment failed, which is the exact
+ * pay-twice outcome the surrounding code exists to prevent. With this
+ * denylist it reads as `still_pending`: "wait for the webhook". An SDK that
+ * is out of date should degrade toward patience, not toward accusing a buyer
+ * of not paying.
+ *
+ * Kept in sync with the `SessionState` union; the server's enum is the
+ * contract (`openapi/openapi.yaml`, SessionStatus.status).
+ */
+const TERMINAL_SESSION_STATES = new Set(["failed", "expired"]);
+export const KNOWN_RETURN_SCHEMES = ["v1", "v2"];
+export const DEFAULT_RETURN_SCHEMES = ["v1", "v2"];
+// One-time advisories on the return-signature path. Module-scoped so each fires
+// once per process, not once per call (verifyReturnSignature is on a hot
+// return-handling path).
+//
+// These use console.warn deliberately: it cannot throw. The Python twin had to
+// be moved off `warnings.warn` for exactly this reason — that channel raises
+// under -W error, which turned a verifier documented "never raises" into one
+// that threw on the buyer-return path after the card was charged.
 let warnedV1ReturnSignatureReplayable = false;
 function warnV1ReturnSignatureReplayable() {
     if (warnedV1ReturnSignatureReplayable)
         return;
     warnedV1ReturnSignatureReplayable = true;
     console.warn("[vonpay] verifyReturnSignature: accepted a legacy v1 return signature. " +
-        "v1 binds no timestamp or success URL, so a captured return URL can be " +
-        "replayed indefinitely. Before fulfilling: (1) confirm payment via " +
-        "sessions.get(session).status === 'succeeded', and (2) guard your own " +
-        "idempotency — sessions.get cannot tell you whether you already fulfilled " +
-        "this order and returns 'succeeded' on replay, so track fulfilled session " +
-        "IDs. Prefer v2 returns (expectedSuccessUrl + expectedKeyMode), or pass " +
-        "{ rejectV1: true } to refuse v1. See https://docs.vonpay.com/return-signatures");
+        "v1 binds no timestamp and no success URL, so a captured return URL can " +
+        "be replayed indefinitely. A valid signature proves the message is " +
+        "AUTHENTIC — it does not prove the payment succeeded, and a decline is " +
+        "signed just as validly. Before fulfilling: (1) check " +
+        "status === 'succeeded'; (2) confirm server-side via sessions.get(session); " +
+        "and (3) guard your own idempotency — sessions.get cannot tell you whether " +
+        "you already fulfilled this order and keeps returning 'succeeded' on " +
+        "replay, so track fulfilled session IDs. v1 is scheduled for retirement " +
+        "on 2026-11-21. To refuse it now, pass { acceptedSchemes: ['v2'] } — but " +
+        "confirm your account already issues v2 returns first, or that will " +
+        "refuse every return you receive. " +
+        "See https://docs.vonpay.com/integration/handle-return");
 }
-/** Test-only: reset the one-time v1 replay warning. Underscore-prefixed; not public API. */
+let warnedV1ReturnSignatureRefused = false;
+function warnV1ReturnSignatureRefused() {
+    if (warnedV1ReturnSignatureRefused)
+        return;
+    warnedV1ReturnSignatureRefused = true;
+    console.warn("[vonpay] verifyReturnSignature: refused a v1 return signature because " +
+        "acceptedSchemes excludes it. If your Vonpay account still issues v1 " +
+        "returns, this refuses EVERY return — verify which scheme your account " +
+        "issues before keeping this setting. If it already issues v2, a v1 " +
+        "signature arriving now is either a replay of a pre-migration capture or " +
+        "a misconfiguration, and refusing it is correct. " +
+        "See https://docs.vonpay.com/integration/handle-return");
+}
+let warnedReturnSignatureMismatch = false;
+function warnReturnSignatureMismatch() {
+    if (warnedReturnSignatureMismatch)
+        return;
+    warnedReturnSignatureMismatch = true;
+    console.warn("[vonpay] confirmReturn: a `secret` was supplied and the return signature " +
+        "did NOT verify. This no longer affects `paid` — the session status is " +
+        "read from the server, which is authenticated by your API key — but the " +
+        "check itself is failing, and the usual cause is a secret that cannot " +
+        "match rather than a tampered URL. Returns are signed with a " +
+        "platform-wide secret, so a per-merchant `ss_*` from the dashboard will " +
+        "never verify. If that is your situation, omit the `secret` argument " +
+        "entirely rather than passing one that always fails. " +
+        "See https://docs.vonpay.com/integration/handle-return");
+}
+let warnedRejectV1Deprecated = false;
+function warnRejectV1Deprecated() {
+    if (warnedRejectV1Deprecated)
+        return;
+    warnedRejectV1Deprecated = true;
+    console.warn("[vonpay] verifyReturnSignature: `rejectV1` is deprecated and will be " +
+        "removed in the next major version. Replace `{ rejectV1: true }` with " +
+        "`{ acceptedSchemes: ['v2'] }`. The verifier now declares which schemes " +
+        "it accepts rather than naming one legacy version to refuse, which also " +
+        "scales to future schemes. Behaviour is unchanged for now.");
+}
+/** Test-only: reset the one-time return-signature advisories. Not public API. */
 export function __resetReturnSignatureWarning() {
     warnedV1ReturnSignatureReplayable = false;
+    warnedV1ReturnSignatureRefused = false;
+    warnedRejectV1Deprecated = false;
+    // Added 2026-08-18 with the mismatch warning itself. Omitting it made the
+    // warning untestable after any earlier test in the same process had already
+    // consumed the once-only flag — which is precisely how it shipped with no
+    // assertion that it fires at all (found by mutation: deleting the call left
+    // every suite green). Any new once-per-process warning belongs here too.
+    warnedReturnSignatureMismatch = false;
+}
+/**
+ * Resolve the effective scheme allowlist from the (possibly legacy) options.
+ *
+ * `rejectV1` published in 0.12.0 on 2026-07-01, so it stays working — merchants
+ * must not have an upgrade break under them. It is a strict subset of what
+ * `acceptedSchemes` expresses, so it maps cleanly onto it.
+ *
+ * Precedence: an explicit `acceptedSchemes` always wins. Supplying both is a
+ * contradiction only the caller can resolve, and silently honouring the
+ * deprecated one would make the new, more specific option appear ignored.
+ */
+function resolveAcceptedSchemes(options) {
+    if (options?.acceptedSchemes !== undefined) {
+        const list = options.acceptedSchemes;
+        // `str` has no JS analogue here, but an empty or bogus list fails the same
+        // way the Python side does: refusing every return, silently. Say so loudly.
+        if (!Array.isArray(list) || list.length === 0) {
+            throw new TypeError("acceptedSchemes must be a non-empty array of scheme names " +
+                `(${KNOWN_RETURN_SCHEMES.join(", ")}); got ${JSON.stringify(list)}. ` +
+                "An empty list would refuse every return signature.");
+        }
+        const unknown = list.filter((s) => !KNOWN_RETURN_SCHEMES.includes(s));
+        if (unknown.length > 0) {
+            throw new TypeError(`acceptedSchemes contains unknown scheme(s) ${JSON.stringify(unknown)}. ` +
+                `Known schemes: ${KNOWN_RETURN_SCHEMES.join(", ")}. A typo here would ` +
+                "silently refuse every return signature.");
+        }
+        return new Set(list);
+    }
+    if (options?.rejectV1) {
+        warnRejectV1Deprecated();
+        return new Set(["v2"]);
+    }
+    return new Set(DEFAULT_RETURN_SCHEMES);
 }
 /**
  * Canonicalise a success URL the same way the Von Payments return-URL
@@ -675,6 +824,16 @@ export class VonPayCheckout {
         if (options?.idempotencyKey) {
             headers["Idempotency-Key"] = options.idempotencyKey;
         }
+        // Can the SDK repeat this request on its own initiative after an AMBIGUOUS
+        // failure? Only when repeating it cannot charge twice: either it moves no
+        // money, or the caller gave us a key the server can collapse the repeat
+        // against. The key is set once, above, and therefore rides every attempt of
+        // this call — a retry never mints a fresh one.
+        //
+        // Note the asymmetry with `RETRYABLE_STATUS_CODES`: this does not make the
+        // error non-retryable, it makes it non-retryable BY US. See VonPayError
+        // `retryWithheld`.
+        const retrySafe = !options?.movesMoney || Boolean(options?.idempotencyKey);
         let lastError;
         for (let attempt = 0; attempt <= this.config.maxRetries; attempt++) {
             if (attempt > 0) {
@@ -715,7 +874,10 @@ export class VonPayCheckout {
                         docs: "https://docs.vonpay.com",
                     };
                 }
-                lastError = new VonPayError(response.status, errorData, requestId, rateLimit);
+                // Withhold OUR retry when the outcome is ambiguous and a repeat could
+                // charge twice. Decided before construction so the error can carry it.
+                const retryWithheld = !retrySafe && AMBIGUOUS_STATUS_CODES.has(response.status);
+                lastError = new VonPayError(response.status, errorData, requestId, rateLimit, retryWithheld);
                 // Only retry on retryable status codes
                 if (!RETRYABLE_STATUS_CODES.has(response.status)) {
                     this.reportError(lastError, {
@@ -728,6 +890,19 @@ export class VonPayCheckout {
                     });
                     throw lastError;
                 }
+                // Ambiguous outcome on a state-changing call with no idempotency key —
+                // surface the first failure rather than risk a duplicate charge.
+                if (retryWithheld) {
+                    this.reportError(lastError, {
+                        method: options?.reporterMethod ?? `${method} ${path}`,
+                        url: VonPayCheckout.safeUrl(url),
+                        status: response.status,
+                        requestId,
+                        code: errorData.code,
+                        attempt,
+                    });
+                    throw lastError;
+                }
                 // Don't retry if we've exhausted attempts
                 if (attempt === this.config.maxRetries) {
                     this.reportError(lastError, {
@@ -746,9 +921,20 @@ export class VonPayCheckout {
                 if (err instanceof VonPayError) {
                     throw err;
                 }
-                // Network/timeout error — retryable
+                // Network/timeout error — retryable in principle, but ALWAYS ambiguous:
+                // an aborted fetch tells us nothing about whether the origin applied
+                // the request. On a state-changing call with no idempotency key that
+                // makes a retry a potential second charge, so we stop here.
                 lastError =
                     err instanceof Error ? err : new Error("Unknown fetch error");
+                if (!retrySafe) {
+                    this.reportError(lastError, {
+                        method: options?.reporterMethod ?? `${method} ${path}`,
+                        url: VonPayCheckout.safeUrl(url),
+                        attempt,
+                    });
+                    throw lastError;
+                }
                 if (attempt === this.config.maxRetries) {
                     this.reportError(lastError, {
                         method: options?.reporterMethod ?? `${method} ${path}`,
@@ -771,7 +957,7 @@ export class VonPayCheckout {
      * fail at the same instant (e.g. a dependency blip hitting a whole fleet). The
      * prior ±10% one-sided window (`base` … `1.1×base`) was narrow enough that a
      * fleet retried in near-lockstep and re-amplified the storm against a service
-     * that was already struggling (kaiju #428). The mean delay is unchanged — the
+     * that was already struggling. The mean delay is unchanged — the
      * jitter is zero-centred — so backoff timing is preserved; only the spread
      * widens.
      */
@@ -790,6 +976,7 @@ export class VonPayCheckout {
                 body: nestMirrorUnderMetadata(buildSnakeBodyOpaqueMetadata(prepared)),
                 idempotencyKey: options?.idempotencyKey,
                 reporterMethod: "paymentIntents.create",
+                movesMoney: true,
             });
             return paymentIntentFromWire(data);
         },
@@ -814,6 +1001,7 @@ export class VonPayCheckout {
                 body,
                 idempotencyKey: options?.idempotencyKey,
                 reporterMethod: "paymentIntents.capture",
+                movesMoney: true,
             });
             return paymentIntentFromWire(data);
         },
@@ -854,6 +1042,7 @@ export class VonPayCheckout {
                 body: buildSnakeBodyOpaqueMetadata(params),
                 idempotencyKey: options?.idempotencyKey,
                 reporterMethod: "refunds.create",
+                movesMoney: true,
             });
             return refundFromWire(data);
         },
@@ -866,10 +1055,26 @@ export class VonPayCheckout {
          * iframe-vault providers require a `providerReference` minted
          * browser-side; the server returns 422 validation_error otherwise.
          * Sandbox keys auto-mint a mock card token if no card data is supplied.
+         *
+         * ⚠️ If you want the saved card to appear in the buyer's saved-card picker
+         * later, pass `allowRedisplay: "always"` HERE. That permission can only be
+         * recorded at save time and can never be added afterwards.
          */
         create: async (params, options) => {
             const { data } = await this.request("POST", "/v1/tokens", {
-                body: buildSnakeBodyOpaqueMetadata(params),
+                body: buildSnakeBodyOpaqueMetadata({
+                    ...params,
+                    // The display permission rides EVERY save, even an unasked one.
+                    // The contract is explicit that `unspecified` is a real answer and
+                    // an absent field is not: omitting it records a blank that cannot
+                    // be told apart from a card saved before the permission existed,
+                    // and the value can never be added afterwards. `unspecified`
+                    // grants nothing, so defaulting here cannot over-grant — it only
+                    // makes the record honest. Callers who asked the buyer pass
+                    // `"always"` (the only value the saved-card picker will show) or
+                    // `"limited"`.
+                    allowRedisplay: params.allowRedisplay ?? "unspecified",
+                }),
                 idempotencyKey: options?.idempotencyKey,
                 reporterMethod: "tokens.create",
             });
@@ -892,6 +1097,157 @@ export class VonPayCheckout {
             return data;
         },
         /** Retrieve the current state of a checkout session. Requires a secret key (vp_sk_*). Publishable keys are rejected with 403. */
+        /**
+         * Confirm, in one call, that a returning buyer actually paid.
+         *
+         * **Use this instead of `verifyReturnSignature` unless you have a specific
+         * reason not to.** That function answers a narrower question than it
+         * appears to: it returns `true` for an *authentic* message, and a DECLINED
+         * payment is signed just as authentically as an approved one. Reading its
+         * boolean as "they paid" is the expensive mistake on this path.
+         *
+         * Reads the session status from the SERVER — not from the redirect URL. The
+         * URL is a hint carried by the buyer's browser; the server is the authority,
+         * it is fresher, and the read is already authenticated by your API key.
+         *
+         * ⚠️ **Do not pass a `secret` unless you actually hold the one the redirect
+         * was signed with.** Returns are signed with a platform-wide secret, so a
+         * per-merchant `ss_*` from the dashboard can never verify. In 1.0.0 a failed
+         * signature short-circuited to `paid: false` before the server was asked, so
+         * that combination reported every genuinely successful payment as unpaid.
+         * The signature is now optional hardening and cannot mask the truth;
+         * `signatureValid` is `null` when no check was performed.
+         *
+         * ⚠️ **This does not make fulfilment safe on its own, and cannot.**
+         * `paid: true` means this buyer paid; it does not mean you have not already
+         * shipped their order. The status keeps reading `succeeded` on every replay
+         * of the same URL, so record which session IDs you have fulfilled and
+         * refuse to fulfil one twice. That needs your database.
+         *
+         * ⚠️ **The redirect is not a guarantee of anything.** Buyers close laptops
+         * and never load your success page. Webhooks are the reliable fulfilment
+         * trigger; this is for what you show the buyer who did arrive.
+         * See https://docs.vonpay.com/integration/handle-return
+         *
+         * @throws on a failed session lookup — `VonPayError` for API errors, and the
+         * underlying transport error (e.g. a `TypeError` from `fetch`) for network
+         * failures, which is NOT wrapped. Catch broadly rather than narrowing to
+         * `VonPayError`, or a network blip will escape and 500 a buyer who just paid.
+         *
+         * A failed lookup is deliberately NOT reported as `paid: false` — that would
+         * turn our outage into the merchant's silent under-fulfilment, and the two
+         * need opposite handling.
+         *
+         * Requires a secret key (`vp_sk_*`): this reads `GET /v1/sessions/:id`,
+         * which rejects publishable keys with 403.
+         */
+        confirmReturn: async (params, 
+        /**
+         * OPTIONAL. Omit it unless you genuinely hold the secret the redirect was
+         * signed with.
+         *
+         * Most integrators should not pass anything here. The redirect is signed
+         * with a platform-wide secret, so a per-merchant `ss_*` from the dashboard
+         * will never match it, and passing one buys a check that always fails. The
+         * session read below is authenticated by your API key and is the actual
+         * answer to "did this buyer pay".
+         *
+         * Kept (rather than removed) so this stays source-compatible with 1.0.0
+         * callers, and so a first-party integration that DOES hold the signing
+         * secret can still assert the redirect was untampered.
+         */
+        secret, options) => {
+            const sessionId = params.session ?? "";
+            // No session id means there is nothing to ask the server about. This is
+            // NOT the "we could not check" case below — there is no session that
+            // could have been paid — so reporting it as unpaid cannot under-fulfil.
+            if (!sessionId) {
+                return {
+                    paid: false,
+                    signatureValid: secret === undefined || secret === null
+                        ? null
+                        : VonPayCheckout.verifyReturnSignature(params, secret, options),
+                    reason: "missing_session",
+                };
+            }
+            // ⛔ THE SIGNATURE IS NOT A GATE. Read this before "simplifying" it back.
+            //
+            // 1.0.0 verified first and returned `paid: false` on failure, without ever
+            // asking the server. That looks like defence in depth and was in fact a
+            // money bug, because the redirect is signed with a PLATFORM-WIDE secret
+            // (`VON_PAY_SESSION_SECRET`, read at module scope with no merchant
+            // argument) that no merchant holds — and could not safely be given one,
+            // since holding it would let any merchant forge any other merchant's
+            // confirmations. Our own documentation told merchants to verify with a
+            // per-merchant `ss_*` from the dashboard. Those can never match, so every
+            // check failed, and the documented `if (outcome.paid)` showed FAILURE to
+            // every buyer whose card had just been charged.
+            //
+            // Measured before the fix: 0 merchants affected, because the endpoint had
+            // 0 authenticated reads in 90 days. The trigger was adoption — and our own
+            // 1.0 docs were what would have caused it.
+            //
+            // The server read is already authenticated by the merchant's API key, so
+            // it is the answer to "did they pay". This is Stripe's model: the redirect
+            // carries a session id, you retrieve it server-side, and per-merchant
+            // signatures live on WEBHOOKS, where they are actually issued per
+            // merchant. The signature here is optional hardening — it may tell you a
+            // URL looks tampered with; it must never stop you learning the truth.
+            const signatureValid = secret === undefined || secret === null
+                ? null
+                : VonPayCheckout.verifyReturnSignature(params, secret, options);
+            if (signatureValid === false) {
+                // Loud, because the overwhelmingly likely cause is a misconfigured
+                // secret rather than an attack — and a merchant who never sees this
+                // will believe they have a tamper check that has never once passed.
+                warnReturnSignatureMismatch();
+            }
+            // Deliberately NOT wrapped: a lookup failure is an exception, not a
+            // `paid: false`. Collapsing "we could not check" into "they did not pay"
+            // is the false-negative class that makes a merchant silently withhold
+            // goods a buyer already paid for.
+            const session = await this.sessions.get(sessionId);
+            const status = session.status;
+            const paid = status === "succeeded";
+            // ⛔ "not finished yet" is NOT "did not work", and collapsing them costs
+            // money in the worst direction. On the 3-D Secure path the buyer returns
+            // to successUrl and the charge "settles on its own" (the API spec's own
+            // words), so they routinely arrive while the session is still
+            // `processing`. Reporting that as a failure tells someone whose card IS
+            // being charged that it did not work; they retry and pay twice.
+            //
+            // ⚠️ Expressed as "NOT a known terminal state" rather than "in a known
+            // pending set". The two agree today, but they fail in opposite directions
+            // when the server adds a state this SDK has not heard of — and one of
+            // those directions is the whole reason this function exists. An allowlist
+            // would route an unknown future state (say `requires_action`) to
+            // `not_succeeded`, i.e. tell a buyer mid-authentication that they failed.
+            // A terminal denylist routes it to `still_pending`, which is the safe
+            // direction: it says "wait for the webhook" rather than "you did not pay".
+            const reason = paid
+                ? undefined
+                : TERMINAL_SESSION_STATES.has(status)
+                    ? "not_succeeded"
+                    : "still_pending";
+            return {
+                paid,
+                signatureValid,
+                sessionId,
+                status,
+                reason,
+                // Surfaced from the AUTHENTICATED read, not the redirect URL.
+                //
+                // Omitting these was a design flaw, not an omission of convenience: we
+                // already fetch them here and then discarded them, which structurally
+                // forced every integrator back onto the buyer-controlled query string
+                // for anything beyond a boolean. Two independent reviews traced the
+                // same fake-receipt path to that gap — a buyer editing `amount` in
+                // their own return URL and screenshotting the rendered "confirmation".
+                amount: session.amount,
+                currency: session.currency,
+                transactionId: session.transactionId,
+            };
+        },
         get: async (sessionId) => {
             assertResourceId(sessionId, "sessionId");
             const { data } = await this.request("GET", `/v1/sessions/${encodeURIComponent(sessionId)}`, { reporterMethod: "sessions.get" });
@@ -1095,30 +1451,44 @@ export class VonPayCheckout {
      *      whether you have already fulfilled this order, and it keeps returning
      *      `succeeded` on a replay. Record which session IDs you have fulfilled
      *      (e.g. a UNIQUE column on the order row) and refuse to fulfil one twice.
-     * Prefer v2 (pass `expectedSuccessUrl` + `expectedKeyMode`), which is
-     * freshness- and URL-bound, or pass `{ rejectV1: true }` to refuse v1 outright
-     * once your checkout server emits v2 returns. Note: `rejectV1` only refuses
-     * v1 — it does not by itself require a valid v2 signature, so still supply the
-     * v2 options. A successful v1 verification logs a warning to this effect once
-     * per process.
+     * `acceptedSchemes` is the allowlist THIS VERIFIER will honour. It exists
+     * because the scheme is otherwise chosen by the incoming signature — i.e. by
+     * the sender — and a verifier should declare what it accepts rather than let
+     * untrusted input select its own algorithm.
+     *
+     * ⚠️ `{ acceptedSchemes: ["v2"] }` refuses the v1 SCHEME. It does not by
+     * itself require a valid v2 signature, so keep supplying the v2 options. And
+     * confirm your account already issues v2 returns before setting it — that is
+     * a server-side setting, so if your account still issues v1 this refuses
+     * EVERY return you receive.
      *
      * @param params - URL search params from the redirect (session, status, amount, currency, transaction_id, sig)
      * @param secret - Your session signing secret, NOT your API key
-     * @param options - expectedSuccessUrl (required for v2), expectedKeyMode (required for v2), maxAgeSeconds (v2 freshness, default 600), rejectV1 (refuse legacy v1 signatures)
+     * @param options - expectedSuccessUrl (required for v2), expectedKeyMode (required for v2), maxAgeSeconds (v2 freshness, default 600), acceptedSchemes (which signature schemes to honour)
+     * @throws TypeError if `acceptedSchemes` is empty or names an unknown scheme — a typo there would silently refuse every return.
      */
     static verifyReturnSignature(params, secret, options) {
+        const schemes = resolveAcceptedSchemes(options);
         const { sig, session, status, amount, currency, transaction_id } = params;
         if (!sig || !session || !status || !amount || !currency)
             return false;
+        // Scheme dispatch. Each arm is gated on the allowlist FIRST, so an
+        // unaccepted scheme is refused before any HMAC or payload work — never a
+        // partial verification, and never an advisory about a signature we did not
+        // honour.
         if (sig.startsWith("v2.")) {
+            if (!schemes.has("v2"))
+                return false;
             return VonPayCheckout.verifyReturnSignatureV2(sig, { session, status, amount, currency, transaction_id: transaction_id ?? "" }, secret, options ?? {});
         }
         // --- Legacy v1 path: plain HMAC over the 5 fields, with NO freshness or
         // success-URL/key-mode binding. A captured v1 return URL is replayable
-        // indefinitely (kaiju #425). v2 (handled above) binds iat + successUrl +
-        // keyMode and is the replay-safe path.
-        if (options?.rejectV1)
+        // indefinitely. v2 (handled above) binds iat + successUrl + keyMode and is
+        // the replay-safe path.
+        if (!schemes.has("v1")) {
+            warnV1ReturnSignatureRefused();
             return false;
+        }
         if (!/^[0-9a-f]{64}$/.test(sig))
             return false;
         const data = [session, status, amount, currency, transaction_id ?? ""].join(".");