# Hubtel Payment Gateway Integration

## Overview
Hubtel Ghana API has been integrated as an alternative payment method alongside Paystack. Users can now choose between Paystack and Hubtel when making payments for wallet top-ups and exchange orders.

## Features

### Dual Payment Gateway Support
- **Paystack**: Cards, Mobile Money, Bank Transfer
- **Hubtel**: Mobile Money (MTN, Vodafone, AirtelTigo)
- Admin can enable/disable each gateway independently
- Users see gateway selection only when multiple gateways are enabled

## Configuration

### Admin Settings
Navigate to Admin Dashboard → Settings → Payment Gateway Configuration

#### Paystack Settings
- Enable/Disable Paystack
- Paystack Public Key
- Paystack Secret Key

#### Hubtel Settings
- Enable/Disable Hubtel
- Hubtel Client ID
- Hubtel Client Secret
- Hubtel Merchant Account Number

### Environment Variables (.env)
```env
# Paystack Configuration
PAYSTACK_PUBLIC_KEY=pk_test_xxxxx
PAYSTACK_SECRET_KEY=sk_test_xxxxx

# Hubtel Configuration
HUBTEL_CLIENT_ID=your_client_id
HUBTEL_CLIENT_SECRET=your_client_secret
HUBTEL_MERCHANT_ACCOUNT=HM-XXXXXXXXXX
HUBTEL_API_URL=https://api.hubtel.com/v1
```

## How It Works

### Payment Flow

#### 1. User Initiates Payment
- User creates an exchange order or wallet top-up
- System shows available payment gateways
- User selects preferred gateway (Paystack or Hubtel)

#### 2. Payment Processing

**Paystack Flow:**
1. User clicks "Proceed to Payment"
2. Redirected to Paystack checkout page
3. Completes payment (card, mobile money, etc.)
4. Redirected back to application
5. Payment verified via Paystack API
6. Transaction completed

**Hubtel Flow:**
1. User clicks "Proceed to Payment"
2. Hubtel sends payment prompt to user's phone
3. User shown waiting page
4. User completes payment on mobile phone
5. Hubtel sends callback to application
6. Transaction completed

#### 3. Payment Verification
- Both gateways trigger callbacks to verify payment
- System updates transaction status
- User wallet credited (for top-ups)
- Order status updated (for exchanges)
- Notifications sent (email, SMS, in-app)

### Gateway Selection Logic
```php
// If both gateways enabled: Show selection UI
// If only Paystack enabled: Use Paystack automatically
// If only Hubtel enabled: Use Hubtel automatically
// If neither enabled: Show error message
```

## Files Modified/Created

### New Files
1. `config/hubtel.php` - Hubtel configuration
2. `resources/views/payment-waiting.blade.php` - Hubtel payment waiting page
3. `HUBTEL_INTEGRATION.md` - This documentation

### Modified Files
1. `app/Http/Controllers/PaymentController.php`
   - Added `initializeHubtelPayment()` method
   - Added `handleHubtelCallback()` method
   - Added `hubtelWaiting()` method
   - Refactored `initializePayment()` to support multiple gateways
   - Extracted `processSuccessfulPayment()` for code reuse

2. `app/Http/Controllers/Admin/AdminController.php`
   - Added Hubtel settings to `settings()` method
   - Added Hubtel validation to `updateSettings()` method

3. `resources/views/admin/settings.blade.php`
   - Restructured payment gateway section
   - Added Hubtel configuration fields
   - Added enable/disable toggles for both gateways

4. `resources/views/payment-confirm.blade.php`
   - Added gateway selection UI
   - Added JavaScript for gateway switching

5. `resources/views/wallet-topup-payment.blade.php`
   - Added gateway selection UI
   - Added JavaScript for gateway switching

6. `routes/web.php`
   - Added Hubtel callback route
   - Added Hubtel waiting page route

7. `.env.example`
   - Added Hubtel configuration variables

## API Endpoints

### Payment Initialization
```
POST /payment/initialize
Parameters:
  - type: 'order' or 'topup'
  - gateway: 'paystack' or 'hubtel'
  - order_id or transaction_id
```

### Paystack Callback
```
GET /payment/callback?reference={reference}
```

### Hubtel Callback
```
POST /payment/hubtel/callback
Parameters:
  - ClientReference: Order/Transaction reference
  - Status: 'Success', 'Failed', 'Pending'
```

### Hubtel Waiting Page
```
GET /payment/hubtel/waiting/{reference}
```

## Hubtel API Integration

### Authentication
Hubtel uses HTTP Basic Authentication with Client ID and Client Secret.

### Receive Money Online API
```php
POST https://api.hubtel.com/v1/merchantaccount/merchants/{merchant_account}/receive/mobilemoney

Headers:
  Authorization: Basic {base64(client_id:client_secret)}

Body:
{
  "CustomerName": "John Doe",
  "CustomerMsisdn": "0244123456",
  "CustomerEmail": "john@example.com",
  "Channel": "mtn-gh", // or vodafone-gh, airtel-tigo-gh
  "Amount": 100.00,
  "PrimaryCallbackUrl": "https://yoursite.com/payment/hubtel/callback",
  "Description": "RMBXchange - Wallet Top-up",
  "ClientReference": "TOP-ABC123"
}
```

### Response
```json
{
  "TransactionId": "12345",
  "ClientReference": "TOP-ABC123",
  "Status": "Pending",
  "Message": "Payment initiated successfully"
}
```

## Testing

### Test Credentials
Get test credentials from [Hubtel Unity Dashboard](https://unity.hubtel.com)

### Test Flow
1. Enable Hubtel in admin settings
2. Add test credentials
3. Create a wallet top-up or exchange order
4. Select Hubtel as payment method
5. Use test phone number for mobile money prompt
6. Complete payment on test phone
7. Verify transaction completion

## Security Considerations

1. **API Credentials**: Store in database settings, not in code
2. **HTTPS Required**: All API calls use HTTPS
3. **Callback Verification**: Verify callback authenticity
4. **Duplicate Prevention**: Check transaction status before processing
5. **Error Logging**: All errors logged for debugging

## Troubleshooting

### Payment Not Completing
- Check Hubtel credentials are correct
- Verify merchant account is active
- Check callback URL is accessible
- Review Laravel logs for errors

### Callback Not Received
- Ensure callback URL is publicly accessible
- Check firewall/security settings
- Verify Hubtel webhook configuration
- Test callback URL manually

### Gateway Not Showing
- Verify gateway is enabled in admin settings
- Check credentials are saved
- Clear application cache

## Support

### Hubtel Support
- Website: https://hubtel.com
- Dashboard: https://unity.hubtel.com
- Documentation: https://developers.hubtel.com

### Paystack Support
- Website: https://paystack.com
- Dashboard: https://dashboard.paystack.com
- Documentation: https://paystack.com/docs

## Future Enhancements

1. Add more payment channels (bank transfer, USSD)
2. Support for recurring payments
3. Payment analytics and reporting
4. Refund functionality
5. Multi-currency support
6. Payment link generation