first commit
This commit is contained in:
Michaël
366
about/payment_options.md
Normal file
366
about/payment_options.md
Normal file
@@ -0,0 +1,366 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user