salman/igny8
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Version 1.9.0

Browse Source
This commit is contained in:
IGNY8 VPS (Salman)
2026-01-20 07:58:48 +00:00
parent bc50b022f1
commit 257b6817f1
9 changed files with 241 additions and 176 deletions
Download Patch File Download Diff File Expand all files Collapse all files

224
docs/90-REFERENCE/BILLING-SYSTEM-MASTER.md
View File

@@ -2,195 +2,113 @@
**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.
> **Primary Reference:** For complete billing documentation, see [BILLING-PAYMENTS-COMPLETE.md](../10-MODULES/BILLING-PAYMENTS-COMPLETE.md)
This document provides a summary of the billing system implementation.
---
## 1) Core Principles
- **Two-Pool Credit System:**
- `account.credits` = Plan credits (reset on renewal)
- `account.bonus_credits` = Purchased credits (NEVER expire, NEVER reset)
- **Credit Usage Priority:** Plan credits used FIRST, bonus credits only when plan credits = 0
- **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.
- Subscription: reset plan credits to **full plan amount** on payment (bonus untouched)
- Credit package: add to **bonus_credits** only (never plan credits)
- **Renewal Grace Period:** 7 days
- **Credit Reset on Non-Payment:** 24 hours after renewal (Day +1), plan credits → 0
- **Auditability**: Every credit change is recorded in `CreditTransaction`.
---
## 2) Data Model Overview
## 2) Two-Pool Credit System
### 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 |
| Pool | Field | Source | Behavior |
|------|-------|--------|----------|
| Plan Credits | `account.credits` | Subscription plan | Reset to plan amount on renewal payment, reset to 0 if unpaid after 24h |
| Bonus Credits | `account.bonus_credits` | Credit packages | NEVER expire, NEVER reset, only deducted after plan credits = 0 |
### 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 |
### Credit Deduction Priority
1. Deduct from `credits` (plan) first
2. Only when `credits = 0`, deduct remainder from `bonus_credits`
---
## 3) Invoice Types and Fulfillment Rules
## 3) Renewal Workflow (Simplified)
| 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 |
### Stripe/PayPal (Auto-Pay) - Industry Standard
- **No advance notice** (like Netflix, Spotify)
- Day 0: Auto-charge attempt
- If success: Receipt email + credits reset to plan amount
- If failed: Retry notification, Stripe retries 4x over 7 days
- Day +7: Expired if all retries fail
### Bank Transfer (Manual)
- **Day -3:** Invoice created + Email sent
- **Day 0:** Renewal day reminder (if unpaid)
- **Day +1:** Urgent reminder + credits reset to 0
- **Day +7:** Subscription expired
---
## 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
## 4) Scheduled Tasks (Updated)
| 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 |
|------|---------|----------|
| `create_bank_transfer_invoices` | Invoice 3 days before (bank transfer only) | Daily 09:00 |
| `process_subscription_renewals` | Auto-pay renewals (Stripe/PayPal) | Daily 00:05 |
| `send_renewal_day_reminders` | Day 0 reminder (bank transfer) | Daily 10:00 |
| `send_day_after_reminders` | Day +1 urgent reminder + credit reset | Daily 09:15 |
| `check_expired_renewals` | Expire after 7-day grace | Daily 00:15 |
| `send_credit_invoice_expiry_reminders` | Credit invoice reminder | Daily 09:30 |
| `void_expired_credit_invoices` | Auto-void credit invoices (48h) | Daily 00:45 |
---
## 7) Key Implementation Rules
## 5) Invoice Types and Fulfillment
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**.
| Invoice Type | Credits Action | Account Status |
|--------------|----------------|----------------|
| `subscription` | Reset plan credits to plan amount | Activate account + subscription |
| `credit_package` | Add to **bonus_credits** | No status change |
| `addon` | Provision entitlement | No status change |
| `custom` | As specified | No status change |
---
## 8) Operational Verification Checklist
## 6) Key Implementation Rules
- 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.
1. **Two pools:** `credits` (plan) + `bonus_credits` (purchased)
2. **Deduction order:** Plan credits first, then bonus credits
3. **Subscription payment:** Reset plan credits to full amount (bonus untouched)
4. **Credit package payment:** Add to bonus_credits only
5. **No payment 24h:** Plan credits → 0, bonus credits unchanged
6. **Late payment:** Plan credits restored to full amount
---
## 9) Extensibility (Future Add‑ons)
## 7) Quick Reference
- 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.
### Payment Method by Country
| Country | Stripe | PayPal | Bank Transfer |
|---------|--------|--------|---------------|
| Pakistan (PK) | ✅ | ❌ | ✅ |
| Others | ✅ | ✅ | ❌ |
### Credit Reset Summary
| Event | Plan Credits | Bonus Credits |
|-------|--------------|---------------|
| Payment success | Reset to plan amount | No change |
| No payment (24h) | Reset to 0 | No change |
| Late payment | Reset to plan amount | No change |
---
## 10) References
## 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)
- Complete Documentation: [BILLING-PAYMENTS-COMPLETE.md](../10-MODULES/BILLING-PAYMENTS-COMPLETE.md)
- Payment Gateways: [PAYMENT-SYSTEM.md](PAYMENT-SYSTEM.md)

8
docs/90-REFERENCE/PAYMENT-SYSTEM.md
View File

@@ -1,10 +1,12 @@
# Payment System Documentation
> **Version:** 1.6.0
> **Last Updated:** January 8, 2026
> **Version:** 2.0.0
> **Last Updated:** January 20, 2026
> **Status:** Production Ready
This document provides comprehensive documentation of the IGNY8 payment system architecture, implementation, and flows.
> **Complete Billing Reference:** For comprehensive billing documentation including the two-pool credit system and renewal workflows, see [BILLING-PAYMENTS-COMPLETE.md](../10-MODULES/BILLING-PAYMENTS-COMPLETE.md)
This document provides payment gateway implementation details for IGNY8.
---