# Wallet System Documentation

## Overview
The wallet system allows users to top up their wallet balance and withdraw funds. The wallet balance is credited when:
1. User completes a top-up payment via Paystack
2. Admin marks an exchange order as "completed"

All transactions are tracked in the `wallet_transactions` table.

## Features

### 1. Top Up Wallet
- Users can add funds to their wallet via Paystack payment
- Minimum amount: ₵10.00
- Payment flow:
  1. User enters amount in Top Up modal
  2. Creates pending transaction with reference (TOP-XXXXX)
  3. Redirects to payment confirmation page
  4. User proceeds to Paystack payment gateway
  5. On successful payment, amount is added to wallet
  6. Transaction status updated to "completed"

### 2. Exchange to Wallet
- When admin marks an exchange order as "completed":
  - CNY amount is automatically added to user's wallet
  - Creates a wallet transaction record (type: topup, method: exchange)
  - Sends notification to user
  - Reference format: EXC-{ORDER_NUMBER}

### 3. Withdraw Funds
- Users can withdraw funds from their wallet
- Minimum amount: ₵10.00
- Maximum amount: Current wallet balance
- Withdrawal methods: Mobile Money (MoMo), Bank Transfer
- Requires account details (MoMo number or bank account)
- Creates a pending transaction with reference (WTH-XXXXX)
- Funds are immediately deducted from wallet balance
- Admin processes withdrawal within 24 hours

## Database Structure

### wallet_transactions Table
- `id`: Primary key
- `user_id`: Foreign key to users table
- `type`: enum('topup', 'withdraw')
- `amount`: decimal(10, 2)
- `status`: string (pending, completed, failed)
- `payment_method`: string (momo, bank, card)
- `reference`: string (unique transaction reference)
- `notes`: text (account details for withdrawals)
- `timestamps`: created_at, updated_at

## API Endpoints

### POST /wallet/topup
Creates a top up request and redirects to payment page.

**Request:**
```json
{
  "amount": 100.00
}
```

**Response:**
```json
{
  "success": true,
  "redirect": "/wallet/topup/payment"
}
```

### GET /wallet/topup/payment
Displays payment confirmation page for wallet top-up.

### POST /payment/initialize
Initializes Paystack payment for both orders and wallet top-ups.

**Request (Top Up):**
```json
{
  "type": "topup",
  "transaction_id": 1
}
```

**Request (Order):**
```json
{
  "type": "order",
  "order_id": 1
}
```

### GET /payment/callback
Handles Paystack payment callback and verification.
- For top-ups: Credits wallet and marks transaction as completed
- For orders: Updates order payment status

### POST /wallet/withdraw
Creates a withdrawal request.

**Request:**
```json
{
  "amount": 50.00,
  "payment_method": "momo",
  "account_details": "0244123456 - John Doe"
}
```

**Response:**
```json
{
  "success": true,
  "message": "Withdrawal request submitted successfully.",
  "transaction": {
    "id": 2,
    "user_id": 1,
    "type": "withdraw",
    "amount": "50.00",
    "status": "pending",
    "payment_method": "momo",
    "reference": "WTH-65F8A9B2D",
    "notes": "0244123456 - John Doe"
  }
}
```

## User Interface

### Dashboard Wallet Section
- Displays current wallet balance
- Two action buttons: "Top Up" and "Withdraw"
- Clicking buttons opens respective modals

### Top Up Modal
- Amount input (minimum ₵10.00)
- Payment method selection
- Submit button creates pending transaction
- Shows reference number for payment completion

### Withdraw Modal
- Amount input (minimum ₵10.00, maximum: wallet balance)
- Withdrawal method selection
- Account details textarea
- Submit button creates pending transaction and deducts from balance
- Shows reference number for tracking

## Admin Tasks (To Be Implemented)

### Pending Features
1. Admin interface to view all wallet transactions
2. Admin ability to approve/complete top up transactions
3. Admin ability to process withdrawal requests
4. Transaction history view for users
5. Email/SMS notifications for transaction status updates
6. Paystack integration for automated top up payments

### Suggested Admin Actions
- View all pending transactions
- Mark top up as completed (adds funds to user wallet)
- Mark withdrawal as completed (confirms funds sent)
- Mark transaction as failed (refunds withdrawal to wallet)
- View transaction history with filters

## Testing

### Test Top Up
1. Login as a user
2. Go to dashboard
3. Click "Top Up" button
4. Enter amount (e.g., 100.00)
5. Click "Continue to Payment"
6. Verify redirect to payment confirmation page
7. Click "Proceed to Payment"
8. Complete Paystack payment (use test card if in test mode)
9. Verify redirect back to dashboard with success message
10. Check wallet balance is updated
11. Check database: `SELECT * FROM wallet_transactions WHERE type='topup' AND status='completed';`

### Test Exchange to Wallet
1. Create an exchange order as a user
2. Complete payment for the order
3. Login as admin
4. Go to admin orders page
5. Change order status to "completed"
6. Check user's wallet balance increased by CNY amount
7. Check database: `SELECT * FROM wallet_transactions WHERE payment_method='exchange';`
8. Verify user received notification about completed exchange

### Test Withdraw
1. Login as a user with wallet balance
2. Go to dashboard
3. Click "Withdraw" button
4. Enter amount (less than or equal to balance)
5. Select withdrawal method
6. Enter account details
7. Click "Submit Withdrawal Request"
8. Verify transaction created and balance deducted
9. Check database: `SELECT * FROM wallet_transactions WHERE type='withdraw';`

## Security Considerations
- CSRF protection on all forms
- Authentication required for all wallet operations
- Balance validation before withdrawal
- Transaction references are unique
- User can only access their own transactions