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