# Phase 5 — Enterprise Banking & Security Documentation

**Date:** 2026-07-03  
**Version:** 2.0.0 (Enterprise v1.0)  
**Status:** COMPLETE

---

## Modules Built

### Module 1: OTP & Security Center

| Component | Files | Description |
|-----------|-------|-------------|
| Models | OtpSettingsModel, UserOtpSettingsModel, OtpLogModel | Global settings, per-user overrides, OTP log records |
| Repositories | OtpSettingsRepository, UserOtpSettingsRepository, OtpLogRepository | CRUD + specialized lookups |
| Service | OtpService | OTP generation, verification, settings management |
| Controller | OtpController | 6 API endpoints |
| Routes | 6 routes | /api/v1/otp/* |

**Features:**
- Global OTP settings with master switch and per-type toggles (11 types)
- Per-user OTP override settings
- Numeric OTP generation (configurable length: 4-10 digits)
- Expiry and max attempts (configurable)
- bcrypt-hashed OTP codes (not stored plaintext)
- Auto-invalidation of previous pending OTPs
- Email delivery via queue (SMS-ready architecture)
- Full audit logging

**Endpoints:**
- `GET /api/v1/otp/settings/global` — Get global OTP settings (admin)
- `PUT /api/v1/otp/settings/global` — Update global OTP settings (admin)
- `GET /api/v1/otp/settings/user` — Get user's OTP settings
- `PUT /api/v1/otp/settings/user` — Update user's OTP settings
- `POST /api/v1/otp/generate` — Generate OTP for a type
- `POST /api/v1/otp/verify` — Verify OTP code

---

### Module 2: Notification Center

| Component | Files | Description |
|-----------|-------|-------------|
| Models | NotificationTemplateModel, NotificationSettingsModel, UserNotificationPreferenceModel | Templates, global settings, user preferences |
| Repositories | NotificationTemplateRepository, NotificationSettingsRepository, UserNotificationPreferenceRepository | CRUD + lookups |
| Service | NotificationCenterService | Template management, settings, preferences, history, archive |
| Controller | NotificationCenterController | 9 API endpoints |
| Routes | 9 routes | /api/v1/notifications/*, /api/v1/admin/notifications/* |

**Features:**
- Editable notification templates with variable substitution ({{variable}})
- Global notification master switch + per-type/channel settings
- Per-user notification preferences with global override option
- 17 notification types supported (debit/credit/transfer/deposit/withdrawal/loan/card/crypto/security alerts)
- Notification history with read/unread/archive status
- Mark all read, archive individual, delete individual
- Email + In-app channels (SMS/Push architecture ready)
- Template rendering engine with {{variable}} substitution

**Endpoints:**
- `GET /api/v1/notifications/types` — List all notification types
- `GET /api/v1/admin/notifications/templates/{uuid}` — Get template (admin)
- `POST /api/v1/admin/notifications/templates` — Create/update template (admin)
- `GET /api/v1/admin/notifications/settings` — Get global settings (admin)
- `PUT /api/v1/admin/notifications/settings` — Update global settings (admin)
- `GET /api/v1/notifications/preferences` — Get user preferences
- `PUT /api/v1/notifications/preferences` — Update user preferences
- `GET /api/v1/notifications/history` — Get notification history
- `PATCH /api/v1/notifications/{uuid}/archive` — Archive notification
- `DELETE /api/v1/notifications/{uuid}` — Delete notification

---

### Module 3: PDF Receipts

| Component | Files | Description |
|-----------|-------|-------------|
| Service | ReceiptPdfService | PDF generation, branding, verification, storage |
| Controllers | ReceiptController, AdminBrandingController | Receipt APIs + admin branding |
| Routes | 7 routes | /api/v1/receipts/*, /api/v1/admin/branding |

**Features:**
- Raw text-based PDF 1.4 generation (no external libraries, PHP 7.4 shared-hosting safe)
- Professional receipt layout with bank name, logo placeholder, receipt number, transaction reference, customer details, amount, currency, status, available balance, description, date/time, QR code placeholder, verification code, footer, watermark
- Admin branding settings (bank name, logo path, colors, footer, watermark, support contact info)
- SHA-256 file hash verification
- Unique verification codes for receipt authenticity
- File storage in `storage/receipts/{receipt_uuid}.pdf`
- Queue-based email delivery with PDF attachment
- Download, verify, and email endpoints

**Endpoints:**
- `POST /api/v1/receipts/{uuid}/generate` — Generate PDF receipt
- `GET /api/v1/receipts/{uuid}/download` — Download receipt
- `GET /api/v1/receipts/verify/{code}` — Verify receipt authenticity (public)
- `POST /api/v1/receipts/{uuid}/email` — Email receipt
- `GET /api/v1/receipts/{uuid}` — Get receipt details
- `GET /api/v1/admin/branding` — Get branding settings (admin)
- `PUT /api/v1/admin/branding` — Update branding settings (admin)

---

### Module 4: Deposit Methods

| Component | Files | Description |
|-----------|-------|-------------|
| Repository | DepositRequestRepository | Deposit requests CRUD + search |
| Service | DepositRequestService | Manual bank transfer, payment gateway, crypto deposit handling |
| Controller | DepositRequestController | Customer + admin APIs |
| Routes | 12 routes | /api/v1/deposit-requests/*, /api/v1/admin/deposit-requests/*, /api/v1/deposit-callbacks/{gateway} |

**Features:**
- **Manual Bank Transfer:** Customer uploads proof, reference, bank details. Admin approves/rejects.
- **Payment Gateway:** Architecture ready for Paystack, Flutterwave, Stripe. Callback processing with auto-credit on success.
- **Crypto Deposit:** BTC, ETH, USDT TRC20, USDT ERC20. Customer submits wallet, transaction hash, proof. Admin verifies and approves.
- All non-gateway deposits go through approval workflow (maker-checker-approver)
- Gateway callbacks auto-credit via TransactionService (no admin approval needed)
- Proof files stored in `storage/deposits/proofs/{year}/{month}/`
- Payment callback logging for audit trail
- Full notification integration (approved/rejected alerts)
- Admin dashboard with stats by status, method, and currency

**Endpoints:**
- `POST /api/v1/deposit-requests/manual` — Submit manual bank transfer
- `POST /api/v1/deposit-requests/gateway` — Submit payment gateway request
- `POST /api/v1/deposit-requests/crypto` — Submit crypto deposit request
- `GET /api/v1/deposit-requests` — List my deposit requests
- `GET /api/v1/deposit-requests/{uuid}` — Get deposit request details
- `PATCH /api/v1/deposit-requests/{uuid}/cancel` — Cancel pending request
- `GET /api/v1/admin/deposit-requests` — Admin list all requests
- `PATCH /api/v1/admin/deposit-requests/{uuid}/approve` — Approve deposit
- `PATCH /api/v1/admin/deposit-requests/{uuid}/reject` — Reject deposit
- `PATCH /api/v1/admin/deposit-requests/{uuid}/verify-crypto` — Verify crypto deposit
- `POST /api/v1/deposit-callbacks/{gateway}` — Payment gateway callback (public)

---

### Module 5: Admin Payment Management

| Component | Files | Description |
|-----------|-------|-------------|
| Repositories | CompanyBankAccountRepository, PaymentGatewayRepository, CryptoWalletRepository | CRUD + search |
| Service | AdminPaymentService | Admin management of payment infrastructure |
| Controller | AdminPaymentController | Admin APIs |
| Routes | 22 routes | /api/v1/admin/company-accounts/*, /api/v1/admin/payment-gateways/*, /api/v1/admin/crypto-wallets/*, /api/v1/admin/deposit-requests/*, /api/v1/admin/deposit-stats |

**Features:**
- Company bank accounts management (CRUD, toggle active, currency filtering)
- Payment gateway configuration (Paystack, Flutterwave, Stripe architecture ready)
- Crypto wallet management (BTC, ETH, USDT TRC20, USDT ERC20, unlimited extensible)
- Deposit request approval/rejection workflow
- Deposit statistics dashboard (count and total by status, method, currency)
- Full audit logging for all admin actions

**Endpoints:**
- `POST /api/v1/admin/company-accounts` — Create company account
- `GET /api/v1/admin/company-accounts` — List company accounts
- `GET /api/v1/admin/company-accounts/{uuid}` — Get account
- `PUT /api/v1/admin/company-accounts/{uuid}` — Update account
- `PATCH /api/v1/admin/company-accounts/{uuid}/toggle` — Toggle active
- `POST /api/v1/admin/payment-gateways` — Create gateway
- `GET /api/v1/admin/payment-gateways` — List gateways
- `GET /api/v1/admin/payment-gateways/{uuid}` — Get gateway
- `PUT /api/v1/admin/payment-gateways/{uuid}` — Update gateway
- `PATCH /api/v1/admin/payment-gateways/{uuid}/toggle` — Toggle active
- `POST /api/v1/admin/crypto-wallets` — Create wallet
- `GET /api/v1/admin/crypto-wallets` — List wallets
- `GET /api/v1/admin/crypto-wallets/{uuid}` — Get wallet
- `PUT /api/v1/admin/crypto-wallets/{uuid}` — Update wallet
- `PATCH /api/v1/admin/crypto-wallets/{uuid}/toggle` — Toggle active
- `GET /api/v1/admin/deposit-requests` — List all deposit requests
- `PATCH /api/v1/admin/deposit-requests/{uuid}/approve` — Approve deposit
- `PATCH /api/v1/admin/deposit-requests/{uuid}/reject` — Reject deposit
- `GET /api/v1/admin/deposit-stats` — Deposit statistics

---

### Module 6: Loans

| Component | Files | Description |
|-----------|-------|-------------|
| Models | LoanProductModel, LoanRequestModel, LoanRepaymentModel | Loan products, requests, repayments |
| Repositories | LoanProductRepository, LoanRequestRepository, LoanRepaymentRepository | CRUD + search |
| Service | LoanService | Full loan lifecycle management |
| Controller | LoanController | 15 API endpoints |
| Routes | 15 routes | /api/v1/loan-products/*, /api/v1/loan-requests/*, /api/v1/admin/loan-requests/*, /api/v1/admin/loan-products/* |

**Features:**
- Loan product management (CRUD, toggle, interest rate, tenure, limits, penalty, processing fee)
- Loan request lifecycle: PENDING → APPROVED → DISBURSED → ACTIVE → REPAID
- Automatic repayment schedule generation (monthly principal + interest breakdown)
- Loan disbursement via TransactionService (double-entry ledger)
- Loan repayment via TransactionService (double-entry ledger)
- Approval workflow integration (maker-checker-approver)
- Loan statements (request details + all repayments + balance remaining)
- Interest calculation: fixed rate on principal
- Penalty support (rate + type configuration)
- Full notification integration (approved/rejected/disbursement/repayment alerts)
- Loan status lifecycle rules (canCancel, canDisburse, canRepay)

**Endpoints:**
- `GET /api/v1/loan-products` — List active loan products (public)
- `GET /api/v1/loan-products/{uuid}` — Get loan product
- `POST /api/v1/loan-requests` — Submit loan request
- `GET /api/v1/loan-requests` — List my loan requests
- `GET /api/v1/loan-requests/{uuid}` — Get loan request
- `PATCH /api/v1/loan-requests/{uuid}/cancel` — Cancel pending request
- `POST /api/v1/loan-requests/{uuid}/repay` — Make repayment
- `GET /api/v1/loan-requests/{uuid}/statement` — Get loan statement
- `POST /api/v1/admin/loan-products` — Create loan product (admin)
- `PUT /api/v1/admin/loan-products/{uuid}` — Update loan product (admin)
- `PATCH /api/v1/admin/loan-products/{uuid}/toggle` — Toggle product (admin)
- `GET /api/v1/admin/loan-requests` — List all loan requests (admin)
- `PATCH /api/v1/admin/loan-requests/{uuid}/approve` — Approve loan (admin)
- `PATCH /api/v1/admin/loan-requests/{uuid}/disburse` — Disburse loan (admin)
- `PATCH /api/v1/admin/loan-requests/{uuid}/reject` — Reject loan (admin)

---

### Module 7: Cards

| Component | Files | Description |
|-----------|-------|-------------|
| Models | CardModel, CardRequestModel | Issued cards and card requests |
| Repositories | CardRepository, CardRequestRepository | CRUD + search |
| Service | CardService | Full card lifecycle management |
| Controller | CardController | 16 API endpoints |
| Routes | 16 routes | /api/v1/card-requests/*, /api/v1/cards/*, /api/v1/admin/card-requests/*, /api/v1/admin/cards/* |

**Features:**
- Card request lifecycle: PENDING → APPROVED → ISSUED
- Virtual and physical card support
- Card number generation (16-digit, starting with 4/5, uniqueness checked)
- Expiry date calculation (2 years from issue)
- CVV and PIN hashing (security)
- Card limits: daily, monthly, per-transaction
- Card status management: ACTIVE, FROZEN, BLOCKED, EXPIRED, REPLACED
- Freeze/unfreeze functionality
- Block functionality with reason
- Card replacement (new card linked to old via replacement_uuid)
- Limit updates
- Approval workflow integration
- Full notification integration
- Issuer tracking (Visa, Mastercard, etc.)

**Endpoints:**
- `POST /api/v1/card-requests` — Request a card
- `GET /api/v1/card-requests` — List my card requests
- `GET /api/v1/card-requests/{uuid}` — Get card request
- `PATCH /api/v1/card-requests/{uuid}/cancel` — Cancel request
- `GET /api/v1/cards` — List my cards
- `GET /api/v1/cards/{uuid}` — Get card details
- `PATCH /api/v1/cards/{uuid}/freeze` — Freeze card
- `PATCH /api/v1/cards/{uuid}/unfreeze` — Unfreeze card
- `PATCH /api/v1/cards/{uuid}/block` — Block card
- `POST /api/v1/cards/{uuid}/replace` — Replace card
- `PUT /api/v1/cards/{uuid}/limits` — Update card limits
- `GET /api/v1/admin/card-requests` — List all requests (admin)
- `PATCH /api/v1/admin/card-requests/{uuid}/approve` — Approve request (admin)
- `POST /api/v1/admin/card-requests/{uuid}/issue` — Issue card (admin)
- `PATCH /api/v1/admin/card-requests/{uuid}/reject` — Reject request (admin)
- `GET /api/v1/admin/cards` — List all cards (admin)

---

### Module 8: KYC (Know Your Customer)

| Component | Files | Description |
|-----------|-------|-------------|
| Models | KycLevelModel, KycDocumentModel, KycVerificationModel | KYC levels, documents, verifications |
| Repositories | KycLevelRepository, KycDocumentRepository, KycVerificationRepository | CRUD + search |
| Service | KycService | Full KYC lifecycle management |
| Controller | KycController | 14 API endpoints |
| Routes | 14 routes | /api/v1/kyc-levels/*, /api/v1/kyc/*, /api/v1/admin/kyc/* |

**Features:**
- KYC level management (LEVEL_0 to LEVEL_3) with limits and required documents
- Document upload with base64 decoding, stored in `storage/kyc/{user_id}/`
- Document types: Passport, Driver's License, National ID, Utility Bill, Bank Statement, Selfie
- KYC verification workflow: PENDING → SUBMITTED → UNDER_REVIEW → APPROVED/REJECTED
- Document review with approve/reject and notes
- KYC verification approval with required document checks
- User KYC status dashboard (current level, documents, verification status)
- Max daily deposit/withdrawal and account balance limits per KYC level
- Full notification integration
- Full audit logging

**Endpoints:**
- `GET /api/v1/kyc-levels` — List KYC levels (public)
- `GET /api/v1/kyc-levels/{uuid}` — Get KYC level
- `POST /api/v1/kyc/documents` — Upload document
- `GET /api/v1/kyc/documents` — List my documents
- `POST /api/v1/kyc/verify` — Submit KYC verification
- `GET /api/v1/kyc/status` — Get my KYC status
- `POST /api/v1/admin/kyc-levels` — Create KYC level (admin)
- `PUT /api/v1/admin/kyc-levels/{uuid}` — Update KYC level (admin)
- `PATCH /api/v1/admin/kyc-levels/{uuid}/toggle` — Toggle KYC level (admin)
- `GET /api/v1/admin/kyc/documents` — List all documents (admin)
- `PATCH /api/v1/admin/kyc/documents/{uuid}/review` — Review document (admin)
- `GET /api/v1/admin/kyc/verifications` — List all verifications (admin)
- `PATCH /api/v1/admin/kyc/verifications/{uuid}/approve` — Approve verification (admin)
- `PATCH /api/v1/admin/kyc/verifications/{uuid}/reject` — Reject verification (admin)

---

### Module 9: Approval Workflow

| Component | Files | Description |
|-----------|-------|-------------|
| Models | ApprovalWorkflowModel, ApprovalRequestModel, ApprovalHistoryModel | Workflows, requests, history |
| Repositories | ApprovalWorkflowRepository, ApprovalRequestRepository, ApprovalHistoryRepository | CRUD + search |
| Service | ApprovalWorkflowService | Maker-Checker-Approver workflow |
| Controller | ApprovalWorkflowController | 11 API endpoints |
| Routes | 11 routes | /api/v1/approval-workflows/*, /api/v1/approval-requests/* |

**Features:**
- Configurable workflow per entity type (requires_maker, requires_checker, requires_approver)
- Amount thresholds (min/max) for workflow eligibility
- Request lifecycle: PENDING → APPROVED/REJECTED/RETURNED/CANCELLED
- Maker approval → Checker approval → Approver approval (sequential)
- Return to maker functionality
- Full audit trail in approval_history
- Pending queue for reviewers
- Approval request search with filters

**Endpoints:**
- `POST /api/v1/approval-workflows` — Create workflow (admin)
- `POST /api/v1/approval-requests` — Submit for approval
- `GET /api/v1/approval-requests` — List requests
- `GET /api/v1/approval-requests/pending-queue` — Get pending queue
- `GET /api/v1/approval-requests/{uuid}` — Get request
- `GET /api/v1/approval-requests/{uuid}/history` — Get approval history
- `PATCH /api/v1/approval-requests/{uuid}/maker-approve` — Maker approve
- `PATCH /api/v1/approval-requests/{uuid}/checker-approve` — Checker approve
- `PATCH /api/v1/approval-requests/{uuid}/approver-approve` — Approver approve
- `PATCH /api/v1/approval-requests/{uuid}/reject` — Reject
- `PATCH /api/v1/approval-requests/{uuid}/return` — Return to maker
- `PATCH /api/v1/approval-requests/{uuid}/cancel` — Cancel

---

## Database Migrations (23 total)

| # | Migration | Tables Created |
|---|-----------|----------------|
| 000000 | Users & Auth | users, user_roles, user_sessions, password_resets, password_history, login_history |
| 000001 | Audit Logs | audit_logs |
| 000002 | Accounts | accounts |
| 000003 | Ledger | ledger_entries |
| 000004 | Transactions | transactions |
| 000005 | Transaction Metadata | transaction_metadata |
| 000006 | Receipts | receipts |
| 000007 | References | ref_registry |
| 000008 | Beneficiaries | beneficiaries |
| 000009 | Statements | statement_requests |
| 000010 | Notifications | notifications |
| 000011 | Transfers | transfers |
| 000012 | Deposits | deposits |
| 000013 | Withdrawals | withdrawals |
| 000014 | Clearing Accounts | system_clearing_accounts (seeded) |
| 000015 | Performance Indexes | 8 composite and single indexes |
| 000016 | OTP | otp_settings, user_otp_settings, otp_logs |
| 000017 | Notification Center | notification_templates, notification_settings, user_notification_preferences |
| 000018 | Deposit Methods | company_bank_accounts, payment_gateways, crypto_wallets, deposit_requests, payment_callbacks |
| 000019 | Loans | loan_products, loan_requests, loan_repayments |
| 000020 | Cards | cards, card_requests |
| 000021 | KYC | kyc_levels, kyc_documents, kyc_verifications |
| 000022 | Approval Workflow | approval_workflows, approval_requests, approval_history |
| 000023 | Receipt PDFs | receipt_pdfs, admin_branding_settings |

---

## Constants (27 files)

| Category | Constants |
|----------|-----------|
| Account | AccountTypes, AccountStatus |
| User | UserStatus, Roles |
| Financial | TransactionTypes, Currencies, DepositTypes, WithdrawalTypes |
| Transfer | TransferTypes |
| Security | OtpTypes |
| Deposit | DepositMethods, DepositStatus, CryptoTypes, PaymentGatewayProviders |
| Loan | LoanTypes, LoanStatus |
| Card | CardTypes, CardStatus, CardRequestStatus |
| KYC | KycDocumentTypes, KycStatus, KycLevels |
| Workflow | ApprovalStatus, ApprovalActions |
| Notification | NotificationTypes, NotificationChannels |

---

## API Endpoint Summary

| Module | Endpoints | Auth Required | Admin Only |
|--------|-----------|---------------|------------|
| Authentication | 7 | Partial | No |
| Users | 7 | Yes | Partial |
| Accounts | 7 | Yes | Partial |
| Transfers | 5 | Yes | No |
| Deposits (Phase 4) | 3 | Yes | Partial |
| Withdrawals | 3 | Yes | Partial |
| Beneficiaries | 6 | Yes | No |
| Statements | 3 | Yes | No |
| Notifications | 5 | Yes | No |
| OTP | 6 | Yes | Partial (2 admin) |
| Notification Center | 9 | Yes | Partial (5 admin) |
| PDF Receipts | 7 | Yes | Partial (2 admin) |
| Deposit Methods | 12 | Yes | Partial (5 admin) |
| Admin Payment | 22 | Yes | Yes (all admin) |
| Loans | 15 | Yes | Partial (5 admin) |
| Cards | 16 | Yes | Partial (5 admin) |
| KYC | 14 | Yes | Partial (7 admin) |
| Approval Workflow | 11 | Yes | Partial (1 admin) |
| **Total** | **~185** | | |

---

## Architecture Compliance

| Principle | Status |
|-----------|--------|
| Ledger-first | ✅ All financial movement through TransactionService |
| Double-entry | ✅ All transactions create balanced DR/CR entries |
| BalanceEngine exclusivity | ✅ Only BalanceEngine writes to accounts.balance |
| Event decoupling | ✅ Events never throw; listener failures logged |
| Transaction safety | ✅ executeInTransaction() with nesting counter |
| UUID-only API | ✅ All controllers expose UUIDs only |
| Reference collision | ✅ ReferenceGenerator retry loop + registry |
| Audit all actions | ✅ AuditService on all create/update/delete |
| File-based queue | ✅ storage/queue/ for shared hosting |
| Approval workflow | ✅ Maker-Checker-Approver for sensitive operations |
| OTP per operation | ✅ Configurable per-type OTP with global master switch |
| Notification templates | ✅ Editable templates with variable substitution |

---

## Files Created Summary

| Category | Count |
|----------|-------|
| PHP files in app/ | 221 |
| Database migrations | 23 |
| Constants | 27 |
| Documentation markdown | 19 |
| **Total** | **290** |

---

## Phase 5 is Complete

**Do NOT proceed to any new phase without explicit approval.**