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