holiday-property-booking/05-payments-and-notifications.md

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.