API reference
POST
/disbursementsCreate a disbursement
Send mobile money from the wallet
Overview
Send money from the merchant wallet to an MTN or Airtel mobile number. The amount is what the recipient receives. The principal plus fee is debited when the request is accepted.
A verified bank payout method and sufficient available balance are required. Payout principals must be whole UGX. Uncertain outcomes retain the debit pending reconciliation. A confirmed failure refunds once; inspect refunded and the latest status.
Example request
curl https://api.nuepay.net/v1/disbursements \
-H "Authorization: Bearer $NUEPAY_TEST_KEY" \
-H "Idempotency-Key: $PAYMENT_UUID" \
-H 'Content-Type: application/json' \
-d '{
"amount": "500.00",
"currency": "UGX",
"phone": "0772000000",
"merchant_reference": "order-123"
}'// Persist this UUID with your order; reuse it when retrying.
const response = await fetch('https://api.nuepay.net/v1/disbursements', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.NUEPAY_TEST_KEY}`,
'Idempotency-Key': paymentUuid,
'Content-Type': 'application/json',
},
body: JSON.stringify({
amount: '500.00', currency: 'UGX',
phone: '0772000000', merchant_reference: 'order-123',
}),
});
const result = await response.json();
if (!response.ok) throw new Error(result.message);
console.log(result.data);$curl = curl_init('https://api.nuepay.net/v1/disbursements');
curl_setopt_array($curl, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer '.getenv('NUEPAY_TEST_KEY'),
'Idempotency-Key: '.$paymentUuid, // Reuse for retries.
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'amount' => '500.00', 'currency' => 'UGX',
'phone' => '0772000000', 'merchant_reference' => 'order-123',
]),
]);
$body = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
if ($body === false || $status < 200 || $status >= 300) {
throw new RuntimeException('Inspect the error and retry safely.');
}
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);import json, os, urllib.request
request = urllib.request.Request(
'https://api.nuepay.net/v1/disbursements',
method='POST',
headers={
'Authorization': 'Bearer ' + os.environ['NUEPAY_TEST_KEY'],
'Idempotency-Key': payment_uuid, # Reuse for retries.
'Content-Type': 'application/json',
},
data=json.dumps({
'amount': '500.00', 'currency': 'UGX',
'phone': '0772000000', 'merchant_reference': 'order-123',
}).encode(),
)
with urllib.request.urlopen(request, timeout=30) as response:
result = json.load(response)
print(result['data'])Parameters
| Name | Location | Details |
|---|---|---|
Idempotency-Key | header | Keep the same UUID when retrying the same payment. Legacy X-NuePay-Request-Id is accepted. |
Request body
| Field | Type | Details |
|---|---|---|
amountrequired | string | Wallet principal for collections; recipient amount for disbursements. |
currencyrequired | string | UGX |
phonerequired | string | Uganda MTN or Airtel number; local or +256 format. |
merchant_reference | string | See the response and related guide. |
description | string | See the response and related guide. |
Example response
{
"data": {
"reference": "NPTEXAMPLE01",
"project_id": "00000000-0000-4000-8000-000000000001",
"application_id": "00000000-0000-4000-8000-000000000001",
"application_name": "Online store",
"request_id": "00000000-0000-4000-8000-000000000002",
"idempotency_key": "00000000-0000-4000-8000-000000000002",
"merchant_reference": "order-123",
"type": "disbursement",
"status": "process",
"status_label": "Pending",
"status_reason": null,
"refunded": false,
"amount": "500.00",
"fee": "1000.00",
"gross_amount": "1500.00",
"currency": "UGX",
"mode": "test",
"livemode": false,
"version": 0,
"payer_charge": null,
"wallet_credit": null,
"recipient_amount": "500.00",
"wallet_debit": "1500.00"
}
}Examples omit timestamps for readability. Use POST /quotes to confirm current fees rather than hard-coding these examples.
Response fields
| Field | Type | Details |
|---|---|---|
reference | string | See the response and related guide. |
project_id | string | See the response and related guide. |
application_id | string | See the response and related guide. |
application_name | string or null | See the response and related guide. |
request_id | string | See the response and related guide. |
idempotency_key | string | See the response and related guide. |
merchant_reference | string or null | See the response and related guide. |
status_reason | string or null | See the response and related guide. |
amount | string | See the response and related guide. |
fee | string | See the response and related guide. |
gross_amount | string | See the response and related guide. |
currency | string | See the response and related guide. |
payer_charge | string or null | See the response and related guide. |
wallet_credit | string or null | See the response and related guide. |
recipient_amount | string or null | See the response and related guide. |
wallet_debit | string or null | See the response and related guide. |
created_at | string | See the response and related guide. |
updated_at | string | See the response and related guide. |
type | string | collection, disbursement |
status | string | process, success, failed |
status_label | string | See the response and related guide. |
mode | string | live, test |
livemode | boolean | See the response and related guide. |
refunded | boolean | See the response and related guide. |
version | integer | See the response and related guide. |
HTTP status codes
| Status | Meaning |
|---|---|
200 | Existing payment returned for an identical retry. |
202 | Accepted for processing. |
203 | Invalid credentials. |
204 | Access unavailable or operation paused. |
205 | Resource not found in this application and environment. |
206 | Idempotency conflict, insufficient funds, or payout setup required. |
207 | Invalid input; inspect errors and code. |
208 | Rate limit exceeded. |
209 | Live provider unavailable; accepted payments can still be read or retried. |
Errors contain a stable code and support request_id. See error handling for recovery guidance.

