# Payment Policy Page & Management System — Implementation Notes

This document provides details on the architectural design, database structures, security protocols, and compliance frameworks implemented for the Kevron Suites and Apartments **Payment Policy Page and Management System**.

---

## 1. System Goals & Governance
* **URL Endpoints**: `/payment-policy`
* **Redirects**: `/payment-terms`, `/policies/payment-policy` redirect permanently (301) to `/payment-policy`.
* **Dynamic Governance**: The frontend is fully database-driven, pulling data from the `payment_policies` schema. Active settings like base nightly rates, accepted payment methods, and bank transfer credentials are managed in admin-controlled tables to avoid static, hardcoded values.
* **Wording Disclaimers**: Policy contents are drafted to represent "starter safe clauses" pending final legal advisor and finance directorate review before publication.

---

## 2. Relational Database Schema Mapping
We created 9 tables via the `2026_06_01_290000_create_payment_policy_tables.php` migration:
1. `payment_policies`: Policy version headers (status: `draft`, `internal_review`, `finance_review`, `legal_review`, `approved`, `published`, `archived`).
2. `payment_policy_sections`: Modular HTML payment clauses.
3. `payment_policy_acceptances`: Compliant acceptances audit trail (IP address, user-agent, checkbox labels, contexts: `booking`, `registration`, `digital_checkin`, `dashboard`, `proof_upload`).
4. `payment_methods`: Configurable payment options (online, bank_transfer, corporate, cash, manual).
5. `bank_accounts`: Official banking details, subject to a `public_display` toggle.
6. `payment_gateways`: Secure credentials repository (Paystack, Flutterwave, Stripe).
7. `payment_gateway_transactions`: Online checkout transactions log.
8. `proof_of_payment_uploads`: Secure database for uploads containing full names, emails, references, transaction dates, and file paths.
9. `payment_disputes`: Registry to log chargebacks and double charges.

---

## 3. Front-End Design & Visual Standards
* **Typography**: Headlines Marcellus (Strictly capped at `Max 1.8rem`); body text Inter (capped at `Max 0.875rem`).
* **Symmetry**: Component cards use `border-radius: 0.1rem` with `box-shadow: rgba(0, 0, 0, 0.05) 0px 0px 0px 1px`. Buttons use `border-radius: 50px`.
* **Alternating Tones**: Section background colors alternate between Cloud White (`#FFFFFF`) and Soft Ice Blue (`#F4F8FF`).
* **Alpine.js TOC Sidebar**: Offers filter search, sticky layout, and Scroll Spy highlighting active sections in real-time.
* **Secure Proof of Payment Upload Card**: Accessible drag-and-drop file uploader (PDF/JPG/PNG, max 4MB) that stores receipt proofs privately.
* **Print layout**: Specific `@media print` directives hide navigational headers, footers, sidebars, and forms for clean physical policy copies.

---

## 4. Compliance Auditing & Log Trackers
* **Unified Audit Trail**: All policy updates, credential revisions, and dispute reviews write entries to `audit_logs` leveraging `AuditLog::record(Auth::id(), 'action_key', 'description')`.
* **Credential Encryption**: Payment gateway secret keys and webhook secrets are stored encrypted via Laravel's standard AES-256-CBC wrapper.
* **Isolated File Storage**: Uploaded transfer receipt proofs reside inside `storage/app/secure/payment-proofs/` to block direct public URI downloads.

---

## 5. Automated Verification Suites
* Tested with `php artisan test --filter=PaymentPolicyTest`.
* Asserts page loading (200), redirections (301), draft status shields (404), acceptance logs, file validations, private storage paths, and disputes.