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