6.5 KiB
Spanglish Website – Payment Options Management
1. Purpose
This document defines how payment methods are configured, displayed, and managed in the Spanglish platform.
It introduces a centralized Payment Options system that can be configured globally and overridden per event.
The goal is to provide flexibility, transparency, and administrative control over all payment flows.
2. Core Principles
- Payment options are centrally managed in the admin panel
- Each event can override default payment settings
- Most non-instant payments require manual admin approval
- Only approved payments trigger confirmation emails
- Users must clearly understand how to pay
- The system must support future payment methods
3. Payment Options Admin Tab
3.1 Location
The admin dashboard must include a dedicated tab:
/Admin → Payment Options
This section controls global payment settings.
3.2 Global Payment Configuration
Admins can configure default payment options used for all events unless overridden.
Global settings include:
- TPago default link
- Bank transfer details
- Bitcoin/Lightning configuration (LNbits)
- Cash policy
- Enabled / disabled status per method
3.3 Event-Level Overrides
Each event includes a "Payment Settings" section.
Admins may override:
- TPago link
- Bank account details
- Enabled payment methods
- Custom instructions
If no override is set, global defaults apply.
4. Supported Payment Methods
4.1 Paraguayan Bank Transfer
Description
Allows users to pay via local bank transfer.
Payment details are displayed to the user.
Displayed Information
- Bank name
- Account holder
- Account number
- Alias
- Phone number
- Additional notes (optional)
User Flow
- User selects "Bank Transfer"
- Bank details are displayed
- User makes the transfer externally
- User clicks "I Have Paid"
- Booking status becomes "Pending Approval"
- Admin verifies payment
- Admin marks payment as Paid
- Confirmation email is sent
System Behavior
- No automatic confirmation
- No booking confirmation until approved
- Payment proof upload (optional future feature)
Status Flow: Pending → Paid → Confirmed
4.2 International Cards (TPago Link)
Description
International card payments are handled via a TPago payment link.
Example: https://www.tpago.com.py/links?alias=PXEOI9...
Displayed Information
- Payment provider name
- External payment link
- Instructions
User Flow
- User selects "International Card"
- TPago link opens in new tab
- User completes payment
- User returns to booking page
- User clicks "I Have Paid"
- Booking status becomes "Pending Approval"
- Admin verifies payment
- Admin marks payment as Paid
- Confirmation email is sent
System Behavior
- Payment verification is manual
- No automatic webhook integration
- External link must be configurable
Status Flow: Pending → Paid → Confirmed
4.3 Bitcoin / Lightning (LNbits)
Description
Lightning payments are handled via LNbits integration.
This method supports instant confirmation.
User Flow
- User selects "Bitcoin / Lightning"
- Invoice is generated
- QR code is displayed
- User pays
- Payment is detected automatically
- Ticket is confirmed
- Confirmation email is sent
System Behavior
- Fully automated
- Webhook-based confirmation
- No admin intervention required
Status Flow: Paid → Confirmed
4.4 Cash at the Door
Description
Users pay in cash when arriving at the event.
User Flow
- User selects "Cash at the Door"
- Booking is created
- Status is set to Pending
- User attends event
- Staff receives payment
- Admin marks as Paid
- Confirmation is sent
System Behavior
- No automatic confirmation
- Manual approval required
- Visible in admin dashboard
Status Flow: Pending → Paid → Confirmed
5. Booking Page Presentation
Payment methods are displayed as selectable cards.
Each card includes:
- Icon
- Title
- Short description
- Processing speed (Instant / Manual)
Example:
[ Bank Transfer ] (Manual) [ International Card ] (Manual) [ Bitcoin / Lightning ] (Instant) [ Cash at Door ] (Manual)
Selected card expands with instructions.
6. "I Have Paid" Confirmation Button
For manual payment methods, the booking page must display:
Button: "I Have Paid"
Behavior
- Marks booking as "Pending Approval"
- Stores timestamp
- Notifies admin
- Disables duplicate clicks
No confirmation email is sent at this stage.
7. Admin Payment Verification Panel
7.1 Payment Review Queue
Admins have access to:
/Admin → Payments → Pending Approval
This list shows:
- User name
- Event
- Payment method
- Amount
- Date
- Reference (if provided)
7.2 Approval Actions
For each pending payment:
- Approve (mark as Paid)
- Reject (mark as Failed)
- Add internal note
Approval triggers:
- Ticket confirmation
- Confirmation email
- Audit log entry
8. Payment Status Model
All bookings follow this status lifecycle:
Created → Pending → Paid → Confirmed ↓ Failed / Cancelled
Only "Confirmed" bookings are considered valid attendees.
9. Data Storage
Each payment record stores:
- Payment ID
- Booking ID
- Method
- Amount
- Currency
- Reference
- Status
- Admin approver
- Approval timestamp
- Notes
10. Extensibility for Future Methods
The payment system must be modular.
New payment methods can be added by defining:
- Name
- Type (Instant / Manual)
- Configuration schema
- UI template
- Validation rules
Examples:
- PayPal
- PIX
- Cashu
- Local wallets
- QR bank payments
No core refactor should be required.
11. Security Requirements
- Secure storage of payment data
- Access control on payment approval
- Audit logging
- Protection against duplicate approvals
- No storage of sensitive card data
12. Reporting
The admin dashboard must provide:
- Revenue per payment method
- Pending approvals
- Failed payments
- Approval turnaround time
13. User Experience Rules
- Instructions must be clear
- Links must open correctly
- Manual steps must be visible
- No misleading "confirmed" messages
- Payment state always visible
14. Summary
This payment options system centralizes configuration and control while supporting both instant and manual payment methods.
It enables local Paraguayan payments, international cards, Bitcoin Lightning, and cash handling within one unified workflow.
All implementations must follow this specification to ensure reliability and scalability.