@vonpay/checkout-node 0.15.1 → 1.0.0

package/README.md

@@ -95,7 +95,7 @@ Write endpoints (create / update / delete / rotate-signing-secret / send-test-ev
 
 - **Typed session / webhook / error objects** — full `CheckoutSession`, `SessionStatus`, `WebhookEvent`, `WebhookSubscription`, `WebhookEventRecord`, `VonPayError`, discriminated-union `ErrorCode`.
 - **Webhook verification** — `webhooks.constructEvent(rawBody, signatureHeader, signingSecret)` parses the `x-vonpay-signature: t=<unix>,v1=<hex>` header, verifies HMAC-SHA256 over `${t}.${rawBody}` keyed by your per-endpoint signing secret (`whsec_…`), and enforces the freshness window (≤5 min old / ≤30 sec future). Accepts multiple `v1=` entries for zero-downtime secret rotation.
-- **Signed return URL verification (v1 + v2)** — `VonPayCheckout.verifyReturnSignature()` supports both legacy v1 signatures and v2 signatures that bind `successUrl`, `keyMode`, and `iat` freshness.
+- **Return confirmation** — `client.sessions.confirmReturn(params, sessionSecret)` verifies the signature **and** confirms server-side that the payment succeeded, returning `{ paid, signatureValid, status, reason }`. **Use this, and branch on `paid`.** ⚠️ `verifyReturnSignature()` is the low-level primitive: it proves the message is AUTHENTIC, and a **declined payment is signed just as validly**, so a `true` from it is not proof of payment. ⚠️ `reason === "still_pending"` means the charge is in flight (the ordinary 3-D Secure case) — show a neutral "confirming your payment", never a failure. ⚠️ `paid: true` still does not mean safe to fulfil: record which session IDs you have already fulfilled, and prefer fulfilling from the `session.succeeded` webhook.
 - **Auto-retry** — exponential backoff on 429 / 5xx with `Retry-After` header support.
 - **Request ID tracing** — every response includes `X-Request-Id` for support tickets.
 - **Rate-limit info** — parsed from response headers into `VonPayError.rateLimit`.

package/dist/client.d.ts

@@ -1,5 +1,8 @@
-import type { VonPayCheckoutConfig, CreateSessionParams, CheckoutSession, SessionStatus, DryRunResult, WebhookEvent, HealthStatus, RequestOptions, ReturnParams, PaymentIntent, CreatePaymentIntentParams, CapturePaymentIntentParams, Capabilities, Refund, CreateRefundParams, Token, CreateTokenParams, WebhookSubscription, ListWebhookSubscriptionsParams, WebhookSubscriptionsList, WebhookEventRecord } from "./types.js";
-/** Test-only: reset the one-time v1 replay warning. Underscore-prefixed; not public API. */
+import type { VonPayCheckoutConfig, CreateSessionParams, CheckoutSession, SessionStatus, DryRunResult, WebhookEvent, HealthStatus, RequestOptions, ReturnOutcome, ReturnParams, PaymentIntent, CreatePaymentIntentParams, CapturePaymentIntentParams, Capabilities, Refund, CreateRefundParams, Token, CreateTokenParams, WebhookSubscription, ListWebhookSubscriptionsParams, WebhookSubscriptionsList, WebhookEventRecord } from "./types.js";
+export declare const KNOWN_RETURN_SCHEMES: readonly ["v1", "v2"];
+export type ReturnScheme = (typeof KNOWN_RETURN_SCHEMES)[number];
+export declare const DEFAULT_RETURN_SCHEMES: readonly ReturnScheme[];
+/** Test-only: reset the one-time return-signature advisories. Not public API. */
 export declare function __resetReturnSignatureWarning(): void;
 /** Test-only: reset the warn-once latch so each case can assert on it. */
 export declare function __resetDeprecationWarningsForTests(): void;
@@ -88,6 +91,57 @@ export declare class VonPayCheckout {
     sessions: {
         create: (params: CreateSessionParams, options?: RequestOptions) => Promise<CheckoutSession>;
         /** 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.
+         *
+         * Sequence: verify the signature, then read 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, and it is fresher. An
+         * unauthenticated return never reaches the network, so a forged URL cannot
+         * make your server issue API calls.
+         *
+         * ⚠️ **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: (params: ReturnParams | Record<string, string>, secret: string, options?: {
+            expectedSuccessUrl?: string;
+            expectedKeyMode?: "test" | "live";
+            maxAgeSeconds?: number;
+            acceptedSchemes?: readonly ReturnScheme[];
+            /**
+             * @deprecated Use `acceptedSchemes: ["v2"]`. Accepted here so a merchant
+             * who already hardened against v1 can move to this helper without
+             * dropping that protection — without it, the documented migration is
+             * blocked for exactly the most security-conscious integrators.
+             */
+            rejectV1?: boolean;
+        }) => Promise<ReturnOutcome>;
         get: (sessionId: string) => Promise<SessionStatus>;
         validate: (params: CreateSessionParams) => Promise<DryRunResult>;
     };
