Skip to content

Booking and checkout

This is the highest-risk path in the product. Two production incidents have come out of it. Before you touch create-payment-intent, the Stripe webhook, reservation status handling or the amount check, read docs/booking-payments/architecture.md and decisions.md in the repo.

  1. Hold. Adding an item calls createHold, which takes pg_advisory_xact_lock(hashtext(id)) and inserts the reservation in the same transaction. Reservations start as held with an expiry.
  2. Checkout. POST /api/create-payment-intent recomputes the total from the held reservations — the client total is never trusted — then creates or reuses the PaymentIntent and claims the cart.
  3. Webhook. payment_intent.succeeded turns the PaymentIntent into a booking. payments.stripe_payment_intent_id is unique, because Stripe redelivers.
  4. Cleanup. The cleanup-expired cron expires stale holds and sends the abandonment email.

Three invariants hold it together:

  • One cart is fulfilled by exactly one PaymentIntent. Anything else is real money — record it, but never create a second booking.
  • A succeeded PaymentIntent always leaves a row: a booking with a payment, or an orphan payment flagged for review. Never nothing.
  • The webhook never throws on a structural problem. A 500 makes Stripe retry for three days against a condition that will not resolve.
Item Window
Signing slot 15 minutes
Entry ticket 15 minutes
Comic cover 15 minutes
Booth 60 minutes (45 once payment starts)

time_slots.slot_kind has several values, but only signing and preorder are bookable. createHold refuses the rest.

apps/web/src/app/[locale]/(main)/checkout/page.tsx. Since D-161 (2026-10-25):

  • Only full name is required. Gender, date of birth and employment are optional, under an “About you” block with a one-line reason and a “Why we ask” disclosure. create-payment-intent and reservations.createFreeBooking still validate them when they are sent, and an invalid value returns 400. The profile upsert writes only the fields the buyer answered, so skipping one never blanks a value already on user_profiles. A half-typed date of birth still blocks, because it would otherwise be dropped silently.
  • Payment preview. Before details and terms are complete, the payment card shows the amount, the methods (card, FPX) and one checklist of open steps. The Pay button is aria-disabled and moves focus to the first open step.
  • PaymentIntent timing is unchanged. It is still created only after full name and accepted terms, with non_refundable_acknowledged.
  • Funnel events. checkout_details_complete (once per cart, with demographics_answered 0–3) and checkout_terms_accepted split the form drop-off ahead of begin_checkout.

The mobile /v1/checkout schema did not change. It still sends all three fields, and the shared handler just accepts their absence.

bookings.status has six values, not three. Revenue and attendance queries must count confirmed and partially_paid; partially_paid is a real, common state (deposit taken, balance outstanding), not an error state. pending, cancelled and refunded are the ones you will meet next.

Presale is a per-package flag (is_presale) and splits the amount 50/50 through calculatePresaleAmounts. Flipping it on a live package mid-checkout causes an amount mismatch on every in-flight PaymentIntent — do it between events.

Vendors pay through /checkout/booth/[applicationId], which follows the same PaymentIntent rules with the longer hold window. The application itself is reviewed in the admin portal first; see Vendors and partners.

Use Stripe’s pm_card_* payment-method fixtures. Never POST a raw card number, not even in a throwaway script — the raw-card API is disabled account-wide and attempts trigger security emails. bun run security:stripe checks the repo for violations, and CI runs it.

Local webhook forwarding:

Terminal window
bun run dev:stripe # stripe listen --forward-to localhost:3000/api/webhooks/stripe