Hubtel Payment Gateway

Authentication

Hubtel uses HTTP Basic Authentication for all API requests. You must provide a Base64-encoded string of your ClientID and ClientSecret in the Authorization header.

Getting API Credentials

ℹ️ Self-service signup now available. Hubtel has introduced self-service merchant registration at https://unity.hubtel.com. You can create an account and generate API keys without needing to email support, though full activation for live transactions still requires business verification.

1. Register at https://unity.hubtel.com or contact [email protected] for enterprise onboarding
2. Log in to your merchant dashboard at https://unity.hubtel.com
3. Navigate to API accounts section and select "Request For New API Keys"
4. Choose "HTTP Rest API" as the API type
5. Provide a description for your application
6. Save and your ClientID, ClientSecret, and Account Number will be displayed

⚠️ API versioning note: Hubtel has been reorganising their API ecosystem. The primary collection/disbursement API currently documents at payproxyapi.hubtel.com, while newer endpoints may appear under api.hubtel.com/v2/. If you encounter 404s on the paths documented here, check the Hubtel developer portal for the current base URLs — they have been updated without redirect in past migrations.

Authentication Header Format

# Step 1: Create Base64 string
# base64_encode("YOUR_CLIENT_ID:YOUR_CLIENT_SECRET")

# Step 2: Add to request header
Authorization: Basic {base64_encoded_credentials}

Example Implementation

// Node.js example
const clientId = "your_client_id";
const clientSecret = "your_client_secret";
const credentials = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');

const headers = {
  "Authorization": `Basic ${credentials}`,
  "Content-Type": "application/json"
};

# Python example
import base64
import requests

client_id = "your_client_id"
client_secret = "your_client_secret"
credentials = base64.b64encode(f"{client_id}:{client_secret}".encode()).decode()

headers = {
    "Authorization": f"Basic {credentials}",
    "Content-Type": "application/json"
}

// PHP example
$clientId = "your_client_id";
$clientSecret = "your_client_secret";
$credentials = base64_encode("{$clientId}:{$clientSecret}");

$headers = [
    "Authorization: Basic {$credentials}",
    "Content-Type: application/json"
];

Core API Reference

Base URL