@@ -216,26 +270,37 @@ export declare 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: ReturnParams | Record<string, string>, secret: string, options?: {
         expectedSuccessUrl?: string;
         expectedKeyMode?: "test" | "live";
         maxAgeSeconds?: number;
         /**
-         * When true, reject legacy v1 signatures outright (return `false`) and
-         * only accept replay-safe v2 signatures. v1 binds no timestamp and no
-         * success-URL/key-mode, so a captured v1 return URL replays indefinitely
-         * (kaiju #425). Default `false` for backward compatibility.
+         * Signature schemes this verifier accepts. Defaults to `["v1", "v2"]`,
+         * preserving existing behaviour. Pass `["v2"]` to refuse the replayable
+         * legacy scheme. Mirrors Python's `accepted_schemes`.
+         */
+        acceptedSchemes?: readonly ReturnScheme[];
+        /**
+         * @deprecated Since 2026-08-17. Use `acceptedSchemes: ["v2"]` instead.
+         * Still honoured (it published in 0.12.0 on 2026-07-01, so upgrades must
+         * not break) and removed in the next major. An explicit `acceptedSchemes`
+         * takes precedence over this.
          */
         rejectV1?: boolean;
     }): boolean;

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

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,115 @@ 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 meaning "not finished yet", as distinct from "did not work".
+ * The server sits in `processing` while a charge is in flight, and on the 3-D
+ * Secure path the buyer returns to successUrl *before* settlement.
+ */
+const PENDING_SESSION_STATES = new Set(["pending", "processing"]);
+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");
+}
+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");
 }
-/** Test-only: reset the one-time v1 replay warning. Underscore-prefixed; not public API. */
+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;
+}
+/**
+ * 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 +788,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 +838,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 +854,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 +885,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}`,
@@ -790,6 +940,7 @@ export class VonPayCheckout {
                 body: nestMirrorUnderMetadata(buildSnakeBodyOpaqueMetadata(prepared)),
                 idempotencyKey: options?.idempotencyKey,
                 reporterMethod: "paymentIntents.create",
+                movesMoney: true,
             });
             return paymentIntentFromWire(data);
         },
@@ -814,6 +965,7 @@ export class VonPayCheckout {
                 body,
                 idempotencyKey: options?.idempotencyKey,
                 reporterMethod: "paymentIntents.capture",
+                movesMoney: true,
             });
             return paymentIntentFromWire(data);
         },
@@ -854,6 +1006,7 @@ export class VonPayCheckout {
                 body: buildSnakeBodyOpaqueMetadata(params),
                 idempotencyKey: options?.idempotencyKey,
                 reporterMethod: "refunds.create",
+                movesMoney: true,
             });
             return refundFromWire(data);
         },
@@ -892,6 +1045,73 @@ 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.
+         *
+         * Sequence: verify the signature, then read 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, and it is fresher. An
+         * unauthenticated return never reaches the network, so a forged URL cannot
+         * make your server issue API calls.
+         *
+         * ⚠️ **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, secret, options) => {
+            const signatureValid = VonPayCheckout.verifyReturnSignature(params, secret, options);
+            if (!signatureValid) {
+                return {
+                    paid: false,
+                    signatureValid: false,
+                    reason: "invalid_signature",
+                };
+            }
+            const sessionId = params.session ?? "";
+            // 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 { status } = await this.sessions.get(sessionId);
+            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.
+            const reason = paid
+                ? undefined
+                : PENDING_SESSION_STATES.has(status)
+                    ? "still_pending"
+                    : "not_succeeded";
+            return { paid, signatureValid: true, sessionId, status, reason };
+        },
         get: async (sessionId) => {
             assertResourceId(sessionId, "sessionId");
             const { data } = await this.request("GET", `/v1/sessions/${encodeURIComponent(sessionId)}`, { reporterMethod: "sessions.get" });
@@ -1095,30 +1315,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(".");