# 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.