60 lines
3.7 KiB
Markdown
60 lines
3.7 KiB
Markdown
# 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.
|