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:

1. The customer selects the mobile operator and fills the phone number and other needed fields;

2. Merchant makes a request to create mobile money payout;

3. Rumbapay process the payout, interacts with the provider;

4. 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

Country	ISO A-2	Operator
Kenya	KE	mpesa, airtel
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": "[phone]", // 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": "[e-mail]", // optional
    "phone": "[phone]", // 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": "MOB[phone]",
    "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:

1. Rumbapay processes the payout request

2. When the payout status changes to a terminal state, Rumbapay sends an HTTP POST request to your callback URL

3. Your server should process the callback, validate the signature, and update your system

4. Your server should respond with HTTP 200 OK to acknowledge receipt

Example

{
    "identifier": "MOB[phone]",
    "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": "MOB[phone]",
    "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"
}