# Hubtel API Testing Guide

## Overview
This guide explains how to test your Hubtel payment gateway integration to ensure it's working correctly.

## Prerequisites
Before testing, you need:
1. Hubtel Unity account (https://unity.hubtel.com)
2. Client ID
3. Client Secret
4. Merchant Account Number (format: HM-XXXXXXXXXX)

## How to Get Hubtel Credentials

### Step 1: Sign Up/Login to Hubtel Unity
1. Go to https://unity.hubtel.com
2. Create an account or login
3. Complete your business verification

### Step 2: Get API Credentials
1. Navigate to **Settings** → **API Keys**
2. Copy your **Client ID**
3. Copy your **Client Secret**
4. Note your **Merchant Account Number** (found in Dashboard)

### Step 3: Configure in RMBXchange
1. Login to admin panel
2. Go to **Settings**
3. Select **Hubtel** as payment gateway
4. Enter your credentials:
   - Client ID
   - Client Secret
   - Merchant Account Number
5. Click **Save Settings**

## Testing Hubtel Connection

### Using the Test Button
1. After saving your Hubtel credentials
2. Click the **Test Connection** button in the Hubtel section
3. Wait for the response

### Expected Results

#### ✓ Success Response
```
✓ Hubtel API connection successful!
Merchant: Your Business Name
Account: HM-XXXXXXXXXX
Status: Active
```

#### ✗ Error Responses

**Missing Credentials:**
```
✗ Hubtel credentials not configured
client_id: Missing
client_secret: Missing
merchant_account: Missing
```
**Solution:** Fill in all three fields and save settings first.

**Authentication Failed:**
```
✗ Hubtel API connection failed
status_code: 401
error: Invalid credentials
```
**Solution:** Double-check your Client ID and Client Secret are correct.

**Invalid Merchant Account:**
```
✗ Hubtel API connection failed
status_code: 404
error: Merchant account not found
```
**Solution:** Verify your Merchant Account Number is correct (format: HM-XXXXXXXXXX).

## Testing Live Payments

### Test Mode
Hubtel provides test credentials for development:
- Use test credentials from Hubtel Unity dashboard
- Test transactions won't charge real money
- Use test phone numbers provided by Hubtel

### Production Mode
When ready for live payments:
1. Switch to production credentials in Hubtel Unity
2. Update credentials in RMBXchange admin settings
3. Test with small real transaction first
4. Monitor transactions in Hubtel Unity dashboard

## Payment Flow

### Customer Experience
1. Customer selects amount to pay
2. System initiates Hubtel payment
3. Customer receives mobile money prompt on phone
4. Customer enters PIN to approve
5. Payment confirmed automatically
6. Customer redirected to success page

### Admin Monitoring
1. View all transactions in **Admin → Orders**
2. Check payment status in Hubtel Unity dashboard
3. Receive notifications for successful payments

## Troubleshooting

### Connection Test Fails
1. Verify credentials are correct
2. Check internet connection
3. Ensure Hubtel account is active
4. Check `storage/logs/laravel.log` for detailed errors

### Payment Initialization Fails
1. Verify customer phone number is valid Ghana number
2. Check merchant account has sufficient balance/credit
3. Ensure mobile money network is available
4. Review Hubtel Unity dashboard for account issues

### Payment Not Completing
1. Customer must approve on their phone
2. Check customer has sufficient mobile money balance
3. Verify callback URL is accessible
4. Check Hubtel Unity dashboard for transaction status

## Support

### Hubtel Support
- Email: support@hubtel.com
- Phone: +233 30 281 8181
- Website: https://hubtel.com/support

### RMBXchange Logs
Check detailed error logs:
```bash
tail -f storage/logs/laravel.log
```

## Security Best Practices

1. **Never share credentials** - Keep Client Secret secure
2. **Use HTTPS** - Ensure your site uses SSL certificate
3. **Test thoroughly** - Use test mode before going live
4. **Monitor transactions** - Regularly check Hubtel dashboard
5. **Keep credentials updated** - Rotate keys periodically

## API Documentation
Full Hubtel API documentation: https://developers.hubtel.com/documentations/receive-money-online

---

**Last Updated:** April 21, 2026