115 lines
4.2 KiB
Markdown
115 lines
4.2 KiB
Markdown
# IGNY8 Billing System Master Document
|
|
|
|
**Last Updated:** 2026-01-20
|
|
|
|
> **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: 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) Two-Pool Credit System
|
|
|
|
| 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 |
|
|
|
|
### Credit Deduction Priority
|
|
1. Deduct from `credits` (plan) first
|
|
2. Only when `credits = 0`, deduct remainder from `bonus_credits`
|
|
|
|
---
|
|
|
|
## 3) Renewal Workflow (Simplified)
|
|
|
|
### 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) Scheduled Tasks (Updated)
|
|
|
|
| Task | Purpose | Schedule |
|
|
|------|---------|----------|
|
|
| `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 |
|
|
|
|
---
|
|
|
|
## 5) Invoice Types and Fulfillment
|
|
|
|
| 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 |
|
|
|
|
---
|
|
|
|
## 6) Key Implementation Rules
|
|
|
|
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
|
|
|
|
---
|
|
|
|
## 7) Quick Reference
|
|
|
|
### 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 |
|
|
|
|
---
|
|
|
|
## References
|
|
|
|
- Complete Documentation: [BILLING-PAYMENTS-COMPLETE.md](../10-MODULES/BILLING-PAYMENTS-COMPLETE.md)
|
|
- Payment Gateways: [PAYMENT-SYSTEM.md](PAYMENT-SYSTEM.md)
|