feat: scaffold holiday booking project

05-payments-and-notifications.md

@@ -0,0 +1,67 @@
+# 05. Payments and Notifications
+
+## Purpose
+
+Define how money is taken and how the system informs the customer and the business.
+
+## Scope
+
+- Stripe Checkout integration.
+- Webhook handling and payment truth.
+- Success and failure return flows.
+- Booking confirmation email.
+- Failure handling email or on-screen messaging.
+- Optional post-booking notifications for admin.
+
+## Proposed Payment and Notification Rules
+
+### Payment Flow
+
+- The app creates a booking record before redirecting to Stripe Checkout.
+- Stripe Checkout is used for payment collection.
+- The app listens for Stripe webhooks to confirm payment completion.
+- The browser return page is informational only and must not be the only source of truth.
+
+### Payment Truth
+
+- Stripe webhook events are authoritative for payment success/failure.
+- The booking record should only be marked confirmed after payment is verified.
+- Payment status must be recorded separately from booking status.
+
+### Notification Rules
+
+- Send a booking confirmation email after successful payment verification.
+- Show a failure or incomplete payment message if checkout does not complete.
+- Optionally notify admins of new confirmed bookings if needed later.
+
+### Failure Handling
+
+- If payment fails or is abandoned, the booking should not appear confirmed.
+- If the browser return fails but payment succeeds, webhook processing must still finalize the booking.
+- If the webhook arrives late, the system should resolve the booking once the event is processed.
+
+## What Needs to Be Done
+
+- Define the payment initiation and callback flow.
+- Define what Stripe events matter.
+- Define which system owns final payment state.
+- Define the email templates and triggers.
+- Define failure recovery behavior.
+- Define which booking states can trigger notifications.
+- Define retry behavior for failed or delayed webhook delivery.
+
+## Acceptance Criteria
+
+- Payment state is not inferred from the browser alone.
+- The success and failure paths are separately documented.
+- Email timing and triggers are explicit.
+- The booking result is consistent across website, admin, and payment provider.
+- The booking state cannot be finalized incorrectly from frontend-only events.
+
+## Dependencies
+
+- Booking, availability, and pricing plan.
+
+## Notes
+
+- This step should prevent later ambiguity about whether Stripe, the browser, or the app is authoritative.