367 lines
6.5 KiB
Markdown
367 lines
6.5 KiB
Markdown
# 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
|
||
|
||
1. User selects "Bank Transfer"
|
||
2. Bank details are displayed
|
||
3. User makes the transfer externally
|
||
4. User clicks "I Have Paid"
|
||
5. Booking status becomes "Pending Approval"
|
||
6. Admin verifies payment
|
||
7. Admin marks payment as Paid
|
||
8. 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](https://www.tpago.com.py/links?alias=PXEOI9)...
|
||
|
||
### Displayed Information
|
||
|
||
* Payment provider name
|
||
* External payment link
|
||
* Instructions
|
||
|
||
### User Flow
|
||
|
||
1. User selects "International Card"
|
||
2. TPago link opens in new tab
|
||
3. User completes payment
|
||
4. User returns to booking page
|
||
5. User clicks "I Have Paid"
|
||
6. Booking status becomes "Pending Approval"
|
||
7. Admin verifies payment
|
||
8. Admin marks payment as Paid
|
||
9. 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
|
||
|
||
1. User selects "Bitcoin / Lightning"
|
||
2. Invoice is generated
|
||
3. QR code is displayed
|
||
4. User pays
|
||
5. Payment is detected automatically
|
||
6. Ticket is confirmed
|
||
7. 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
|
||
|
||
1. User selects "Cash at the Door"
|
||
2. Booking is created
|
||
3. Status is set to Pending
|
||
4. User attends event
|
||
5. Staff receives payment
|
||
6. Admin marks as Paid
|
||
7. 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.
|