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