​
Endpoint

POST /api/v1/disburse
Authorization: Bearer {live_api_key}
Idempotency-Key: {unique_uuid}
Content-Type: application/json
Disbursements require a live API key. They are blocked in test mode. Always verify your wallet balance before disbursing.

​
Request Body

​
phone
string
required
The recipient’s mobile number in international format without +. Example: 256700123456.
​
amount
integer
required
Amount in the smallest currency unit. Minimum disbursement is 1000 UGX.
​
currency
string
required
ISO 4217 currency code. Accepted: UGX, KES, TZS, RWF.
​
description
string
Human-readable reason for the transfer. Shown in provider transaction records.
​
callback_url
string
HTTPS URL to receive a webhook when disbursement status updates.

​
Example Request

curl -X POST https://api.rohopay.com/api/v1/disburse \
  -H "Authorization: Bearer live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "phone": "256700123456",
    "amount": 25000,
    "currency": "UGX",
    "description": "Agent commission payout – July 2024",
    "callback_url": "https://your-app.com/webhooks/rohopay"
  }'

​
Response

Same structure as collections, with type: "disbursement": 
{
  "success": true,
  "data": {
    "id": "01j5m6n7p8q9r0s1t2u3vwxy",
    "internal_reference": "RHP-2024-DISP001",
    "provider_reference": "0987654321",
    "status": "pending",
    "type": "disbursement",
    "payment_method": "mobile_money",
    "provider": "relworx",
    "phone_number": "256700123456",
    "amount": 25000,
    "currency": "UGX",
    "net_amount": 25000,
    "environment": "live",
    "created_at": "2024-07-15T09:00:00Z"
  }
}

​
Balance Check

Before disbursing, verify you have sufficient live balance: 
curl https://api.rohopay.com/api/v1/wallet/balance \
  -H "Authorization: Bearer live_YOUR_KEY"

{
  "success": true,
  "data": {
    "balance_live": 500000,
    "balance_test": 1000000,
    "currency": "UGX"
  }
}

​
Use Cases

Agent Payouts

Pay field agents, commission earners, or salesperson bonuses in real-time.

Marketplace Settlements

Settle vendor earnings from marketplace transactions automatically.

Salary Disbursements

Send salaries or allowances to employee mobile wallets.

Refunds

Return funds to customers after failed orders or cancellations.

​
Failover

If your preferred provider is unavailable, RohoPay automatically routes to the secondary provider. The failover_reason field on the transaction records why the switch occurred. 
{
  "failover_reason": "Primary provider (relworx) returned a timeout; retried with iotec",
  "provider": "iotec"
}