revamps docs complete

master-docs/30-frontend/accounts/PAYMENT-METHODS-PAGE.md

@@ -0,0 +1,59 @@
+ # Payment Methods Page
+ 
+ ## Purpose
+ Display available payment methods for the tenant and support selection for purchases/subscriptions. Methods originate from backend billing configs and are reused across plan changes and credit purchases.
+ 
+ ## Code Locations (exact paths)
+ - Consolidated flows: `frontend/src/pages/account/PlansAndBillingPage.tsx` (tab `payment-methods`)
+ - Purchase credits: `frontend/src/pages/account/PurchaseCreditsPage.tsx` (method selection + manual payment proof)
+ - API: `frontend/src/services/billing.api` (`getAvailablePaymentMethods`, `createPaymentMethod`, `deletePaymentMethod`, `setDefaultPaymentMethod`)
+ 
+ ## High-Level Responsibilities
+ - Fetch account-scoped payment methods (bank transfer, local wallet, manual/other).
+ - Allow choosing a default method for purchases/subscriptions.
+ - Provide instructions/details (bank or wallet) for manual/offline flows.
+ 
+ ## Detailed Behavior
+ - PlansAndBillingPage:
+   - On load, calls `getAvailablePaymentMethods()` with other billing calls; filters out disabled methods (`is_enabled === false`).
+   - Chooses preferred method for selection: bank_transfer, then manual, else default flag, else first item.
+   - Renders payment-methods tab listing methods, default flag, instructions; supports create/delete/default actions via `createPaymentMethod`, `deletePaymentMethod`, `setDefaultPaymentMethod`.
+   - Selection state (`selectedPaymentMethod`) is reused when purchasing packages or creating subscriptions.
+ - PurchaseCreditsPage:
+   - Fetches methods and auto-selects bank_transfer, then manual, else first.
+   - For bank/local/manual methods, shows instructions and bank/wallet details and collects `transaction_reference` + `notes` when the payment is manual/offline.
+   - Stripe/PayPal placeholders show “integration pending”.
+ 
+ ## Data Structures / Models Involved (no code)
+ - `PaymentMethod` DTO: `id`, `type` (`bank_transfer`, `local_wallet`, `manual`, `stripe`, `paypal`), `display_name`, `instructions`, optional `bank_details`/`wallet_details`, `is_default`, `is_enabled`.
+ 
+ ## Execution Flow
+ - Load methods → set local `paymentMethods` → derive `selectedPaymentMethod`.
+ - User selects method → stored in component state; used by purchase/subscription handlers.
+ - Optional CRUD (create/delete/default) triggered in `PlansAndBillingPage` tab using billing API helpers.
+ 
+ ## Cross-Module Interactions
+ - Used by credit purchase (`purchaseCreditPackage`) and subscription updates (`createSubscription`, `cancelSubscription`) within `PlansAndBillingPage`.
+ 
+ ## State Transitions
+ - Local selection state only; backend default flag can be updated via `setDefaultPaymentMethod`.
+ 
+ ## Error Handling
+ - Errors surface via toast/banner in `PlansAndBillingPage`; inline error message in `PurchaseCreditsPage` for missing selections or failed calls.
+ 
+ ## Tenancy Rules
+ - All calls are account-scoped by backend auth; no client multi-tenant switching.
+ 
+ ## Billing Rules (if applicable)
+ - Selected method is passed to credit purchase and subscription creation; manual methods require proof submission (transaction reference) and remain pending approval server-side.
+ 
+ ## Background Tasks / Schedulers (if applicable)
+ - None on client.
+ 
+ ## Key Design Considerations
+ - Prefers offline-safe methods (bank/manual) to avoid blocking when card gateways are unavailable.
+ - Keeps selection sticky within the session to reduce user friction across tabs.
+ 
+ ## How Developers Should Work With This Module
+ - To add a new gateway type, extend `PaymentMethod` type, update selection logic, and render gateway-specific instructions or redirection flows.
+ - Keep manual/offline instructions editable via backend configs; surface them read-only in the UI.