Endpoint
POST https://api.rohopay.com/api/v1/disburse
| Header | Required | Value |
|---|
Authorization | ✅ | Bearer {live_api_key} |
Content-Type | ✅ | application/json |
Idempotency-Key | ✅ | UUID v4 |
Disbursements require a live API key. Requests with test_ keys return 403 DISBURSE_TEST_BLOCKED.
Request Body
{
"phone": "256700123456",
"amount": 25000,
"currency": "UGX",
"description": "Agent payout – July",
"callback_url": "https://your-app.com/webhooks/rohopay"
}
Response (200 OK)
{
"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",
"commission_amount": 500,
"net_amount": 24500,
"environment": "live",
"created_at": "2024-07-15T09:00:00Z"
}
}
Error Responses
| HTTP | Code | Description |
|---|
| 400 | VALIDATION_ERROR | Invalid phone, amount, or currency |
| 401 | UNAUTHORIZED | Invalid API key |
| 403 | DISBURSE_TEST_BLOCKED | Cannot disburse in test mode |
| 422 | INSUFFICIENT_BALANCE | Live wallet balance too low |
| 429 | RATE_LIMIT_EXCEEDED | Too many requests |
| 503 | PROVIDER_LINE_DOWN | Provider unavailable |
