Payout
Overview
The Rumbapay Payout API allows you to make payouts to your clients' bank accounts. This document provides instructions on how to create and manage bank transfer payouts.
How exactly Mobile Money Payout works:
The customer selects the mobile operator and fills the phone number and other needed fields;
Merchant makes a request to create mobile money payout;
Rumbapay process the payout, interacts with the provider;
Rumbapay sends a webhook to the merchant once the transaction status becomes terminal.
Base URL:
https://api.rumbapay.online/v1/
Data Format: JSON
HTTP Methods: POST, GET
List of available operators
Kenya
KE
mpesa, airtel, airtel kenya
Tanzania
TZ
vodacom, tigo, halopesa, airtel
Ghana
GH
vodafone, mtn, airteltigo
Gambia
GM
qcell, wave, africel
Cameroon
CM
mtn, orange
Initialize Payout
Method: HTTP POST
URL: https://api.rumbapay.online/v1/payout
Request Body:
{
"method": "mobile_money", // required
"reference": "1234-dfgdgfdfew", // required, unique
"currency": "KES", // required
"amount": 2500, // required
"description": "My order payin", // optional
"mobile_money": { // required
"phone": "+254712973246", // required
"operator": "mpesa", // conditional
"beneficiary_first_name": "Oki", // conditional
"beneficiary_last_name": "Doki", // conditional
"beneficiary_document_type": "national_id", // conditional
"beneficiary_document_value": "7876543" // conditional
},
"customer": { // required
"identifier": "1111-1111-2211-2211", // required
"email": "juancarlos@hotmail.com", // optional
"phone": "+2250504432244", // required
"first_name": "Juan", // required
"last_name": "García Rodríguez", // required
"middle_name": "Carlos", // optional
"country": "KE", // optional
"state_code": "B", // optional
"city": "Buenos Aires", // optional
"address": "Calle Emilio Mitre 3256", // optional
"zip_code": "C1407", // optional
"itn": "12345678910", // optional
"birthday": "2006-01-02", // optional
"ip": "192.168.0.1", // optional
"gender": "male" // optional
},
"callback_url": "https://merchant.shop.com/callback/success", // conditional
"extra": // conditional, any field which may be needed for transaction routing and integration
[{"key_1":"value"},{"key_2":"value"},{"key_3":"value"},{"key_4":"value"}]
}Response (Success):
{
"identifier": "MOB000137185",
"request_id": "6ae8671e-6b6f-4678-981a-36a783aa73ec",
"reference": "1234-dfgdgfdfew",
"description": "My order payin",
"status": {
"name": "pending",
"date": "2025-08-27T08:27:49.014"
},
"created_date": "2025-08-27T08:27:45.764",
"amount": 2500,
"billing_amount": 2500,
"currency": "KES",
"extra": [
{
"key": "key_2",
"value": "value"
},
{
"key": "key_3",
"value": "value"
},
{
"key": "key_4",
"value": "value"
},
{
"key": "key_1",
"value": "value"
}
],
"timestamp": "2025-08-27T08:27:49.2818969Z",
"error_code": 0,
"error_message": ""
}Response - 400 Bad request
{
"error_code": 30,
"error_reason": "Invalid params",
"request_id": "15195dfe-95dd-4916-95e2-b9696cff61ba",
"error_fields": [
{
"field": "currency",
"message": "currency is a required field"
}
],
"timestamp": "2025-04-11T16:58:57.11Z"
}Callback
On every completed Payout we send a callback notification to the URL you passed in the request in the callback_url field.
We strongly recommend validating the callback signature to avoid suspicious activity. Follow the signature docs to prepare callback verification.
Callback flow
The callback flow follows these steps:
Rumbapay processes the payout request
When the payout status changes to a terminal state, Rumbapay sends an HTTP POST request to your callback URL
Your server should process the callback, validate the signature, and update your system
Your server should respond with HTTP 200 OK to acknowledge receipt
Example
{
"identifier": "MOB000137185",
"request_id": "6ae8671e-6b6f-4678-981a-36a783aa73ec",
"reference": "1234-dfgdgfdfew",
"description": "My order payin",
"status": {
"name": "success",
"date": "2025-08-27T08:27:49.014"
},
"created_date": "2025-08-27T08:27:45.764",
"amount": 2500,
"billing_amount": 2500,
"currency": "KES",
"extra": [
{
"key": "key_2",
"value": "value"
},
{
"key": "key_3",
"value": "value"
},
{
"key": "key_4",
"value": "value"
},
{
"key": "key_1",
"value": "value"
}
],
"timestamp": "2025-08-27T08:27:49.2818969Z",
"error_code": 0,
"error_message": ""
}Check Payout Status
Method: HTTP GET
URL: https://api.rumbapay.online/v1/transaction/{request_id}
Response (Success):
{
"identifier": "MOB000137185",
"request_id": "6ae8671e-6b6f-4678-981a-36a783aa73ec",
"reference": "1234-dfgdgfdfew",
"description": "My order payin",
"status": {
"name": "success",
"date": "2025-08-27T08:27:49.014"
},
"created_date": "2025-08-27T08:27:45.764",
"amount": 2500,
"billing_amount": 2500,
"currency": "KES",
"extra": [
{
"key": "key_2",
"value": "value"
},
{
"key": "key_3",
"value": "value"
},
{
"key": "key_4",
"value": "value"
},
{
"key": "key_1",
"value": "value"
}
],
"timestamp": "2025-08-27T08:27:49.2818969Z",
"error_code": 0,
"error_message": ""
}Response (Not Found):
Transaction not found
{
"error_code": 101,
"error_reason": "Transaction not found",
"request_id": "5cf038ba-a5a8-43e8-9419-7a2a0932068f",
"timestamp": "2025-04-11T16:58:57.11Z"
}Last updated