API reference
POST/disbursements

Create 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

Create a disbursement
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"
  }'

Parameters

NameLocationDetails
Idempotency-KeyheaderKeep the same UUID when retrying the same payment. Legacy X-NuePay-Request-Id is accepted.

Request body

FieldTypeDetails
amountrequiredstringWallet principal for collections; recipient amount for disbursements.
currencyrequiredstringUGX
phonerequiredstringUganda MTN or Airtel number; local or +256 format.
merchant_referencestringSee the response and related guide.
descriptionstringSee the response and related guide.

Example response

Illustrative sandbox 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

FieldTypeDetails
referencestringSee the response and related guide.
project_idstringSee the response and related guide.
application_idstringSee the response and related guide.
application_namestring or nullSee the response and related guide.
request_idstringSee the response and related guide.
idempotency_keystringSee the response and related guide.
merchant_referencestring or nullSee the response and related guide.
status_reasonstring or nullSee the response and related guide.
amountstringSee the response and related guide.
feestringSee the response and related guide.
gross_amountstringSee the response and related guide.
currencystringSee the response and related guide.
payer_chargestring or nullSee the response and related guide.
wallet_creditstring or nullSee the response and related guide.
recipient_amountstring or nullSee the response and related guide.
wallet_debitstring or nullSee the response and related guide.
created_atstringSee the response and related guide.
updated_atstringSee the response and related guide.
typestringcollection, disbursement
statusstringprocess, success, failed
status_labelstringSee the response and related guide.
modestringlive, test
livemodebooleanSee the response and related guide.
refundedbooleanSee the response and related guide.
versionintegerSee the response and related guide.

HTTP status codes

StatusMeaning
200Existing payment returned for an identical retry.
202Accepted for processing.
203Invalid credentials.
204Access unavailable or operation paused.
205Resource not found in this application and environment.
206Idempotency conflict, insufficient funds, or payout setup required.
207Invalid input; inspect errors and code.
208Rate limit exceeded.
209Live 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.

Made for builders. Built in Uganda.NuePay API v1

Search endpoints, guides and examples.