@code-collective/booking-widget 1.0.12 → 1.0.14

package/src/lib/checkout-payment-flow.svelte.ts

@@ -0,0 +1,523 @@
+// The state of one shopper's current Peach payment attempt, from minting it through to a settled outcome -
+// split out of CheckoutModal.svelte because this was the single largest, most tangled concern in that file
+// (roughly a third of it): initiating a payment, resuming one after a reload, releasing/reporting a dead or
+// declined attempt, and polling the cart's status until it settles. None of it needs the cart's own item list,
+// the contact form, or the wizard's cart/edit views - only the current payment attempt and where it stands.
+
+import type { BookingApi } from './api';
+import { ApiError, isInvalidCart, isPaymentPending, isPaymentSettled } from './api';
+import type {
+  CheckoutCartConfirmResultDto,
+  CheckoutCartDetailDto,
+  CheckoutCartPaymentInitiationDto,
+  OctoContact,
+  PaymentSdkResult,
+  PaymentStatus,
+} from './client-types';
+import { cartDeadline } from './cart-expiry';
+import { postMessage } from './messages';
+import { forgetPaymentAttempt, recallPaymentAttempt, rememberPaymentAttempt } from './payment-attempt';
+
+// Peach's webhook is typically near-instant, but is a genuinely separate async delivery from the card charge
+// itself, and confirming the bookings behind it means a call per item to a supplier. 90s at 1.5s intervals
+// covers both without making a shopper whose payment already succeeded wait an unreasonable time to see it.
+// Running out is not a failure - see runStatusPoll.
+const StatusPollIntervalMs = 1500;
+const StatusPollTimeoutMs = 90_000;
+
+export interface CheckoutPaymentFlowDeps {
+  getApi: () => BookingApi;
+  getCart: () => CheckoutCartDetailDto;
+  // Re-reads the cart from the server and applies it; false (with the modal already closed) when the server
+  // no longer has it. Shared with cart-item editing, which needs the exact same behaviour - owned by the
+  // parent so this module does not have to reimplement "close on a gone cart" itself.
+  reloadCart: () => Promise<boolean>;
+  notifyCartUpdated: (cart: CheckoutCartDetailDto) => void;
+  // Paying does not move the cart's clock, but a still-there answer given between the parent's last read and
+  // the pay click could have, so payNow re-reads the deadline rather than assuming it. Best-effort by design
+  // (see CheckoutModal's own former comment) - a failed re-read just keeps the older deadline.
+  refreshDeadlineAfterPay: () => void;
+  setView: (view: 'contact' | 'payment' | 'result') => void;
+  close: () => void;
+  onOrderConfirmed: () => void;
+}
+
+export interface CheckoutPaymentFlow {
+  readonly paymentResult: CheckoutCartPaymentInitiationDto | null;
+  readonly isPaying: boolean;
+  readonly payError: string | null;
+  readonly isConfirming: boolean;
+  // A straight readout onto ResultView's own outcome union - see the derivation below for what each case
+  // means and why 'partial' has to stay distinct from both 'pending' and a plain failure.
+  readonly resultStatus: PaymentStatus | null;
+  payNow(contact: OctoContact): Promise<void>;
+  onPaymentComplete(result: PaymentSdkResult): Promise<void>;
+  onPaymentTimedOut(): Promise<void>;
+  resumeInterruptedPayment(): Promise<void>;
+  retry(): void;
+  checkStatusAgain(): Promise<void>;
+  /** Aborts any in-flight poll - call from onDestroy so a gone component cannot keep hitting the gateway. */
+  dispose(): void;
+}
+
+export function createCheckoutPaymentFlow(deps: CheckoutPaymentFlowDeps): CheckoutPaymentFlow {
+  let paymentResult = $state<CheckoutCartPaymentInitiationDto | null>(null);
+  // What polling the cart's status actually established - not a plain success/failure boolean, because
+  // "payment succeeded but this gateway couldn't confirm it in time" and "payment itself never went through"
+  // need different copy and different actions (see resultStatus and runStatusPoll's own remarks). null while
+  // still in flight.
+  let confirmOutcome = $state<'success' | 'pending' | 'partial' | 'notCharged' | null>(null);
+  // Cancels an in-flight poll - on dispose, and when a retry supersedes it. Without this the old loop keeps
+  // running after the caller is gone and can write its own stale answer over the new attempt's.
+  let activePoll: AbortController | null = null;
+  let isConfirming = $state(false);
+  let isPaying = $state(false);
+  let payError = $state<string | null>(null);
+
+  // The cart's one clock ran out while Peach's card form was open (CartExpiryGuard cannot act on that itself -
+  // the server exempts a cart with a payment in flight from expiry so a landing charge can still be confirmed).
+  // The shopper should see the cart expire here like anywhere else, so the attempt is torn down through the
+  // same Peach-verified abandon a cancel uses: a charge Peach reports as landed or still in flight is never torn
+  // down (releaseAbandonedAttempt routes those to the confirm loop instead), and an attempt Peach confirms dead
+  // reopens the cart on its already-past deadline, so the reload that follows gets a 401 and the guard's
+  // payment:ended re-check shows "Your cart has expired". Nothing to do if no attempt is open right now.
+  async function onPaymentTimedOut(): Promise<void> {
+    if (!paymentResult) return;
+    await releaseAbandonedAttempt();
+  }
+
+  // A reload mid-payment: the server still holds this cart in AwaitingPaymentConfirmation for the Peach
+  // checkout recorded before the reload, and will refuse every edit and a second payCart until that attempt
+  // is settled or abandoned. Where to land depends on how far the shopper got before the reload, and only the
+  // server knows: Peach's form may have completed a moment earlier - a charge, or a decline the server reads
+  // straight back from Peach's status endpoint, since Peach sends no webhook for one - so it is asked once
+  // first, and a recorded outcome is shown exactly as it would have been without the reload. Only "not paid"
+  // puts the shopper back on that same card form, whose Peach handlers then route as they do without a
+  // reload: a completed charge confirms, a cancel/expiry/error abandons the attempt and reopens the cart.
+  // Same resume as payNow's own paymentResult short-cut.
+  async function resumeInterruptedPayment(): Promise<void> {
+    const interruptedAttempt = recallPaymentAttempt(deps.getApi().cartToken);
+    if (!interruptedAttempt) return;
+    paymentResult = interruptedAttempt;
+    // Posted before the answer is known, as payNow does: CartExpiryGuard must treat the attempt as in flight
+    // whichever screen it ends up on, and a decline's own payment:ended (releaseDeclinedAttempt) then reads the
+    // same as it does without a reload.
+    postMessage({ type: 'payment:started' });
+    if (await resumeOntoRecordedOutcome()) return;
+    deps.setView('payment');
+    // The guard's watcher fires once per deadline and may already have done so before this flow existed (a
+    // reload after the clock ran out, or checkout reopened late). Nothing else would tear the attempt down
+    // then; the shopper would land on a card form for a cart that is already gone.
+    if (cartDeadline(deps.getCart()).getTime() <= Date.now()) void onPaymentTimedOut();
+  }
+
+  // Where a reload lands. One status read decides it: a settled attempt (a charge, a supplier-side partial
+  // failure, or a decline) goes straight to the result screen; a confirmation in flight joins the ordinary
+  // poll to read its outcome; a cart the server no longer has closes the modal, as a 401 does everywhere else
+  // here. Anything still genuinely unresolved - a shopper who never submitted the card, or one who reloaded
+  // mid-3-D Secure, which cannot be told apart from here (PR 8447 review) - goes back to the card form, since
+  // that is Peach's own form for this same checkoutId rather than a fresh charge. An unreachable server is
+  // treated the same way, rather than parking them on a screen telling them not to pay again for a card they
+  // may never have submitted.
+  async function resumeOntoRecordedOutcome(): Promise<boolean> {
+    isConfirming = true;
+    deps.setView('result');
+
+    let status;
+    try {
+      status = await deps.getApi().getCartStatus();
+    } catch (e) {
+      isConfirming = false;
+      if (isInvalidCart(e)) {
+        deps.close();
+        return true;
+      }
+      return false;
+    }
+
+    if (status.cartStatus === 'confirmed') {
+      recordConfirmation(status.confirmResult ?? { items: [] });
+      isConfirming = false;
+      return true;
+    }
+
+    if (status.paymentOutcome === 'failed' || status.paymentOutcome === 'abandoned') {
+      confirmOutcome = 'notCharged';
+      await releaseDeclinedAttempt();
+      isConfirming = false;
+      return true;
+    }
+
+    // Paid or confirming: the money is in and the bookings are being turned into a sale right now.
+    if (status.cartStatus === 'paid' || status.cartStatus === 'confirming') {
+      await runStatusPoll();
+      return true;
+    }
+
+    isConfirming = false;
+    return false;
+  }
+
+  // Tells the server this attempt is over so a fresh payCart will be accepted - without it the cart stays
+  // AwaitingPaymentConfirmation, no webhook ever comes for a checkout nobody submitted, and the only thing a
+  // retry could do is reopen a Peach session that is already dead. 'settled' means Peach has this attempt as
+  // paid, or still in flight (PAYMENT_PENDING) - either way the cart must not be reopened, and the confirm loop
+  // already handles "not paid yet" by landing on the pending screen, so both take the same path here; 'failed'
+  // means the server could not be reached or refused for another reason, in which case paymentResult is kept
+  // so payNow falls back to resuming the same still-open attempt.
+  // Two endpoints, one guard behind them: a shopper backing out or a clock running out is an abandon, while
+  // Peach's own SDK reporting a failure carries a reason worth recording against the attempt - and for a card
+  // declined inside the checkout, where Peach sends no webhook, that payload is the only place its code exists.
+  async function abandonPaymentAttempt(checkoutId: string, failure?: PaymentSdkResult):
+    Promise<'abandoned' | 'settled' | 'failed'> {
+    try {
+      if (failure) {
+        await deps.getApi().reportPaymentFailure(checkoutId, failure.resultCode, failure.description);
+      } else {
+        await deps.getApi().abandonPayment(checkoutId);
+      }
+      return 'abandoned';
+    } catch (e) {
+      return isPaymentSettled(e) || isPaymentPending(e) ? 'settled' : 'failed';
+    }
+  }
+
+  async function payNow(contact: OctoContact): Promise<void> {
+    // paymentResult is only ever still set here when the previous attempt could not be torn down: the abandon
+    // call failed (Peach unreachable), or Peach reported the charge as settled or still in flight. Every other
+    // way out of PaymentPage - cancel, expiry, error - releases the attempt and clears paymentResult, and the
+    // next Pay Now creates a NEW Peach checkout. That is deliberate, not waste: Peach's SDK will not re-render
+    // a checkoutId it has already unmounted, a cancelled checkout is finished on Peach's side, and the total is
+    // frozen at creation so an edited cart needs a new one regardless.
+    //
+    // Which is exactly why this asks the server to release the attempt once more before anything else, rather
+    // than resuming it on the spot as it used to: that put the shopper back on a card form for a checkoutId
+    // Peach was done with, and Peach's own unrecoverable-error card in front of them instead of ours (PR 8447
+    // review). A release that succeeds leaves the cart Open and falls through to a genuinely new checkout. One
+    // that reports it has taken over - the charge turned out to have settled after all, or the cart is gone -
+    // owns what happens next, and paying again is the one thing that must not happen. Only a release that fails
+    // again leaves the server still holding the attempt (a second payCart would be refused with a 409), and
+    // then resuming that same card form really is the only move left.
+    if (paymentResult) {
+      isPaying = true;
+      try {
+        if (!(await releaseAbandonedAttempt())) return;
+      } catch {
+        // reloadCart rethrows anything that is not the cart being gone, and releaseAbandonedAttempt re-reads
+        // the cart on its way out. The attempt's own outcome is already decided by then, so the two branches
+        // below still route correctly on it; all a failed re-read costs is a countdown read a moment ago.
+      } finally {
+        isPaying = false;
+      }
+
+      if (paymentResult) {
+        deps.setView('payment');
+        return;
+      }
+    }
+
+    isPaying = true;
+    payError = null;
+    try {
+      paymentResult = await deps.getApi().payCart(contact);
+      rememberPaymentAttempt(deps.getApi().cartToken, {
+        checkoutId: paymentResult.checkoutId ?? '',
+        entityId: paymentResult.entityId ?? '',
+      });
+      deps.setView('payment');
+      postMessage({ type: 'payment:started' });
+      deps.refreshDeadlineAfterPay();
+    } catch (e) {
+      if (isInvalidCart(e)) {
+        // The cart expired between CartExpiryGuard's last tick and this click - there is nothing left to pay for.
+        deps.close();
+        return;
+      }
+
+      // PayCheckoutCartCommandHandler's own error-mapping switch: 502 means Peach itself (or the network
+      // path to it) failed before a checkout could even be created - no charge was attempted and the cart is
+      // still Open, so this is always safe to retry. Every other status (400/409) reflects a cart/contact state
+      // the shopper can't fix by only retrying the same request, but there is no more specific action to suggest
+      // here either - either way, without this catch the rejection was previously unhandled and the shopper
+      // saw no indication anything had gone wrong at all.
+      const status = e instanceof ApiError ? e.status : null;
+      payError = status === 502
+        ? 'Unable to start payment right now. Please try again.'
+        : 'Something went wrong starting your payment. Please try again.';
+    } finally {
+      isPaying = false;
+    }
+  }
+
+  async function onPaymentComplete(result: PaymentSdkResult): Promise<void> {
+    // Neither cancelled, expired nor error ever reached a real charge - Peach's own SDK is reporting that the
+    // checkout itself didn't go through (the shopper backed out, session timeout, a declined card, a 3DS
+    // failure, a client-side error), not that a successful charge's confirmation is in question. That
+    // distinction matters: the confirm path at the bottom is only reachable once onCompleted has fired, which
+    // Peach does for a settled outcome of either kind - a charge, or a decline (the server reads that back from
+    // Peach's status endpoint, since Peach sends no webhook for one, and answers PAYMENT_FAILED). So "try again"
+    // there is only ever offered once the server itself has said nothing was charged. Here nothing was charged,
+    // so the attempt is abandoned server-side (a retry then starts a genuinely new Peach checkout instead of
+    // reopening this dead one) and re-opening the card form is exactly correct.
+    if (result.status === 'cancelled' || result.status === 'expired' || result.status === 'error') {
+      // Only the two genuine failures carry Peach's own reason; a shopper backing out has none to give.
+      const failure = result.status === 'cancelled' ? undefined : result;
+      if (!(await releaseAbandonedAttempt(failure))) return;
+    }
+
+    if (result.status === 'cancelled') {
+      deps.setView('contact');
+      return;
+    }
+
+    if (result.status === 'expired' || result.status === 'error') {
+      confirmOutcome = 'notCharged';
+      isConfirming = false;
+      deps.setView('result');
+      return;
+    }
+
+    // Peach's form has reported the checkout complete, which covers a declined card as much as a charged one.
+    // The server is asked once to go and find out which, because no webhook is coming for a decline; the poll
+    // below then reads whatever it established. Best effort - a failure here only means the answer arrives
+    // from the webhook or the sweep instead, which is exactly what the poll is already waiting for.
+    deps.setView('result');
+    try {
+      await deps.getApi().resolvePayment();
+    } catch {
+      // see above
+    }
+    await runStatusPoll();
+  }
+
+  // False when this flow has already taken over what happens next - the cart turned out to be paid and is
+  // being confirmed, or it has expired - so the caller must not route the shopper anywhere else.
+  async function releaseAbandonedAttempt(failure?: PaymentSdkResult): Promise<boolean> {
+    // Already cleared by an earlier call for this same attempt (e.g. a second Peach callback after the first
+    // already abandoned it) - nothing left to tell the server about.
+    if (!paymentResult) return await deps.reloadCart();
+
+    const abandoned = await abandonPaymentAttempt(paymentResult.checkoutId, failure);
+    if (abandoned === 'settled') {
+      deps.setView('result');
+      await runStatusPoll();
+      return false;
+    }
+
+    if (abandoned === 'abandoned') {
+      paymentResult = null;
+      forgetPaymentAttempt();
+    }
+
+    // The cart is Open again, or the abandon call itself failed and the shopper is being routed back to
+    // contact/result regardless. payment:ended tells CartExpiryGuard to stop treating a payment as in flight -
+    // without it the guard never prompts or expires again for the rest of the page's life - and goes out last so
+    // the guard re-checks the deadline it ends up with. But it is only true when the attempt is actually over:
+    // released here, or the cart gone regardless (a 401 on the reload - the payment window had already run out).
+    // After a failed abandon the server still holds the cart awaiting payment for this attempt, and the guard's
+    // own timeout fallback must stay armed to finish the job, so the guard is told nothing.
+    const reloaded = await deps.reloadCart();
+    if (reloaded) deps.notifyCartUpdated(deps.getCart());
+    if (abandoned === 'abandoned' || !reloaded) postMessage({ type: 'payment:ended' });
+    return reloaded;
+  }
+
+  // Back to the contact form rather than straight to 'payment'. Every outcome that offers Try Again is one
+  // where nothing was charged, and in all but one of them the attempt has already been released (a decline
+  // here, a Peach-reported expiry or error in onPaymentComplete) - so there is no card form left to return to:
+  // Peach's SDK will not re-render a checkoutId it has unmounted, and a checkout that reached a decline is
+  // finished on Peach's side regardless. Contact is where payNow creates a genuinely new one, with the
+  // shopper's details still filled in (they live in the parent component, not in ContactForm) so paying again -
+  // on another card, if that is what the decline was about - is one click away. The exception needs no handling
+  // of its own: after an abandon the server refused, the attempt is still open and payNow's own paymentResult
+  // short-cut resumes that same one from here, which is exactly what it is there for.
+  function retry(): void {
+    deps.setView('contact');
+  }
+
+  // The declined counterpart to releaseAbandonedAttempt, and deliberately without its abandon call: the server
+  // has already resolved this attempt itself - a decline reached it (Peach's webhook, or its own read of Peach's
+  // status endpoint on the status poll, since Peach sends no webhook for a declined card), which is what moved
+  // the cart to Failed - so there is nothing left to report. AbandonPaymentAsync answers a Failed cart with
+  // AlreadyOpen, an explicit no-op.
+  // Clearing the attempt is what makes Try Again start a NEW Peach checkout instead of reopening the dead one:
+  // payNow resumes paymentResult when it is still set, and resumeInterruptedPayment would land a reload
+  // straight back on that same spent card form.
+  async function releaseDeclinedAttempt(): Promise<void> {
+    paymentResult = null;
+    forgetPaymentAttempt();
+    // Failed is live and still payable again - the decline leaves the cart's one clock exactly where it was -
+    // so this re-reads whatever time Try Again actually has left rather than the deadline from before the card
+    // form. A cart whose clock ran out meanwhile 401s here and closes the modal, same as anywhere else. Any
+    // other failure of the re-read must not escape: this runs inside resumeOntoRecordedOutcome's own catch,
+    // from where a throw would strand the shopper on "Verifying payment..." with no button at all, and the
+    // decline itself is already recorded - Try Again simply counts down from the older deadline (PR 8447 review).
+    try {
+      if (await deps.reloadCart()) deps.notifyCartUpdated(deps.getCart());
+    } catch {
+      // see above
+    }
+    // Without this CartExpiryGuard keeps treating a payment as in flight for the rest of the page's life, so it
+    // never prompts or expires this cart again.
+    postMessage({ type: 'payment:ended' });
+  }
+
+  // One status read, interpreted - the single place that decides what a given cart state means, shared by the
+  // automatic poll and the manual on-demand recheck. 'settled' has recorded the outcome (success, a
+  // supplier-side partial failure, or a decline); 'waiting' means the backend has not finished and another
+  // read is worth making.
+  async function pollOnce(signal?: AbortSignal): Promise<'settled' | 'waiting'> {
+    let status;
+    try {
+      status = await deps.getApi().getCartStatus();
+    } catch (e) {
+      // Checked on this path too: an aborted poll must not write even a 'pending' over the outcome of the
+      // attempt that superseded it.
+      if (signal?.aborted) return 'settled';
+      // A cart the server no longer has is not something to pay for again - by this point it is a paid cart it
+      // cannot show us. Anything else says nothing about the payment (a dropped connection, a gateway blip),
+      // so the loop simply tries again; only running out of time settles it.
+      if (isInvalidCart(e)) {
+        confirmOutcome = 'pending';
+        return 'settled';
+      }
+      return 'waiting';
+    }
+
+    // Checked after the await, not just before it: a retry or an unmount can land while this request is in
+    // flight, and everything below writes state - including firing onOrderConfirmed, which the host must not
+    // receive twice for one order.
+    if (signal?.aborted) return 'settled';
+
+    if (status.cartStatus === 'confirmed') {
+      recordConfirmation(status.confirmResult ?? { items: [] });
+      return 'settled';
+    }
+
+    // A settled non-success attempt. The server has already asked Peach directly if no webhook arrived (Peach
+    // sends none for a card declined inside a checkout), so this is a real answer rather than a guess, and the
+    // cart is payable again - nothing was captured.
+    if (status.paymentOutcome === 'failed' || status.paymentOutcome === 'abandoned') {
+      confirmOutcome = 'notCharged';
+      // Clears the spent Peach checkout so Try Again mints a new one rather than reopening a dead card form,
+      // and re-reads the cart's remaining time. The server has already resolved this attempt itself, so there
+      // is nothing left to report to it.
+      await releaseDeclinedAttempt();
+      return 'settled';
+    }
+
+    // Everything else - awaitingPaymentConfirmation, paid, or confirming - resolves on its own.
+    return 'waiting';
+  }
+
+  function recordConfirmation(result: CheckoutCartConfirmResultDto): void {
+    // An empty item list is not a success - a confirmed cart always reports one result per item, so nothing to
+    // check means the result is not the shape we expect and must not read as "all good".
+    const allOk = result.items.length > 0 && result.items.every((i) => i.statusCode >= 200 && i.statusCode < 300);
+    confirmOutcome = allOk ? 'success' : 'partial';
+    // Notifies the host (order value/currency for analytics, clearing the stored cart token) without closing
+    // the modal - the shopper still needs to see the success screen, and only dismisses it themselves via
+    // ResultView's Done button, which is the one thing that posts modal:close.
+    if (allOk) {
+      deps.onOrderConfirmed();
+    }
+  }
+
+  // Runs after every terminal SDK outcome, and would run just as correctly if the SDK said nothing at all: the
+  // cart's own status is the single source of truth, so the browser never has to guess whether money moved.
+  // Timing out is not a failure - it means the backend has not finished yet, which is what the pending screen
+  // is for. The webhook (or the stuck-payment sweep behind it) settles the cart either way, whether or not this
+  // tab is still open to see it.
+  async function runStatusPoll(): Promise<void> {
+    isConfirming = true;
+    confirmOutcome = null;
+
+    const deadline = Date.now() + StatusPollTimeoutMs;
+    const poll = new AbortController();
+    activePoll?.abort();
+    activePoll = poll;
+
+    while (!poll.signal.aborted) {
+      if (await pollOnce(poll.signal) === 'settled') break;
+
+      if (Date.now() + StatusPollIntervalMs > deadline) {
+        confirmOutcome = 'pending';
+        break;
+      }
+
+      await pollDelay(StatusPollIntervalMs, poll.signal);
+    }
+
+    // A poll superseded by a newer one (a retry) must not write its own stale answer over it.
+    if (!poll.signal.aborted) {
+      isConfirming = false;
+      activePoll = null;
+    }
+  }
+
+  function pollDelay(ms: number, signal: AbortSignal): Promise<void> {
+    return new Promise((resolve) => {
+      const timer = setTimeout(resolve, ms);
+      signal.addEventListener('abort', () => { clearTimeout(timer); resolve(); }, { once: true });
+    });
+  }
+
+  // A single on-demand recheck for the 'pending' screen's "Check Again" button - deliberately not another full
+  // runStatusPoll, which would re-impose its own wait on someone who is already actively engaged and can just
+  // click again.
+  async function checkStatusAgain(): Promise<void> {
+    isConfirming = true;
+    if (await pollOnce() === 'waiting') {
+      confirmOutcome = 'pending';
+    }
+    isConfirming = false;
+  }
+
+  // A straight readout of confirmOutcome onto ResultView's own outcome union, which now carries one of each.
+  // 'partial' - the payment succeeded but this gateway could not confirm every item - keeps an outcome of its
+  // own the whole way through: it is a real problem worth surfacing distinctly from 'pending' (which resolves
+  // on its own), and it must never reach the shopper as "Payment Failed", because their card was charged.
+  // ResultView owns the wording for it, as it already did for 'successful' and 'pending'.
+  const resultStatus = $derived<PaymentStatus | null>(
+    isConfirming
+      ? null
+      : confirmOutcome === 'success'
+        ? { outcome: 'successful' as const }
+        : confirmOutcome === 'pending'
+          ? { outcome: 'pending' as const }
+          : confirmOutcome === 'partial'
+            ? { outcome: 'partial' as const }
+            : confirmOutcome === 'notCharged'
+              ? {
+                  outcome: 'failed' as const,
+                  resultDescription: 'Your payment could not be completed. Please try again.',
+                  retryPayment: true,
+                }
+              : null,
+  );
+
+  return {
+    get paymentResult() {
+      return paymentResult;
+    },
+    get isPaying() {
+      return isPaying;
+    },
+    get payError() {
+      return payError;
+    },
+    get isConfirming() {
+      return isConfirming;
+    },
+    get resultStatus() {
+      return resultStatus;
+    },
+    payNow,
+    onPaymentComplete,
+    onPaymentTimedOut,
+    resumeInterruptedPayment,
+    retry,
+    checkStatusAgain,
+    dispose: () => activePoll?.abort(),
+  };
+}

