54 lines
2.8 KiB
Markdown
54 lines
2.8 KiB
Markdown
# 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.
|
|
|