payemnt billing and credits refactoring
This commit is contained in:
IGNY8 VPS (Salman)
196
docs/90-REFERENCE/BILLING-SYSTEM-MASTER.md
Normal file
196
docs/90-REFERENCE/BILLING-SYSTEM-MASTER.md
Normal file
@@ -0,0 +1,196 @@
|
||||
# IGNY8 Billing System Master Document
|
||||
|
||||
**Last Updated:** 2026-01-20
|
||||
|
||||
This document is the authoritative reference for the billing system implementation, including models, invoice lifecycle, payment flows, credit reset logic, and notification timing.
|
||||
|
||||
---
|
||||
|
||||
## 1) Core Principles
|
||||
|
||||
- **No hardcoded products**: Plans, credit packages, and future add-ons are data-driven.
|
||||
- **Explicit invoice type**: `subscription`, `credit_package`, `addon`, `custom`.
|
||||
- **Correct crediting**:
|
||||
- Subscription credits reset to **0** at cycle end.
|
||||
- Subscription credits reset to **full plan amount** on renewal/activation.
|
||||
- Credit package credits add to balance.
|
||||
- **Lifecycle governance**: Credit invoices expire automatically and can be cancelled by users.
|
||||
- **Auditability**: Every credit change is recorded in `CreditTransaction`.
|
||||
|
||||
---
|
||||
|
||||
## 2) Data Model Overview
|
||||
|
||||
### 2.1 Invoice
|
||||
| Field | Purpose |
|
||||
|---|---|
|
||||
| `invoice_type` | `subscription`, `credit_package`, `addon`, `custom` |
|
||||
| `status` | `draft`, `pending`, `paid`, `void`, `uncollectible` |
|
||||
| `expires_at` | Expiry for credit invoices |
|
||||
| `void_reason` | Cancellation/expiration reason |
|
||||
| `line_items` | Itemized charges (product‑driven) |
|
||||
| `metadata` | Compatibility + gateway context |
|
||||
|
||||
### 2.2 Payment
|
||||
| Field | Purpose |
|
||||
|---|---|
|
||||
| `status` | `pending_approval`, `succeeded`, `failed`, `refunded` |
|
||||
| `payment_method` | `stripe`, `paypal`, `bank_transfer`, `local_wallet`, `manual` |
|
||||
| `invoice` | FK to invoice |
|
||||
| `metadata` | Gateway and fulfillment details |
|
||||
|
||||
### 2.3 Credits
|
||||
| Field | Purpose |
|
||||
|---|---|
|
||||
| `Account.credits` | Current balance |
|
||||
| `CreditTransaction` | Immutable ledger of changes |
|
||||
|
||||
---
|
||||
|
||||
## 3) Invoice Types and Fulfillment Rules
|
||||
|
||||
| Invoice Type | Fulfillment | Account Status Change |
|
||||
|---|---|---|
|
||||
| `subscription` | Reset credits to plan amount | Activate account + subscription |
|
||||
| `credit_package` | Add package credits | No status change |
|
||||
| `addon` | Provision add-on entitlement | No status change |
|
||||
| `custom` | No credits unless specified | No status change |
|
||||
|
||||
---
|
||||
|
||||
## 4) Flowcharts
|
||||
|
||||
### 4.1 Subscription Purchase (Stripe / PayPal / Bank Transfer)
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[User selects plan] --> B[Create subscription invoice]
|
||||
B --> C{Payment Method}
|
||||
C -->|Stripe/PayPal| D[Gateway checkout]
|
||||
D --> E[Webhook payment succeeded]
|
||||
E --> F[Invoice paid]
|
||||
F --> G[Reset credits to full plan amount]
|
||||
G --> H[Account + subscription active]
|
||||
|
||||
C -->|Bank Transfer| I[User submits confirmation]
|
||||
I --> J[Payment pending_approval]
|
||||
J --> K[Admin approves]
|
||||
K --> F
|
||||
```
|
||||
|
||||
### 4.2 Subscription Renewal (Automatic + Manual)
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[Billing cycle end] --> B[Reset credits to 0]
|
||||
B --> C[Create renewal invoice]
|
||||
C --> D{Auto method available?}
|
||||
D -->|Yes| E[Gateway charges]
|
||||
E --> F[Webhook payment succeeded]
|
||||
F --> G[Reset credits to full plan amount]
|
||||
G --> H[Subscription active]
|
||||
|
||||
D -->|No| I[Manual payment required]
|
||||
I --> J[Invoice emailed]
|
||||
J --> K[Admin approves]
|
||||
K --> G
|
||||
```
|
||||
|
||||
### 4.3 Credit Package Purchase (All Methods)
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[User selects credit package] --> B[Create credit invoice + expires_at]
|
||||
B --> C{Payment Method}
|
||||
C -->|Stripe/PayPal| D[Gateway checkout]
|
||||
D --> E[Webhook payment succeeded]
|
||||
E --> F[Add package credits]
|
||||
|
||||
C -->|Bank Transfer| G[User submits confirmation]
|
||||
G --> H[Payment pending_approval]
|
||||
H --> I[Admin approves]
|
||||
I --> F
|
||||
```
|
||||
|
||||
### 4.4 Credit Invoice Expiry
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[Scheduler checks pending credit invoices] --> B{expires_at <= now?}
|
||||
B -->|Yes| C[Void invoice + notify user]
|
||||
B -->|No| D[No action]
|
||||
```
|
||||
|
||||
### 4.5 Credit Invoice Cancellation (User)
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[User clicks cancel] --> B{Pending credit invoice?}
|
||||
B -->|Yes| C[Set status=void, void_reason=user_cancelled]
|
||||
C --> D[Notify user]
|
||||
B -->|No| E[Reject request]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5) Notification Matrix (Required Emails)
|
||||
|
||||
| Event | Email | Timing |
|
||||
|---|---|---|
|
||||
| Manual payment submitted | Payment confirmation | Immediate |
|
||||
| Manual payment approved | Payment approved | Immediate |
|
||||
| Manual payment rejected | Payment rejected | Immediate |
|
||||
| Renewal notice | Subscription renewal notice | N days before end |
|
||||
| Renewal invoice | Invoice email | At renewal creation |
|
||||
| Renewal reminder | Invoice reminder | Every 3 days until paid |
|
||||
| Credit invoice expiring | Credit invoice expiring | 24h before expires_at |
|
||||
| Credit invoice expired | Credit invoice expired | At void |
|
||||
| Credit invoice cancelled | Credit invoice cancelled | Immediate |
|
||||
| Payment failed | Payment failed | Immediate |
|
||||
| Low credits | Low credits warning | Threshold crossing |
|
||||
| Subscription expired | Subscription expired | When grace period ends |
|
||||
|
||||
---
|
||||
|
||||
## 6) Scheduled Tasks
|
||||
|
||||
| Task | Purpose | Schedule |
|
||||
|---|---|---|
|
||||
| send_renewal_notices | Renewal reminders | Daily 09:00 |
|
||||
| process_subscription_renewals | Create renewal invoices | Daily 00:05 |
|
||||
| send_invoice_reminders | Remind pending renewals | Daily 10:00 |
|
||||
| check_expired_renewals | Expire grace period | Daily 00:15 |
|
||||
| send_credit_invoice_expiry_reminders | Credit invoice expiry reminder | Daily 09:30 |
|
||||
| void_expired_credit_invoices | Auto-void expired credit invoices | Daily 00:45 |
|
||||
| replenish_monthly_credits | Monthly credit reset (legacy) | 1st day monthly |
|
||||
|
||||
---
|
||||
|
||||
## 7) Key Implementation Rules
|
||||
|
||||
1. **Invoice type drives fulfillment** (no plan/package hardcoding).
|
||||
2. **Subscription credits**: reset to **0** at cycle end, then set to **full amount** on renewal.
|
||||
3. **Credit packages**: add package credits only.
|
||||
4. **Credit invoices**: expire automatically and are cancellable by users.
|
||||
5. **Account status** only changes on **subscription invoices**.
|
||||
|
||||
---
|
||||
|
||||
## 8) Operational Verification Checklist
|
||||
|
||||
- Stripe/PayPal subscription purchase activates account and resets credits.
|
||||
- Bank transfer subscription approval resets credits (not adds).
|
||||
- Credit package approval adds package credits (not plan credits).
|
||||
- Credit invoices do not block subscription state.
|
||||
- Credit invoice expiry and cancellation work with emails.
|
||||
- Renewal resets credits to 0 at cycle end and to full on payment.
|
||||
|
||||
---
|
||||
|
||||
## 9) Extensibility (Future Add‑ons)
|
||||
|
||||
- Add new `Product` types without code changes to invoice fulfillment.
|
||||
- Use `invoice_type='addon'` with line items to provision entitlements.
|
||||
- No plan/package hardcoding required.
|
||||
|
||||
---
|
||||
|
||||
## 10) References
|
||||
|
||||
- Audit: [docs/audits/BILLING-SYSTEM-AUDIT-20260120.md](docs/audits/BILLING-SYSTEM-AUDIT-20260120.md)
|
||||
- Refactor Plan: [docs/audits/BILLING-SYSTEM-AUDIT-AND-REFACTOR-PLAN-20260120.md](docs/audits/BILLING-SYSTEM-AUDIT-AND-REFACTOR-PLAN-20260120.md)
|
||||
Reference in New Issue
Block a user