package/src/lib/client-types.ts

@@ -18,22 +18,38 @@ export type CheckoutCartItemDetailDto = S['CheckoutCartItemDetailDto'];
 export type CheckoutAddCartItemDto = S['CheckoutAddCartItemDto'];
 export type CheckoutCartItemAddedDto = S['CheckoutCartItemAddedDto'];
 export type CheckoutCartPaymentInitiationDto = S['CheckoutCartPaymentInitiationDto'];
+export type CheckoutCartStatusDto = S['CheckoutCartStatusDto'];
 export type CheckoutCartConfirmResultDto = S['CheckoutCartConfirmResultDto'];
 export type CheckoutCartConfirmItemResultDto = S['CheckoutCartConfirmItemResultDto'];
 export type OctoContact = S['OctoContact'];
 
 // Client-side types
-export type PaymentOutcome = 'successful' | 'pending' | 'failed' | 'cancelled';
+
+// What PaymentPage hands back when Peach's embedded SDK reaches a terminal state. The failure callbacks carry
+// a payload describing what went wrong; it used to be discarded, which left the backend with no way to record
+// why an attempt failed - and for a card declined inside the checkout, where Peach sends no webhook, that
+// payload is the only place the decline's own code exists at all.
+export interface PaymentSdkResult {
+  status: 'completed' | 'cancelled' | 'expired' | 'error';
+  resultCode?: string;
+  description?: string;
+}
+
+// 'partial' is its own outcome rather than a kind of 'failed' because the shopper's card WAS charged: the
+// payment succeeded and only some of the booking's items could be confirmed afterwards. It gets a heading of
+// its own in ResultView, since "Payment Failed" printed over the words "Your payment succeeded" invites
+// exactly the wrong reaction - paying again elsewhere, or charging back a payment that did go through.
+export type PaymentOutcome = 'successful' | 'pending' | 'partial' | 'failed' | 'cancelled';
 
 export interface PaymentStatus {
   outcome: PaymentOutcome;
   resultCode?: string;
   resultDescription?: string;
-  // Only meaningful for outcome 'failed'. A card that was actually charged - which is every 'failed' this
-  // gateway produces once confirmation itself is what failed, not the payment - must never be offered a
-  // "try again" that re-opens the card form, since the shopper would be charged a second time for a booking
-  // that already has their money against it. Defaults true (the ordinary declined/expired/errored case,
-  // where nothing was charged and retrying is exactly correct) so existing callers need not set it.
+  // Only meaningful for outcome 'failed', and only for a 'failed' that nonetheless took the shopper's money:
+  // it must never be offered a "try again" that re-opens the card form, since they would be charged a second
+  // time for a booking that already has their money against it. Defaults true (the ordinary declined/expired/
+  // errored case, where nothing was charged and retrying is exactly correct) so existing callers need not set
+  // it. The confirm-partial case this was first introduced for now carries its own 'partial' outcome.
   retryPayment?: boolean;
 }