Finish and recover paid checkouts safely

scripts/mutation/equivalent-mutants.txt

@@ -30,6 +30,9 @@
 # `x ?? F` vs `x || F` differ only when x is falsy-but-not-null; these are all
 # cases where x can't be such a value, or F equals the only one it can be.
 src/shared/checkout-pricing.ts:85:35  ?? → ||    # Map<number,number> sum: 0 ?? 0 === 0 || 0
+src/shared/booking-lines.ts:145:40  ?? → ||    # packageGroupId is undefined, 0, or a positive id; both return 0 for the only falsy value
+src/shared/sumup.ts:262:18  ?? → ||    # withClient returns true|null here; the false fallback is identical for null
+src/shared/sumup.ts:301:37  ?? → ||    # keyMode is "live", "test", or null; present values are always truthy
 src/shared/checkout-pricing.ts:334:41  ?? → ||   # intent.modifiers: an array is always truthy
 src/shared/logistics-filter.ts:22:35  ?? → ||    # raw: string|null, only falsy string "" === fallback ""
 src/shared/config.ts:150:39  ?? → ||    # getEnv(): string|undefined, only falsy string "" === fallback ""

src/features/admin/attendee-refunds.ts

@@ -132,6 +132,9 @@ const handleAttendeeRefund = verifiedAttendeeAction(
       { attendee: data.attendee, references },
       listingId,
     );
+    if (refunded.outcome === "pending") {
+      return refundError(attendeeId, t("error.refund_pending"), returnUrl);
+    }
     if (refunded.outcome !== "refunded") {
       return refundError(attendeeId, t("error.refund_failed"), returnUrl);
     }
