# Store-Specific Paystack Payment System

## Overview

This system allows each store owner to configure their own Paystack credentials, enabling customers to pay directly to the store owner's Paystack account. When payment is confirmed, orders are automatically processed without manual intervention.

## Features

1. **Store-Specific Paystack Credentials**: Each store owner can add their own Paystack public and secret keys
2. **Automatic Payment Processing**: Orders are automatically processed when Paystack payment is confirmed
3. **Fallback to Mobile Money**: If Paystack is not configured or disabled, customers use Mobile Money
4. **Secure Payment Verification**: All payments are verified using Paystack's API before processing

## Setup Instructions

### Step 1: Create Database Tables

Run the database setup script:

```bash
php create_store_paystack_table.php
```

This will create:
- `store_paystack_credentials` table for storing store-specific Paystack keys
- Add `payment_method` column to `orders` table
- Add `paystack_reference` column to `orders` table

### Step 2: Configure Paystack Credentials (Store Owner)

1. Log in as a store owner
2. Navigate to **Store Dashboard** → **Paystack** (or go to `pages/store_paystack_settings.php`)
3. Enter your Paystack credentials:
   - **Public Key**: Get from Paystack Dashboard → Settings → API Keys & Webhooks
   - **Secret Key**: Get from Paystack Dashboard → Settings → API Keys & Webhooks
4. Toggle **"Enable Paystack payments for this store"** to activate
5. Click **Save Settings**

### Step 3: Configure Paystack Webhook (Optional but Recommended)

In your Paystack Dashboard:
1. Go to Settings → API Keys & Webhooks
2. Add webhook URL: `https://yourdomain.com/store_paystack_callback.php`
3. Select events: `charge.success`

## How It Works

### For Store Owners

1. **Adding Paystack Credentials**:
   - Go to Store Dashboard → Paystack Settings
   - Enter your Paystack Public and Secret Keys
   - Enable/disable Paystack payments as needed

2. **Payment Flow**:
   - When a customer places an order, the system checks if your store has Paystack enabled
   - If enabled, customer is redirected to Paystack payment page
   - Payment goes directly to your Paystack account
   - Order is automatically processed when payment is confirmed

### For Customers

1. **Placing an Order**:
   - Customer selects package and enters phone number
   - If store has Paystack enabled, customer is redirected to Paystack
   - Customer completes payment on Paystack
   - After payment, customer is redirected to order status page
   - Order is automatically processed

2. **If Paystack Not Available**:
   - Customer sees Mobile Money payment instructions
   - Store owner must manually confirm payment and process order

## Payment Flow Diagram

```
Customer Places Order
        ↓
Store Has Paystack?
    ├─ Yes → Initialize Paystack Payment
    │         ↓
    │    Customer Pays on Paystack
    │         ↓
    │    Paystack Callback Received
    │         ↓
    │    Verify Payment
    │         ↓
    │    Auto-Process Order
    │         ↓
    │    Send to External API (if enabled)
    │
    └─ No → Show Mobile Money Instructions
              ↓
          Store Owner Confirms Payment
              ↓
          Store Owner Clicks "Process"
              ↓
          Order Processed
```

## Files Modified/Created

### New Files:
- `create_store_paystack_table.php` - Database setup script
- `pages/store_paystack_settings.php` - UI for managing Paystack credentials
- `store_paystack_callback.php` - Callback handler for store order payments
- `STORE_PAYSTACK_SETUP.md` - This documentation

### Modified Files:
- `config_paystack.php` - Added support for store-specific keys
- `process_store_order.php` - Added Paystack payment initialization
- `store.php` - Added Paystack redirect handling
- `pages/store_dashboard.php` - Added Paystack settings link

## Security Features

1. **Payment Intent Verification**: Orders are linked to Paystack references before payment
2. **Amount Verification**: Payment amounts are verified against order amounts
3. **Idempotency**: Duplicate payment processing is prevented
4. **Store Isolation**: Each store uses its own Paystack credentials
5. **Transaction Rollback**: Failed operations are rolled back automatically

## Troubleshooting

### Payment Not Processing Automatically

1. Check if store has Paystack enabled in settings
2. Verify Paystack credentials are correct
3. Check error logs for callback errors
4. Verify webhook is configured in Paystack dashboard

### Orders Stuck in Pending

1. Check store owner's balance (must have sufficient balance for admin cost)
2. Verify external API is enabled (for MTN orders)
3. Check order status in database

### Paystack Redirect Not Working

1. Verify Paystack credentials are active
2. Check if callback URL is accessible
3. Verify amount matches (must be in pesewas for Paystack)

## Testing

1. **Test Paystack Payment**:
   - Use Paystack test keys
   - Place a test order
   - Complete payment with test card
   - Verify order is automatically processed

2. **Test Mobile Money Fallback**:
   - Disable Paystack for a store
   - Place an order
   - Verify Mobile Money instructions are shown

## Notes

- Store owners must have sufficient balance in their system account to process orders (admin cost is deducted)
- Paystack payments go directly to store owner's Paystack account
- The system's admin Paystack (used for top-ups) is separate from store Paystack accounts
- Each store can independently enable/disable Paystack payments


