revamps docs complete

master-docs/20-api/ENDPOINTS/payments.md

@@ -0,0 +1,53 @@
+# Payments Endpoints
+
+## Purpose
+Document payment-related endpoints exposed under billing APIs.
+
+## Code Locations (exact paths)
+- Routing: `backend/igny8_core/business/billing/urls.py`
+- Views: `backend/igny8_core/business/billing/views.py` (`PaymentViewSet`)
+
+## High-Level Responsibilities
+- List payments for the current account and submit manual payments tied to invoices.
+- Expose available payment methods per account/country configuration.
+
+## Detailed Behavior
+- Base path: `/api/v1/billing/`
+- `PaymentViewSet`:
+  - `GET /payments/` → list payments (account-scoped; optional status filter). Returns amount, currency, payment_method, status, timestamps, invoice linkage, transaction_reference, failure_reason.
+  - `GET /payment-methods/available/` → returns available methods (driven by `PaymentService.get_available_payment_methods`; includes methods array plus metadata).
+  - `POST /payments/manual/` → submit manual payment for an invoice:
+    - Body: `invoice_id`, `payment_method` (`bank_transfer` or `local_wallet`), `transaction_reference` (or `reference`), optional `notes`.
+    - Validates invoice belongs to account and is not already paid; creates payment via `PaymentService.create_manual_payment`; returns pending-approval status and payment id.
+- Permissions: authenticated users; account scoping via `request.user.account`.
+
+## Data Structures / Models Involved (no code)
+- `Payment`, `Invoice`, `Account`, `PaymentMethodConfig`, `AccountPaymentMethod`.
+
+## Execution Flow
+- Router dispatch → PaymentViewSet → service calls → model updates → unified responses. Manual payment creates a pending payment record for later approval/processing.
+
+## Cross-Module Interactions
+- Payments link to invoices; account scoping enforced. Available methods depend on payment method configs; manual payments may require admin follow-up.
+
+## State Transitions
+- Payments move through statuses (`pending`, `pending_approval`, `processing`, `succeeded/completed`, `failed`, `refunded`, `cancelled`).
+
+## Error Handling
+- 400 on missing required fields or already-paid invoice; 404 if invoice not found for account.
+
+## Tenancy Rules
+- All queries scoped to `request.user.account`; no cross-tenant access.
+
+## Billing Rules
+- Payment records tie to invoices; credit balance changes happen when payments are processed (handled in payment service/admin flows).
+
+## Background Tasks / Schedulers
+- None specific in endpoints; payment processing/approval handled by services/admin workflows.
+
+## Key Design Considerations
+- Manual payment endpoint avoids storing sensitive data; relies on transaction_reference and admin approval.
+
+## How Developers Should Work With This Module
+- Use manual payment endpoint for bank/local wallet flows; implement gateway flows (Stripe/PayPal) in `PaymentService` and add endpoints if needed; keep account scoping and invoice validation.
+