POST /api/v1/collect-money MTN • Airtel

Collect Money (Mobile Money Deposit)

Requests mobile money from a customer. When invoked, HivePay dispatches an interactive USSD push prompt directly to the customer's phone screen. The customer enters their Mobile Money PIN to approve the transaction.

Want to test this endpoint right now?

Launch an actual USSD prompt directly to your phone using our interactive live test runner.

Run Live Test →

Payment Lifecycle

1. API Request

Your server calls /collect-money with amount & phone.

2. USSD Prompt

Customer sees PIN prompt on their mobile screen instantly.

3. PIN Entered

Customer approves. Funds settle to your merchant wallet.

4. Webhook Fired

HivePay delivers a signed webhook to your callback URL.

Request Parameters (JSON Body)

Parameter	Type	Required	Description
phone_number	string	Required	Customer's mobile money phone number (e.g. `0777123456` or `+256777123456`). Supported on MTN & Airtel Uganda.
amount	number	Required	Amount in UGX to collect from the customer. Minimum is 500 UGX, maximum is 5,000,000 UGX.
description	string	Required	Payment reason shown to the customer (e.g. `"Order #1001"`). Max 100 characters.
reference	string	Optional	Your unique internal transaction identifier. Stored and returned in all responses and webhooks. Max 40 chars, no spaces.
currency	string	Optional	Defaults to `UGX`. Also supports KES, GHS, XAF where available.
webhook_url	string	Optional	Custom callback endpoint to override your default merchant webhook for this transaction.

Code Example

curl -X POST https://hivepay.site/api/v1/collect-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": 50000,
    "reference": "ORDER-98765",
    "description": "Order #98765 payment"
  }'

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

$payload = [
    'phone_number' => '0777123456',
    'amount'       => 50000,
    'reference'    => 'ORDER-98765',
    'description'  => 'Order #98765 payment'
];

$ch = curl_init('https://hivepay.site/api/v1/collect-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"
    ]
]);

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

$result = json_decode($response, true);
if ($result['success']) {
    echo "Prompt sent to phone! Reference: " . $result['gateway_reference'];
}

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/collect-money', {
  method: 'POST',
  headers: {
    'X-API-Key': apiKey,
    'X-API-Secret': apiSecret,
    'X-Account-Number': accountNumber,
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    phone_number: '0777123456',
    amount: 50000,
    reference: 'ORDER-98765',
    description: 'Order #98765 payment'
  })
});

const result = await response.json();
if (result.success) {
  console.log('Collection initiated! Gateway ref:', result.gateway_reference);
}

import os, requests

url = 'https://hivepay.site/api/v1/collect-money'
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'
}
data = {
    'phone_number': '0777123456',
    'amount': 50000,
    'reference': 'ORDER-98765',
    'description': 'Order #98765 payment'
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

Success Response (200 OK)

Response JSON

{
  "success": true,
  "message": "Collection request initiated. Prompt sent to customer phone.",
  "reference": "ORDER-98765",
  "gateway_reference": "HP-COL-AB12CD34EF",
  "amount": 50000,
  "net_credited": 48500,
  "currency": "UGX",
  "status": "pending",
  "network": "MTN"
}

Note: The transaction begins in pending status. When the customer enters their PIN, your webhook endpoint receives a signed transaction.success notification.

← Status Codes & Errors Next: Card Checkout (USD)