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

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.