Payment

Overview

Base URLs: https://api.rumbapay.online/v1/

Data Format: JSON

HTTP Methods: POST, PUT, GET

---

Initialize payment

When creating a payment using the method https://api.rumbapay.online/v1/payment you must inspect the challenge.challenge_type field to determine the appropriate flow.

For this type of payment, you must set widget.method = mobile_money and use the currency KES.

Otherwise, you may receive the following error: 273:Invalid adapter route configuration

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
Ivory Coast	CI	orange, mtn, moov, wave

Method: HTTP POST

URL: https://api.rumbapay.online/v1/payment

Request Body Type HPP:

{
  "widget": { // required
    "method": "mobile_money", // required
    "locale": "en" // optional
  },
  "reference": "1234-fdfgrem", // required, unique
  "currency": "KES", // required
  "amount": 1000, // required
  "description": "My order payin", // optional
  "mobile_money": { // required
     "phone": "[phone]" // required
  },
  "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": "UA", // 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
  },
  "redirect_url": "https://merchant.shop.com/", // optional
  "cancel_url": "https://merchant.shop.com/cancel", // 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"}]
}

Request Body Type H2H:

{
  "method": "mobile_money", // required
  "mode": "initial", // required, only "initial" for this method
  "reference": "1234-fdfgrem", // required, unique
  "currency": "KES", // required
  "amount": 1000, // required
  "description": "My order payin", // optional
  "channel_code": "mpesa", // required, value from List of available operators above
  "mobile_money": { // required
     "phone": "[phone]" // required
  },
  "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
  },
  "redirect_url": "https://merchant.shop.com/", // optional
  "cancel_url": "https://merchant.shop.com/cancel", // 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):

Response - 200 OK

1. First, you should check error_code field of response.

   If error_code field is not equals to 0 - transaction is Failed.

2. Second, you should check status field.

   The status field will always be set to created if there are no errors.

   Make check request or wait for a callback to get final transaction status.

Challenge type: redirect

{
    "identifier": "P2C000000381",
    "request_id": "fcd9927b-0528-4568-b29c-63d89e7f50c6",
    "reference": "564889b8-d61f-4e8e-a573-598739feafbb",
    "description": "My order h2h",
    "status": {
        "name": "created",
        "date": "2025-06-06T15:43:37.4530503Z"
    },
    "created_date": "2025-06-06T15:43:30.387",
    "amount": 1000,
    "billing_amount": 1000,
    "currency": "KES",
    "challenge": {
        "challenge_type": "redirect",
        "challenge_redirect": {
            "url": "https://rumba.ms/p/6c96ee77-085b-487c-9ec2-48144c56315f/confirm"
        }
    },
    "timestamp": "2025-06-06T15:43:37.7864915Z",
    "error_code": 0,
    "error_message": ""
}

If the challenge.challenge_type is set to redirect, you must send your Customer to the URL specified in challenge.challenge_redirect.url.

---

Customer can complete the payment by either scanning the barcode with their banking app or manually transferring the funds using the payment details — both the barcode and payment information are available on the page at challenge.challenge_redirect.url.

Rumbapay sends a callback to the merchant's callback URL when the payment reaches a terminal state (success, error, etc.)

Challenge type: stk

{
    "identifier": "P2C000000381",
    "request_id": "fcd9927b-0528-4568-b29c-63d89e7f50c6",
    "reference": "564889b8-d61f-4e8e-a573-598739feafbb",
    "description": "My order h2h",
    "status": {
        "name": "created",
        "date": "2025-06-06T15:43:37.4530503Z"
    },
    "created_date": "2025-06-06T15:43:30.387",
    "amount": 1000,
    "billing_amount": 1000,
    "currency": "KES",
    "challenge": {
        "challenge_type": "stk"
    },
    "timestamp": "2025-06-06T15:43:37.7864915Z",
    "error_code": 0,
    "error_message": ""
}

If the challenge.challenge_type is set to redirect, you must send your Customer to the URL specified in challenge.challenge_redirect.url.

Challenge type: otp

