# IGNY8 Billing & Account Platform — Final Plan  
**Date:** 2025-12-05  
**Status:** Canonical (supersedes all prior billing/account docs)  
**Scope:** Tenant + Admin experience across Billing, Account, Credits, Payment Methods, and Payment Gateways. Frontend + Backend must use the IGNY8 standard API system.

---

## 1) Purpose & Principles
- Single source of truth for billing/account flows.
- One canonical API namespace per audience (tenant vs admin).
- Align models ↔ services ↔ serializers ↔ frontend calls; remove drift.
- Keep manual payment path healthy while Stripe/PayPal mature.
- Favor incremental rollout with feature-flagged transitions.

---

## 2) Canonical Namespaces
- Tenant: `/api/v1/billing/...`
- Admin: `/api/v1/admin/billing/...`
- Deprecate legacy `/api/v1/admin/...` (modules/billing) and duplicated routers. Optionally dual-serve for one release behind a feature flag.

---

## 3) Reality Snapshot (current code)
- Tenant billing viewsets live in `backend/igny8_core/business/billing/views.py` (invoices, payments, credit packages, transactions).
- Admin billing viewset also exists there (`pending_payments`, approvals, stats) but mounted at `/api/v1/billing/admin/...`.
- Legacy admin stack in `backend/igny8_core/modules/billing/views.py` exposes stats/users/credit-costs only; no invoices/payments.
- Model drift: `InvoiceService` expects `currency`, `tax_amount`, `total_amount` that are absent on `Invoice`. `PaymentService` uses `pending_approval`/`completed` statuses not present in `Payment.STATUS_CHOICES`.
- Frontend admin pages are wired but call nonexistent or legacy routes (e.g., `/v1/admin/payments/`).

---

## 4) Backend Plan
### 4.1 Models & Migrations (billing app)
- Invoice: add `currency`, `subtotal_amount`, `tax_amount`, `total_amount`, `line_items` (JSON list), `payment_method` (string), `stripe_invoice_id`/`paypal_invoice_id` (nullable), `metadata`. Keep existing dates/status. Add index on `status, created_at`.
- Payment: extend `STATUS_CHOICES` to include `pending_approval`, `processing`, `completed`, `failed`, `refunded`, `cancelled`. Add `payment_method` enum (stripe, paypal, bank_transfer, local_wallet, manual), gateway intent/charge ids, `manual_reference`, `failure_reason`, `approved_by/at`, `metadata`.
- CreditPackage: ensure `slug`, `price`, `credits`, `stripe_price_id` exist and `is_active`, `is_featured`. Add `sort_order` for admin ordering.
- PaymentMethodConfig: keep as source for country-level enablement; ensure uniqueness `(country_code, payment_method)`.
- Write forward/backward-safe migrations; backfill currency and totals with sensible defaults (e.g., `USD`, recompute `total_amount=subtotal_amount+tax_amount` where possible).

### 4.2 Services
- `InvoiceService`: align fields; generate invoice numbers, compute subtotal/tax/total, store line items, mark paid/void/uncollectible, emit events, optionally render PDF stub.
- `PaymentService`: 
  - Stripe/PayPal: create intents/orders, store ids, update status on success/failure, attach to invoice, and trigger credit application when relevant.
  - Manual: create `pending_approval`, allow approve/reject endpoints to flip status and apply credits.
  - Sync helpers from webhooks/intents; emit structured logs.
- `SubscriptionService` (existing): ensure plan ↔ subscription sync; use Stripe subscription id; update invoice/payment when Stripe posts events.
- `CreditPackageService`: list active packages, create invoice + payment intent, on success add credits (`CreditTransaction`) and recalc balance.

### 4.3 Webhooks
- Add `/api/v1/billing/webhooks/stripe/` and `/api/v1/billing/webhooks/paypal/` with signature verification.
- Handle events: `invoice.paid`, `invoice.payment_failed`, `customer.subscription.updated/deleted`, `payment_intent.succeeded/failed`, PayPal equivalents.
- Idempotent processing; log and surface dead-letter queue for failures.

### 4.4 APIs (Tenant)
- `GET /api/v1/billing/account_balance/` – balance + monthly included.
- `GET /api/v1/billing/transactions/` – credit transactions (paginated).
- `GET /api/v1/billing/usage/` – usage logs with filters.
- `GET /api/v1/billing/invoices/` | `GET /api/v1/billing/invoices/:id/` | `GET /api/v1/billing/invoices/:id/pdf/`.
- `GET /api/v1/billing/payments/` | `GET /api/v1/billing/payments/:id/`.
- `GET /api/v1/billing/credit-packages/`.
- `POST /api/v1/billing/credits/purchase/` – create intent; returns client secret + invoice id.
- `POST /api/v1/billing/subscriptions/create|upgrade|cancel/`.
- `GET /api/v1/billing/subscriptions/` – current subscription status.
- `GET/POST /api/v1/billing/payment-methods/` – list/add; store tokens/ids, not card data.

