POST /api/v1/send-money Payouts

Send Money (Mobile Money Payouts)

Disburse funds directly from your HivePay virtual wallet to any recipient phone on MTN or Airtel. If the provider rejects the payout, HivePay automatically issues a 100% immediate wallet refund.

Disbursement Safeguards

✓ 100% Instant Refund: If recipient network rejects transfer or phone is inactive, funds return to your wallet.
✓ Audited Ledger: Balance before and after are recorded in your immutable wallet ledger.
✓ Recipient Name Lookup: Validates recipient identity on MTN and Airtel.

Request Parameters (JSON Body)

Parameter	Type	Required	Description
phone_number	string	Required	Recipient mobile money number (MTN or Airtel e.g. `0777123456`).
amount	number	Required	Amount in UGX debited from your wallet. The tiered service fee is cut from this amount, so the recipient receives `amount - fee`. Must not exceed your wallet balance.
description	string	Required	Description for the payout ledger (e.g. `"Driver weekly payout"`).
reference	string	Optional	Your unique internal transaction ID for idempotency and reconciliation.

Code Example

curl -X POST https://hivepay.site/api/v1/send-money \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "X-Account-Number: YOUR_ACCOUNT_NUMBER" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "0777123456",
    "amount": 25000,
    "description": "Agent commission payout",
    "reference": "WD-9812"
  }'

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

$payload = [
    'phone_number' => '0777123456',
    'amount'       => 25000,
    'description'  => 'Agent commission payout',
    'reference'    => 'WD-9812'
];

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

$result = json_decode(curl_exec($ch), true);
curl_close($ch);

if ($result['success']) {
    echo "Payout Reference: " . $result['gateway_reference'];
}

const response = await fetch('https://hivepay.site/api/v1/send-money', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.HIVEPAY_API_KEY,
    'X-API-Secret': process.env.HIVEPAY_API_SECRET,
    'X-Account-Number': process.env.HIVEPAY_ACCOUNT_NUMBER,
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    phone_number: '0777123456',
    amount: 25000,
    description: 'Agent commission payout',
    reference: 'WD-9812'
  })
});

const data = await response.json();
console.log('Payout initiated:', data.gateway_reference);

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'),
    'Content-Type': 'application/json'
}

payload = {
    'phone_number': '0777123456',
    'amount': 25000,
    'description': 'Agent commission payout',
    'reference': 'WD-9812'
}

res = requests.post(
    'https://hivepay.site/api/v1/send-money',
    json=payload,
    headers=headers
)
print(res.json())

Success Response (200 OK)

Response JSON

{
  "success": true,
  "message": "Payout initiated successfully.",
  "reference": "WD-9812",
  "gateway_reference": "HP-PAY-ZX98WV76UT",
  "amount": 25000,
  "fee": 1800,
  "recipient_gets": 23200,
  "total_deducted": 25000,
  "currency": "UGX",
  "status": "pending"
}

← Card Checkout (USD) Next: Wallet Balance