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

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.