Spanglish/about/booking_fow.md

Spanglish Website – Booking & Payment Flow

1. Purpose

This document defines the complete booking and payment flow for Spanglish events.

It ensures a fast, reliable, and user-friendly process for participants and a clear management workflow for organizers.

The system supports the following payment methods:

• TPago / Bancard (Credit & Debit Cards)
• Bitcoin Lightning (BTCPay)
• Cash at Event

---

2. Core Objectives

The booking system must:

• Allow users to reserve a seat in under 60 seconds
• Minimize drop-off during payment
• Provide clear confirmation
• Support mobile-first usage
• Reduce manual coordination
• Integrate cleanly with the admin dashboard

---

3. High-Level Booking Flow

1. User visits an event page
2. User clicks "Join Event"
3. Booking page opens
4. User enters personal details
5. User selects payment method
6. Payment or reservation is processed
7. Ticket is generated
8. Confirmation is sent
9. User appears in admin dashboard

---

4. Booking Page Structure

The booking page is available at:

/book/{event-id}

It consists of a single vertical flow optimized for mobile devices.

4.1 Event Summary Section

Displayed at the top and always visible:

• Event title
• Date and time
• Location
• Remaining seats
• Price

This section helps users verify they selected the correct event.

---

4.2 User Information Section

The booking form collects:

• Full name (required)
• Email address (required)
• Phone / WhatsApp number (required)
• Preferred language (optional)

Validation rules:

• All required fields must be filled
• Email format validation
• Phone number format validation
• Duplicate booking prevention

---

4.3 Payment Selection Section

Users choose one of the following payment methods using selectable cards.

Each option is presented as a large, tap-friendly card with icon and description.

Available options:

1. TPago / Bancard
2. Bitcoin Lightning
3. Cash at Event

Only one option may be selected.

---

5. Payment Methods

5.1 TPago / Bancard (Credit & Debit Card)

User Flow

1. User selects "TPago / Bancard"
2. User clicks "Pay with Card"
3. User is redirected to Bancard checkout
4. User completes payment
5. User is redirected back to Spanglish
6. Payment is verified via webhook
7. Ticket is confirmed

System Behavior

• Payment intent is created before redirect
• Payment reference is stored
• Webhook validation is mandatory
• Only verified payments mark tickets as paid

Status: Paid

---

5.2 Bitcoin Lightning (BTCPay)

User Flow

1. User selects "Bitcoin Lightning"
2. Invoice is generated
3. QR code and invoice string are displayed
4. User pays with Lightning wallet
5. Payment is detected via webhook
6. Ticket is confirmed automatically

Display Requirements

• QR code
• Amount in sats
• Expiry countdown
• Copy invoice button

System Behavior

• Invoice created via BTCPay API
• Webhook confirmation required
• Automatic ticket confirmation

Status: Paid

---

5.3 Cash at Event

User Flow

1. User selects "Cash at Event"
2. User confirms reservation
3. Booking is created
4. Ticket is generated
5. User receives confirmation
6. User pays in cash at the event entrance

System Behavior

• Booking is stored as unpaid
• Seat is reserved immediately
• No automatic expiration is applied
• Admin marks payment as received manually

Status: Pending (until marked Paid by staff)

---

6. Ticket Generation

After successful booking:

• A unique ticket ID is generated
• Ticket is linked to user and event
• Ticket status is assigned
• QR code may be generated
• Ticket is stored permanently

Ticket statuses:

• Pending
• Paid
• Cancelled
• Refunded

---

7. Confirmation & Notifications

7.1 Booking Confirmation

Sent immediately after booking.

Channels:

• Email
• Optional WhatsApp integration

Content includes:

• Event details
• Payment method
• Ticket ID
• Check-in instructions n

---

7.2 Payment Confirmation

Sent when payment is completed (Card / Lightning).

Includes:

• Payment receipt
• Ticket confirmation
• Calendar link

---

7.3 Event Reminder

Sent automatically before the event.

Includes:

• Date and time
• Location map
• Payment reminder for cash users

---

8. Admin Management Flow

8.1 Admin View

Admins can view all bookings with:

• Name
• Event
• Payment method
• Status
• Contact info
• Check-in status

Color coding:

• Green: Paid
• Yellow: Pending
• Red: Cancelled

---

8.2 Manual Payment Processing

For cash payments:

• Admin locates ticket
• Marks as Paid
• Timestamp is recorded
• Receipt may be attached

---

8.3 Refund Handling

Admins may:

• Mark tickets as Refunded
• Trigger payment provider refunds
• Send notification to user

---

9. Capacity Management

• Each event has a fixed capacity
• Seats are reserved immediately on booking
• Overbooking is prevented
• Sold-out events disable booking

---

10. Anti-Abuse Measures

The system must implement:

• Duplicate booking detection
• Rate limiting on bookings
• Email verification (optional)
• Admin override tools

---

11. Error Handling

The system must handle:

• Failed payments
• Interrupted redirects
• Invoice expiration
• Network issues
• Invalid input

Behavior:

• Clear user-facing messages
• Automatic retry options
• Error logging

---

12. Audit Logging

All booking-related actions must be logged:

• Ticket creation
• Payment updates
• Manual status changes
• Refunds
• Cancellations

Each log entry includes:

• User ID
• Admin ID (if applicable)
• Timestamp
• Action type n

---

13. Security Requirements

• Secure payment redirects
• Webhook signature verification
• Encrypted data storage
• PCI compliance via provider
• No sensitive card data stored

---

14. Future Extensions

The booking system is designed to support:

• Subscriptions
• Membership passes
• Promo codes
• Group bookings
• Lightning Address payments
• Cashu payments

---

15. Summary

This booking and payment flow is designed to be fast, reliable, and scalable.

It supports local payment methods, Bitcoin Lightning, and cash while maintaining professional standards.

All implementations must follow this document to ensure consistency and trust.