### 4.5 APIs (Admin)
- `GET /api/v1/admin/billing/invoices/` | `GET /:id/` – all accounts, filters (status, account, method, date), pagination, export.
- `GET /api/v1/admin/billing/payments/` | `GET /:id/` – all accounts, filters (status, method, gateway).
- `POST /api/v1/admin/billing/payments/:id/approve/` | `/reject/` – manual payments only.
- `GET/POST/PATCH/DELETE /api/v1/admin/billing/credit-packages/` – CRUD with `is_featured`, `sort_order`.
- `GET /api/v1/admin/billing/stats/` – totals, MRR, pending approvals, failed webhooks.
- `GET /api/v1/admin/billing/pending_payments/` – for approvals (same payload frontend expects).
- AuthZ: developer/superuser only; enforce tenant scoping for non-admin routes.

### 4.6 Settings & Config
- Add `STRIPE_PUBLIC_KEY`, `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, `PAYPAL_CLIENT_ID`, `PAYPAL_CLIENT_SECRET`, `PAYPAL_WEBHOOK_ID` to settings/env; feature-flag gateways.
- Rate-limit payment endpoints; CSRF exempt webhooks only.

---

## 5) Frontend Plan
### 5.1 Service Layer (`frontend/src/services/billing.api.ts`)
- Point all admin calls to `/api/v1/admin/billing/...`; remove dead `/v1/admin/...` routes.
- Reuse tenant calls for user-facing pages; ensure response shapes match new serializers (`InvoiceSerializer`, `PaymentSerializer`, `CreditPackageSerializer`).
- Add helpers for manual approval actions and credit-package CRUD.

### 5.2 Tenant Pages
- Plans & Billing (`/account/billing`): tabs for Plan, Credits, Billing History (invoices), Payment Methods. Uses balance, subscription, invoices, payment-methods, credit-packages, purchase intent.
- Purchase Credits (`/account/credits/purchase`): list packages → create purchase intent → confirm via Stripe/PayPal/manual upload → poll payment.
- Invoices (`/account/invoices`): paginated table, filters, PDF download.
- Payment Methods: list/add/remove default (via tokens).

### 5.3 Admin Pages
- Billing Overview (`/admin/billing`): stats from `/admin/billing/stats/`, pending approvals summary.
- Invoices (`/admin/invoices`): uses `/admin/billing/invoices/`; add filters (account, status, method, date) and CSV/PDF export.
- Payments (`/admin/payments`): uses `/admin/billing/payments/`; add filters and status badges.
- Credit Packages (`/admin/credit-packages`): CRUD via admin endpoints; show `is_active`, `is_featured`, `sort_order`, Stripe price id.
- Payment Approvals (`/admin/payments/approvals`): call `pending_payments`, approve/reject endpoints; show invoice link and manual references.
- Sidebar links already present—only fix data wiring.

### 5.4 UX/Consistency
- Standard empty/error/loading states across billing pages.
- Currency display from invoice/payment `currency`.
- Role-guard tenant routes (owner/admin only for purchases; read-only for others where applicable).

---

## 6) Sequenced Action Plan
- **Day 0 (alignment):** Merge this doc; add “retired” note to older docs; choose namespace flag (`USE_NEW_ADMIN_BILLING_API=true`).
- **Phase 1 (backend, 2-3 days):** Migrate models; update services; add admin list endpoints; webhook stubs; tests for serializers and viewsets.
- **Phase 2 (gateways + frontend wiring, 3-4 days):** Implement Stripe/PayPal intent paths, hook webhooks, wire `billing.api.ts` to new endpoints, fix admin pages, enable manual approvals end-to-end.
- **Phase 3 (polish, 2 days):** Add exports, filters, pagination polish; observability (structured logs, alerts); finalize docs and remove legacy router.

---

## 7) Deliverables & DoD
- Schema migration applied and reversible; services match models.
- Canonical endpoints live and documented; legacy admin endpoints removed/flagged off.
- Tenant billing pages load without 404s; purchases and subscriptions succeed (manual + Stripe at minimum).
- Admin pages show data, support approvals, and package CRUD.
- Tests: unit (services), API (tenant/admin billing), integration (purchase + manual approval flow), webhook idempotency.
- Docs: this file referenced from legacy docs; endpoint matrix embedded in `billing.api.ts` JSDoc or a short `/docs/billing/api-map.md`.

---

## 8) Quick Endpoint Matrix (canonical)
- Tenant: invoices (`/api/v1/billing/invoices`), payments (`/api/v1/billing/payments`), credit packages + purchase (`/api/v1/billing/credit-packages`, `/credits/purchase`), subscription create/upgrade/cancel (`/subscriptions/...`), payment methods (`/payment-methods`), usage/transactions/balance.
- Admin: invoices (`/api/v1/admin/billing/invoices`), payments (`/api/v1/admin/billing/payments`), pending approvals (`/api/v1/admin/billing/pending_payments`), approve/reject (`/api/v1/admin/billing/payments/:id/approve|reject`), credit packages CRUD (`/api/v1/admin/billing/credit-packages`), stats (`/api/v1/admin/billing/stats`).

---

## 9) Rollout & Migration Notes
- Run migrations during maintenance window; backfill currency/totals.
- If dual-stack needed, proxy legacy admin routes to new handlers temporarily.
- Communicate new admin endpoints to frontend before flipping flags.
- Validate webhook secrets in non-prod before enabling in prod.

---

## 10) Retirement Notice
This document supersedes `docs/working-docs/Original-plan-may-have-wrong-logic.md` and `docs/working-docs/admin-billing-plan-2025-12-05.md`. Treat those as retired; keep only for historical reference.