@@ -196,16 +199,16 @@ const buildRefundProblemResponse = async (
   ctx: RefundResponseCtx,
 ): Promise<Response> => {
   const { listing, refundAllUrl, counts, remaining } = ctx;
-  const { refundedCount, failedCount, errorCount } = counts;
+  const { refundedCount, pendingCount, failedCount, errorCount } = counts;
   const problemCount = failedCount + errorCount;
   const errorNote =
     errorCount > 0
       ? ` (${errorCount} errored — check the activity log for details)`
       : "";
   const msg =
     remaining > 0
-      ? `${refundedCount} refund(s) succeeded, ${problemCount} failed${errorNote}. ${remaining} remaining — submit again to continue.`
-      : `${refundedCount} refund(s) succeeded, ${problemCount} failed${errorNote}. Some payments may have already been refunded.`;
+      ? `${refundedCount} refund(s) succeeded, ${pendingCount} pending, and ${problemCount} failed${errorNote}. ${remaining} remaining. Submit again to continue.`
+      : `${refundedCount} refund(s) succeeded, ${pendingCount} pending, and ${problemCount} failed${errorNote}. Some payments may have already been refunded.`;
   await logActivity(
     `Bulk refund: ${refundedCount} succeeded, ${problemCount} failed for '${listing.name}'`,
     listing.id,
@@ -219,7 +222,8 @@ const buildRefundAllResponse = async (
 ): Promise<Response> => {
   const { counts, listing, refundAllUrl, totalRefundable, remaining } = ctx;
   const refundedCount = counts.refundedCount;
-  const hasProblems = counts.failedCount + counts.errorCount > 0;
+  const hasProblems =
+    counts.pendingCount + counts.failedCount + counts.errorCount > 0;
 
   if (hasProblems) {
     return buildRefundProblemResponse({

src/features/admin/refunds/provider.ts

@@ -23,6 +23,7 @@ type MarkReturnedReferences = (
 
 export type RefundCounts = {
   refundedCount: number;
+  pendingCount: number;
   failedCount: number;
   errorCount: number;
 };
@@ -46,7 +47,8 @@ const refundReferenceAtProvider = async (
   const paymentReference = reference.reference;
   try {
     if (reference.providerRefunded) return "refunded";
-    if (await provider.refundPayment(paymentReference)) return "refunded";
+    const result = await provider.refundPayment(paymentReference);
+    if (result === "refunded" || result === "pending") return result;
     if (await provider.isPaymentRefunded(paymentReference)) return "refunded";
     logError({
       code: ErrorCode.PAYMENT_REFUND,
@@ -153,6 +155,8 @@ const tallyProviderRefund = (
   } else if (outcome === "failed") {
     counts.failedCount++;
     logBulkRefundProblem(outcome, candidate, listingId);
+  } else if (outcome === "pending") {
+    counts.pendingCount++;
   } else {
     refundedAttendees.push({
       attendeeId: candidate.attendee.id,
@@ -171,6 +175,7 @@ export const processRefundBatch = async (
   const counts: RefundCounts = {
     errorCount: 0,
     failedCount: 0,
+    pendingCount: 0,
     refundedCount: 0,
   };
   for (const group of packByReferenceCount(PROVIDER_REFUND_CONCURRENCY)(

src/features/admin/refunds/waves.ts

@@ -1,8 +1,9 @@
+import type { PaymentRefundResult } from "#shared/payments.ts";
 import type { RefundCandidate } from "./candidates.ts";
 
 /** The result of attempting to refund one charge reference (or a whole
  * candidate, once its per-reference outcomes are combined). */
-export type RefundOutcome = "refunded" | "failed" | "errored";
+export type RefundOutcome = PaymentRefundResult | "errored";
 
 /** Pack candidates into waves whose combined charge references stay within
  * `budget`, so each concurrently-processed wave issues at most ~`budget`
@@ -30,11 +31,12 @@ export const packByReferenceCount =
 
 /** Reduce a candidate's per-reference outcomes to a single outcome, worst
  * first: any errored reference errors the candidate, any failed reference
- * fails it, otherwise it is fully refunded. */
+ * fails it, any pending reference keeps it pending, otherwise it is refunded. */
 export const combineRefundOutcomes = (
   outcomes: RefundOutcome[],
 ): RefundOutcome => {
   if (outcomes.includes("errored")) return "errored";
   if (outcomes.includes("failed")) return "failed";
+  if (outcomes.includes("pending")) return "pending";
   return "refunded";
 };

src/features/api/folded-booking.ts

@@ -45,6 +45,7 @@ import {
   type CheckoutItem,
   getActivePaymentProvider,
 } from "#shared/payments.ts";
+import { createAndHandlePaidCheckout } from "#shared/staged-checkout.ts";
 import {
   type ContactInfo,
   isPaidListing,
@@ -278,11 +279,14 @@ const completeFoldedBooking = async (
     if (!available) return soldOutResponse();
     const provider = (await getActivePaymentProvider())!;
     const baseUrl = getBaseUrl(request);
-    const result = await provider.createCheckoutSession(intent, baseUrl);
-    if (!result) return checkoutFailedResponse();
-    return "error" in result
-      ? checkoutFailedResponse(result.error)
-      : checkoutResponse(result.checkoutUrl);
+    return createAndHandlePaidCheckout(
+      { baseUrl, intent, provider },
+      {
+        checkout: checkoutResponse,
+        failed: checkoutFailedResponse,
+        soldOut: soldOutResponse,
+      },
+    );
   }
   // Free, or provider-less paid (owes the full value). An owed order must record
   // its gross sale legs in the ledger at creation — the outstanding balance

src/features/api/payment-processing/cancel.ts

@@ -18,9 +18,15 @@ import { htmlResponse } from "#routes/response.ts";
 import { lineGroupIds } from "#shared/booking/signed-metadata.ts";
 import { groups } from "#shared/db/groups.ts";
 import { getListingWithCount } from "#shared/db/listings/records.ts";
-import type { ValidatedPaymentSession } from "#shared/payments.ts";
+import type {
+  PaymentProvider,
+  ValidatedPaymentSession,
+} from "#shared/payments.ts";
+import { tryCloseAndPurgeCheckoutStageBySession } from "#shared/staged-checkout.ts";
 import { paymentCancelPage } from "#templates/payment.tsx";
 
+type CancelLog = (detail: string) => void;
+
 /** The retry link for a cancelled checkout: the package group's page when the
  * order booked one package, else the (first) listing's own page. Returns null
  * (no retry link) whenever the target page would no longer serve, so a "Try
@@ -57,7 +63,7 @@ const retryHrefFor = async (
 /** Render the payment-cancelled page for a session's first listing. */
 export const cancelPageResponse = async (
   session: ValidatedPaymentSession,
-  logFailure: (detail: string) => void,
+  logFailure: CancelLog,
 ): Promise<Response> => {
   const intent = extractIntent(session);
   const listingId = intent?.items[0]?.e ?? 0;
@@ -76,3 +82,16 @@ export const cancelPageResponse = async (
   const retryHref = await retryHrefFor(intent!, listing);
   return htmlResponse(paymentCancelPage(listing, retryHref));
 };
+
+/** Close and clear a staged checkout. A paid close stays distinct so the route
+ * can process the payment. Provider errors keep the stage for scheduled retry. */
+export const closeStageForCancel = async (
+  session: ValidatedPaymentSession,
+  provider: PaymentProvider,
+  logFailure: CancelLog,
+): Promise<"error" | "kept" | "missing" | "paid" | "purged"> =>
+  tryCloseAndPurgeCheckoutStageBySession(session.id, provider, (error) =>
+    logFailure(
+      `Could not close checkout stage ${session.id}: ${String(error)}`,
+    ),
+  );

src/features/api/payment-processing/classify.ts

@@ -4,7 +4,10 @@
  * ours before anything downstream processes or refunds it.
  */
 
-import { cancelPageResponse } from "#routes/api/payment-processing/cancel.ts";
+import {
+  cancelPageResponse,
+  closeStageForCancel,
+} from "#routes/api/payment-processing/cancel.ts";
 import { extractIntent } from "#routes/api/payment-processing/metadata.ts";
 import type {
   BookingIntent,
@@ -16,6 +19,7 @@ import { ErrorCode, logError } from "#shared/logger.ts";
 import { verifyPrice } from "#shared/payment-signature.ts";
 import {
   getActivePaymentProvider,
+  type PaymentProvider,
   type ValidatedPaymentSession,
 } from "#shared/payments.ts";
 
@@ -135,10 +139,18 @@ export const validatePaidSession = async (
   // URL for every outcome, so a card decline lands here. Show the friendly
   // cancel/try-again page, not a "contact support" error.
   if (session.paymentStatus === "failed") {
-    return {
-      ok: false,
-      response: await cancelPageResponse(session, logRedirectError),
-    };
+    const closeResult = await closeStageForCancel(
+      session,
+      provider,
+      logRedirectError,
+    );
+    if (closeResult !== "paid") {
+      return {
+        ok: false,
+        response: await cancelPageResponse(session, logRedirectError),
+      };
+    }
+    return validateRefreshedPaidSession(sessionId, provider);
   }
 
   if (session.paymentStatus !== "paid") {
@@ -153,13 +165,41 @@ export const validatePaidSession = async (
     };
   }
 
+  return validateConfirmedPaidSession(session);
+};
+
+/** Re-read provider state after close reports that payment won the race. */
+export const validateRefreshedPaidSession = async (
+  sessionId: string,
+  provider: PaymentProvider,
+): Promise<SessionValidation> => {
+  const session = await provider.retrieveSession(sessionId);
+  if (session?.paymentStatus !== "paid") {
+    logRedirectError(
+      `Paid checkout not yet readable (session=${sessionId}, status=${session?.paymentStatus ?? "missing"})`,
+    );
+    return {
+      ok: false,
+      response: paymentErrorResponse(
+        "Payment verification failed. Please try again.",
+        503,
+      ),
+    };
+  }
+  return validateConfirmedPaidSession(session);
+};
+
+/** Validate a session whose provider close operation has just confirmed payment. */
+export const validateConfirmedPaidSession = async (
+  session: ValidatedPaymentSession,
+): Promise<SessionValidation> => {
   // Only a session carrying a valid price proof is provably ours. Without one we
   // cannot prove ownership (foreign instance sharing the provider, replayed or
   // corrupt data), so we neither process nor refund it — refunding an
   // unverifiable session could refund another instance's payment.
   const classified = await classifySessionIntent(session);
   if (classified === null) {
-    logRedirectError(`Unrecognized payment session (session=${sessionId})`);
+    logRedirectError(`Unrecognized payment session (session=${session.id})`);
     return {
       ok: false,
       response: paymentErrorResponse("Payment session not recognized"),