369 lines
6.1 KiB
Markdown
369 lines
6.1 KiB
Markdown
# 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.
|