287 lines
9.1 KiB
Markdown
287 lines
9.1 KiB
Markdown
# Billing Module Standalone & Coupon System - Implementation Summary
|
|
|
|
## Overview
|
|
|
|
This update addresses two major requirements:
|
|
|
|
1. **Standalone Billing Module**: The billing module can now operate independently from the panel, either on the same server or on a separate web host.
|
|
2. **Enhanced Coupon System**: A comprehensive coupon system with game filters, usage tracking, and permanent/one-time discount options.
|
|
|
|
## Changes Made
|
|
|
|
### 1. Standalone Database Connection (Critical Fix)
|
|
|
|
**Problem**: The billing module was trying to use panel database functions that don't exist when deployed on a separate server, causing PayPal payment processing to fail with "Unexpected end of JSON input" error.
|
|
|
|
**Solution**:
|
|
- Removed all `require_once` statements that reference panel files like `includes/database_mysqli.php`
|
|
- Replaced panel database functions with native mysqli functions
|
|
- Created standalone `config.inc.php` file for database credentials
|
|
- Updated `api/capture_order.php` to use `mysqli_connect()` instead of `createDatabaseConnection()`
|
|
|
|
**Files Modified**:
|
|
- `.github/copilot-instructions.md` - Added standalone requirement documentation
|
|
- `modules/billing/includes/config.inc.php` - Created from template (should be gitignored in production)
|
|
- `modules/billing/api/capture_order.php` - Fixed database connection
|
|
|
|
### 2. Enhanced Coupon System
|
|
|
|
**Features Implemented**:
|
|
- ✅ Create, edit, delete coupons through admin interface
|
|
- ✅ Percentage-based discounts (0-100%)
|
|
- ✅ One-time vs. permanent discount types
|
|
- ✅ Game-specific filtering (all games or specific games)
|
|
- ✅ Usage limits and tracking
|
|
- ✅ Expiration dates
|
|
- ✅ Coupon application in cart with real-time price updates
|
|
- ✅ Automatic discount application on payment
|
|
- ✅ Discount display in My Servers and Admin Invoices views
|
|
|
|
**Files Created**:
|
|
- `modules/billing/create_coupons_table.sql` - Database schema
|
|
- `modules/billing/admin_coupons.php` - Admin management interface
|
|
- `modules/billing/COUPON_SYSTEM.md` - Comprehensive documentation
|
|
|
|
**Files Modified**:
|
|
- `modules/billing/admin.php` - Added "Manage Coupons" link
|
|
- `modules/billing/cart.php` - Added coupon application form and discount logic
|
|
- `modules/billing/api/capture_order.php` - Apply coupons on payment, track usage
|
|
- `modules/billing/my_servers.php` - Display discount information
|
|
- `modules/billing/admin_invoices.php` - Display discount information
|
|
|
|
### 3. Database Schema Updates
|
|
|
|
**New Table**: `ogp_billing_coupons`
|
|
```sql
|
|
- coupon_id (primary key)
|
|
- code (unique)
|
|
- name, description
|
|
- discount_percent
|
|
- usage_type (one_time/permanent)
|
|
- game_filter_type (all_games/specific_games)
|
|
- game_filter_list (JSON array of game keys)
|
|
- max_uses, current_uses
|
|
- expires, is_active
|
|
```
|
|
|
|
**Updated Tables**:
|
|
- `ogp_billing_invoices`: Added `coupon_id`, `discount_amount`
|
|
- `ogp_billing_orders`: Added `coupon_id`, `discount_amount`
|
|
|
|
## Installation Instructions
|
|
|
|
### Prerequisites
|
|
- MySQL/MariaDB database
|
|
- PHP 7.4 or higher
|
|
- Existing billing module installation
|
|
|
|
### Step 1: Create Configuration File
|
|
|
|
If deploying on a separate server (not co-located with panel):
|
|
|
|
```bash
|
|
cd modules/billing/includes/
|
|
cp config.inc.php.orig config.inc.php
|
|
```
|
|
|
|
Edit `config.inc.php` with your database credentials:
|
|
```php
|
|
$db_host = "your-db-host";
|
|
$db_user = "your-db-user";
|
|
$db_pass = "your-db-password";
|
|
$db_name = "your-db-name";
|
|
$table_prefix = "ogp_";
|
|
```
|
|
|
|
**Important**: Add `config.inc.php` to `.gitignore` to prevent committing sensitive credentials.
|
|
|
|
### Step 2: Run Database Migration
|
|
|
|
```bash
|
|
mysql -u [username] -p [database] < modules/billing/create_coupons_table.sql
|
|
```
|
|
|
|
Or import via phpMyAdmin.
|
|
|
|
### Step 3: Verify Installation
|
|
|
|
1. Log in as admin: `/modules/billing/admin.php`
|
|
2. Click "Manage Coupons"
|
|
3. You should see the coupon management interface with 2 sample coupons
|
|
|
|
### Step 4: Test Coupon System
|
|
|
|
1. Create a test coupon or use existing "WELCOME10"
|
|
2. Add a server to cart: `/modules/billing/order.php`
|
|
3. View cart: `/modules/billing/cart.php`
|
|
4. Apply coupon code
|
|
5. Verify discount is calculated correctly
|
|
6. Complete payment (or use free server button if admin)
|
|
7. Check My Servers page for discount display
|
|
|
|
## Usage
|
|
|
|
### For Administrators
|
|
|
|
**Create a Coupon**:
|
|
1. Navigate to Admin → Manage Coupons
|
|
2. Scroll to "Add New Coupon" form
|
|
3. Fill in details:
|
|
- Code (e.g., "SUMMER25")
|
|
- Discount percentage (e.g., 25 for 25% off)
|
|
- Usage type (one-time or permanent)
|
|
- Game filter (all games or specific)
|
|
4. Click "Add Coupon"
|
|
|
|
**Monitor Usage**:
|
|
- View current uses vs. max uses in coupon list
|
|
- Edit or deactivate coupons as needed
|
|
- Delete expired or unused coupons
|
|
|
|
### For Customers
|
|
|
|
**Apply a Coupon**:
|
|
1. Add servers to cart
|
|
2. On cart page, find "Have a coupon code?" section
|
|
3. Enter coupon code
|
|
4. Click "Apply Coupon"
|
|
5. Prices update automatically
|
|
6. Proceed to PayPal checkout
|
|
|
|
**View Discounts**:
|
|
- Cart page shows applied discount
|
|
- My Servers page shows original price (strikethrough) and discounted price
|
|
- Coupon code displayed with percentage
|
|
|
|
## Coupon Types Explained
|
|
|
|
### One-Time Coupons
|
|
- Applied to first invoice only
|
|
- Renewals use original price
|
|
- Example: "WELCOME10" for new customers
|
|
|
|
### Permanent Coupons
|
|
- Applied to initial purchase AND all renewals
|
|
- Discount stored in order record
|
|
- Example: "VIP50" for permanent 50% off
|
|
|
|
### Game Filters
|
|
|
|
**All Games**:
|
|
- Coupon applies to any game in cart
|
|
- Simplest option for general promotions
|
|
|
|
**Specific Games**:
|
|
- Define list of game keys
|
|
- Only matching games get discount
|
|
- Uses partial matching (e.g., "arma3" matches "arma3_linux64")
|
|
- Example: Arma-only promotion
|
|
|
|
## Troubleshooting
|
|
|
|
### PayPal Payment Returns JSON Error
|
|
|
|
**Symptom**: "Unexpected end of JSON input" on cart page after PayPal payment
|
|
|
|
**Cause**: Missing `config.inc.php` or incorrect database credentials
|
|
|
|
**Fix**:
|
|
1. Check `/modules/billing/includes/config.inc.php` exists
|
|
2. Verify credentials are correct
|
|
3. Test database connection: `/modules/billing/test_db_connection.php`
|
|
4. Check error logs: `/modules/billing/logs/` and server error log
|
|
|
|
### Coupon Not Applying
|
|
|
|
**Checks**:
|
|
- Code is correct (case-sensitive)
|
|
- Coupon is active
|
|
- Not expired
|
|
- Usage limit not reached
|
|
- Game matches filter (for game-specific coupons)
|
|
|
|
### Discount Not Showing After Payment
|
|
|
|
**Checks**:
|
|
- Database schema includes `discount_amount` columns
|
|
- `coupon_id` was saved to invoice/order
|
|
- Clear browser cache
|
|
|
|
## Security Notes
|
|
|
|
1. **Sensitive Files**: Add `modules/billing/includes/config.inc.php` to `.gitignore`
|
|
2. **Database Credentials**: Use read-only credentials if possible (billing only needs read/write to billing tables)
|
|
3. **CSRF Protection**: All admin forms include CSRF tokens
|
|
4. **Input Sanitization**: All user inputs are sanitized with `mysqli_real_escape_string()`
|
|
5. **SQL Injection**: Parameterized queries or escaped strings throughout
|
|
|
|
## File Structure
|
|
|
|
```
|
|
modules/billing/
|
|
├── api/
|
|
│ ├── capture_order.php (Modified - standalone DB connection)
|
|
│ └── create_order.php
|
|
├── includes/
|
|
│ ├── config.inc.php (Created - DB config)
|
|
│ └── config.inc.php.orig (Template)
|
|
├── admin_coupons.php (Created - Coupon management UI)
|
|
├── admin_invoices.php (Modified - Show discounts)
|
|
├── cart.php (Modified - Coupon application)
|
|
├── my_servers.php (Modified - Show discounts)
|
|
├── admin.php (Modified - Added coupon link)
|
|
├── create_coupons_table.sql (Created - DB schema)
|
|
└── COUPON_SYSTEM.md (Created - Documentation)
|
|
```
|
|
|
|
## Testing Checklist
|
|
|
|
- [ ] Database migration ran successfully
|
|
- [ ] Admin can access coupon management page
|
|
- [ ] Can create new coupon (all games)
|
|
- [ ] Can create game-specific coupon
|
|
- [ ] Can edit existing coupon
|
|
- [ ] Can delete coupon
|
|
- [ ] Customer can apply coupon in cart
|
|
- [ ] Cart prices update with discount
|
|
- [ ] Free server creation works (if admin)
|
|
- [ ] PayPal payment processes successfully
|
|
- [ ] Coupon usage count increments
|
|
- [ ] One-time coupon clears after payment
|
|
- [ ] Permanent coupon stays in order
|
|
- [ ] Discount shows on My Servers page
|
|
- [ ] Discount shows on Admin Invoices page
|
|
- [ ] Expired coupons are rejected
|
|
- [ ] Max uses limit is enforced
|
|
- [ ] Game filter works correctly
|
|
|
|
## Known Limitations
|
|
|
|
1. Coupons are percentage-based only (no fixed-amount discounts)
|
|
2. No minimum purchase requirement
|
|
3. No user-specific targeting (all users can use any active coupon)
|
|
4. No coupon stacking (one coupon per order)
|
|
5. Game matching uses partial string match (may need refinement)
|
|
|
|
## Future Enhancements
|
|
|
|
- Fixed-amount coupons (e.g., $5 off)
|
|
- Minimum purchase requirements
|
|
- User-specific or group-specific coupons
|
|
- Referral system integration
|
|
- Automatic coupon generation for campaigns
|
|
- Analytics dashboard
|
|
- Email notifications on coupon usage
|
|
|
|
## Support & Documentation
|
|
|
|
- Full documentation: `modules/billing/COUPON_SYSTEM.md`
|
|
- Copilot instructions: `.github/copilot-instructions.md`
|
|
- Issue tracker: GitHub Issues
|
|
|
|
---
|
|
|
|
**Version**: 1.0
|
|
**Date**: October 29, 2025
|
|
**Author**: Copilot Agent
|
|
**Tested**: Manual testing completed
|