{
    "identifier": "P2C000000381",
    "request_id": "fcd9927b-0528-4568-b29c-63d89e7f50c6",
    "reference": "564889b8-d61f-4e8e-a573-598739feafbb",
    "description": "My order h2h",
    "status": {
        "name": "created",
        "date": "2025-06-06T15:43:37.4530503Z"
    },
    "created_date": "2025-06-06T15:43:30.387",
    "amount": 1000,
    "billing_amount": 1000,
    "currency": "KES",
    "challenge": {
        "challenge_type": "otp"
    },
    "timestamp": "2025-06-06T15:43:37.7864915Z",
    "error_code": 0,
    "error_message": ""
}

If the challenge.challenge_type is set to redirect, you must send your Customer to the URL specified in challenge.challenge_redirect.url.

Complete otp

Use the URL: https://api.rumbapay.online/v1/payment/challenge/otp

{
    "reference": "order1111", // string, required
    "otp": "625424" // required
}

Response

{
    "identifier": "P2C000000381",
    "request_id": "fcd9927b-0528-4568-b29c-63d89e7f50c6",
    "reference": "564889b8-d61f-4e8e-a573-598739feafbb",
    "description": "My order h2h",
    "status": {
        "name": "pending",
        "date": "2025-06-06T15:43:37.4530503Z"
    },
    "created_date": "2025-06-06T15:43:30.387",
    "amount": 1000,
    "billing_amount": 1000,
    "currency": "KES",
    "challenge": {
        "challenge_type": "otp"
    },
    "timestamp": "2025-06-06T15:43:37.7864915Z",
    "error_code": 0,
    "error_message": ""
}

---

Response - 400 Bad request

{
    "error_code": 30,
    "error_reason": "Invalid params",
    "request_id": "f4d30fac-7da9-4fa0-8918-46d56f7d38b0",
    "error_fields": [
        {
            "field": "reference",
            "message": "reference is a required field"
        }
    ],
    "timestamp": "2025-04-11T16:58:57.11Z"
}

If incorrect values are provided for widget.method or currency, you may receive the following response:

{
    "error_code": 273,
    "error_message": "Invalid adapter route configuration"
}

---

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 payment request

2. When the payment 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": "P2C000000387",
  "request_id": "c45bca03-1d39-4d27-b2e6-60b821544e4e",
  "reference": "39d21d0a-1fe2-4f77-969e-be4894520f4f",
  "description": "My order h2h",
  "status": {
    "name": "success",
    "date": "2025-06-06T16:02:47.757"
  },
  "created_date": "2025-06-06T16:01:33.224",
  "amount": 1000,
  "billing_amount": 1000,
  "currency": "KES",
  "extra": [
    {
      "key": "key_1",
      "value": "value"
    },
    {
      "key": "key_2",
      "value": "value"
    },
    {
      "key": "key_3",
      "value": "value"
    },
    {
      "key": "key_4",
      "value": "value"
    }
  ],
  "timestamp": "2025-06-06T16:02:48.7266448Z",
  "error_code": 0,
  "error_message": ""
}

---

Check Payment Status

Method: HTTP GET

URL: https://api.rumbapay.online/v1/transaction/{request_id}

Response (Success):

{
    "identifier": "P2C000000386",
    "request_id": "f290dd9a-def2-4f7c-81e0-11af7f20f37e",
    "reference": "f40b236f-5abb-439c-b756-c27a8c0f645e",
    "description": "My order h2h",
    "status": {
        "name": "created",
        "date": "2025-06-06T15:47:54.045"
    },
    "created_date": "2025-06-06T15:47:44.552",
    "amount": 1000,
    "billing_amount": 1000,
    "currency": "KES",
    "extra": [
        {
            "key": "key_1",
            "value": "value"
        },
        {
            "key": "key_2",
            "value": "value"
        },
        {
            "key": "key_3",
            "value": "value"
        },
        {
            "key": "key_4",
            "value": "value"
        }
    ],
    "timestamp": "2025-06-06T15:48:54.8840229Z",
    "error_code": 0,
    "error_message": ""
}

Response (Not Found):

Transaction not found

{
    "error_code": 101,
    "error_reason": "Transaction not found",
    "request_id": "16003088-037e-416c-9163-4e70e17d291b",
    "timestamp": "2025-04-11T16:58:57.11Z"
}