Security & Headers

Authentication & API Keys

All requests to the HivePay Gateway API must be authenticated using your merchant API key passed via standard HTTP headers.

Environment Base URLs

Environment	Base URL	Status
Production	https://hivepay.site/api/v1	Live

Merchant Credentials & Headers

Every merchant account on HivePay is provisioned with a triad of credentials: an API Key, a confidential API Secret, and a unique Account Number (e.g. HP2609562857).

Header	Status	Type	Description & Purpose
X-API-Key	REQUIRED	string	Your merchant API Key (e.g. `ph_...`). Identifies which merchant account is initiating the API call.
X-API-Secret	HIGHLY RECOMMENDED	string (64-char)	Your private server credential. Proves that the request is genuinely from your backend server and not an intercepted client-side call.
X-Account-Number	RECOMMENDED	string	Your HivePay Merchant Account Number (e.g. `HP2609562857`). Ensures transactions route strictly to your settlement wallet.
X-Signature	OPTIONAL	string (HMAC-SHA256)	Cryptographic payload hash computed via `hash_hmac('sha256', $body, $apiSecret)` for tamper-proof payload integrity.
Content-Type	POST ONLY	string	Set to `application/json` on all POST/PUT requests.

What is the Purpose of the API Secret?

In modern financial APIs, an API Key is often used as a public identifier, but it alone does not provide complete protection against credential leaks or payload tampering. The API Secret provides three vital security pillars:

🔒 1. Server-to-Server Auth

Passing X-API-Secret guarantees requests originate from your secure backend server, blocking unauthorized frontend calls.

✍ 2. Request Signing (HMAC)

You can hash request bodies using your API Secret into an X-Signature header. Nobody can alter amounts or numbers in flight.

📡 3. Webhook Authentication

Use your secrets to verify incoming webhook alerts from HivePay, confirming payments are legitimate before crediting customers.

Verification Request

Verify that your credentials function properly by querying the wallet balance endpoint:

curl -X GET https://hivepay.site/api/v1/balance \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "X-Account-Number: YOUR_ACCOUNT_NUMBER" \
  -H "Accept: application/json"

<?php
$apiKey        = getenv('HIVEPAY_API_KEY');
$apiSecret     = getenv('HIVEPAY_API_SECRET');
$accountNumber = getenv('HIVEPAY_ACCOUNT_NUMBER');

$ch = curl_init('https://hivepay.site/api/v1/balance');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "X-API-Key: {$apiKey}",
        "X-API-Secret: {$apiSecret}",
        "X-Account-Number: {$accountNumber}",
        "Accept: application/json"
    ]
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    echo "Authenticated successfully! " . $response;
} else {
    echo "Authentication failed with status: " . $httpCode;
}

const apiKey        = process.env.HIVEPAY_API_KEY;
const apiSecret     = process.env.HIVEPAY_API_SECRET;
const accountNumber = process.env.HIVEPAY_ACCOUNT_NUMBER;

const response = await fetch('https://hivepay.site/api/v1/balance', {
  headers: {
    'X-API-Key': apiKey,
    'X-API-Secret': apiSecret,
    'X-Account-Number': accountNumber,
    'Accept': 'application/json'
  }
});

if (response.ok) {
  const data = await response.json();
  console.log('Authenticated! Wallet balance:', data.wallet_balance);
} else {
  console.error('Authentication error:', response.status);
}

import os, requests

headers = {
    'X-API-Key': os.getenv('HIVEPAY_API_KEY'),
    'X-API-Secret': os.getenv('HIVEPAY_API_SECRET'),
    'X-Account-Number': os.getenv('HIVEPAY_ACCOUNT_NUMBER'),
    'Accept': 'application/json'
}

response = requests.get('https://hivepay.site/api/v1/balance', headers=headers)

if response.status_code == 200:
    print("Authenticated! Balance:", response.json())
else:
    print("Authentication failed:", response.status_code)

Cryptographic Request Signing (HMAC-SHA256)

HIGH SECURITY

For maximum financial security, you can use your API Secret to sign POST request bodies with HMAC-SHA256. Pass the resulting hash in the X-Signature header. HivePay verifies that the payload has not been intercepted or tampered with in transit:

<?php
$apiSecret = getenv('HIVEPAY_API_SECRET');
$payload   = json_encode([
    'phone_number' => '0777123456',
    'amount'       => 50000,
    'description'  => 'Payment for Order #1042'
]);

// Generate cryptographic HMAC-SHA256 signature using your API Secret
$signature = hash_hmac('sha256', $payload, $apiSecret);

$ch = curl_init('https://hivepay.site/api/v1/collect-money');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "X-API-Key: " . getenv('HIVEPAY_API_KEY'),
        "X-API-Secret: {$apiSecret}",
        "X-Account-Number: " . getenv('HIVEPAY_ACCOUNT_NUMBER'),
        "X-Signature: {$signature}",
        "Content-Type: application/json"
    ]
]);

$response = curl_exec($ch);
curl_close($ch);

import crypto from 'crypto';

const apiSecret = process.env.HIVEPAY_API_SECRET;
const payload   = JSON.stringify({
  phone_number: '0777123456',
  amount: 50000,
  description: 'Payment for Order #1042'
});

// Compute HMAC-SHA256 signature using your API Secret
const signature = crypto
  .createHmac('sha256', apiSecret)
  .update(payload)
  .digest('hex');

const response = await fetch('https://hivepay.site/api/v1/collect-money', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.HIVEPAY_API_KEY,
    'X-API-Secret': apiSecret,
    'X-Account-Number': process.env.HIVEPAY_ACCOUNT_NUMBER,
    'X-Signature': signature,
    'Content-Type': 'application/json'
  },
  body: payload
});

import os, json, hmac, hashlib, requests

api_secret = os.getenv('HIVEPAY_API_SECRET')
payload = json.dumps({
    'phone_number': '0777123456',
    'amount': 50000,
    'description': 'Payment for Order #1042'
})

# Compute HMAC-SHA256 signature using your API Secret
signature = hmac.new(api_secret.encode(), payload.encode(), hashlib.sha256).hexdigest()

headers = {
    'X-API-Key': os.getenv('HIVEPAY_API_KEY'),
    'X-API-Secret': api_secret,
    'X-Account-Number': os.getenv('HIVEPAY_ACCOUNT_NUMBER'),
    'X-Signature': signature,
    'Content-Type': 'application/json'
}

response = requests.post('https://hivepay.site/api/v1/collect-money', data=payload, headers=headers)

API Key Protection Guidelines

Never embed your API key directly in client-side code, mobile apps, or public Git repositories.
Store keys in encrypted environment variables (e.g. .env).
If an API key is accidentally exposed, immediately revoke and regenerate it from your Settings panel.

← Overview Next: Status Codes & Errors