Make Payments

This section explains how to execute payouts using Niobi’s Payment API, covering various payment channels and the payout process. To start making payments using these methods, ensure that your Niobi account is set up and verified. Refer to the ‘Setting up a Niobi Account’ section in the Getting Started section for detailed steps on account creation and setup.

Using the API

The unified-payments api endpoint is used for making payments across the supported countries. Please find the full API reference here. You will be required to pass in the following parameters.

Parameter	Type	Required	Description
Amount	Integer	Yes	The amount to be paid from your account. This is in absolute form (e.g. 100 KES to be passed as 100).
Currency	String	Yes	The currency in which the payment will be made.
Payment Reference	String	Yes	Information you will use to refer to the transaction later.
First Name	String	Yes	The first name of the recipient.
Last Name	String	Yes	The last name of the recipient.
Mobile	String	Yes	The phone number of the recipient.
Email	String	Yes	The email of the recipient.
Country ID	String	Yes	The ID of the country the payment will be made to. The full list can be found here.
City	String	Yes	The city of the recipient.
Postal Code	String	Yes	The postal code of the recipient.
Address Line 1	String	Yes	The address line of the recipient.
Description	String	No	A description or message from the payer who is making the payment.
Client Callback URL	String	Yes	The callback URL for payment confirmation response.
Third Party Reference	String	No	Information you’d like to use to refer to the deposit later.
Payment Method Type	String	Yes	The payment channel that will be used for the payment.
Payment Method Object	Object	Yes	An object containing the phone number of the recipient, associated with the selected payment method type.
Sender First Name	String	Conditional	First name of the sender. Required for XAF (Cameroon) payouts.
Sender Last Name	String	Conditional	Last name of the sender. Required for XAF (Cameroon) payouts.
Sender Phone Number	String	Conditional	Phone number of the sender in international format. Required for XAF (Cameroon) payouts.

You will then generate a signature using the parameters above and proceed to make an api request using the payload. Refer to Signature Generation for signing requests. On successful payment, you will receive a callback response with the transaction details. Please find a detailed description of the callback response under Callback URL Section.

Please note that all live transactions made through our API are subject to a transaction fee.

High-Level Integration

This section provides a high-level overview of how to integrate with the Disbursements API.

Initiating the Unified Disbursements API Request

To begin, generate a signature for your api request using the generate signature api endpoint and initiate a payout transaction by making an API request.

Sample API Request

{
        "client_id": "client_id",
        "params": {
            "amount": 500,
            "city": "CustomerCity",
            "client_callback_url": "https://webhook.site/url",
            "country_id": "2",
            "currency": "XOF",
            "email": "john.doe@example.com",
            "first_name": "John",
            "last_name": "Doe",
            "line1": "CustomerStreet",
            "mobile": "22991600649",
            "mtn": [
                {
                    "phone_number": "22991600649"
                }
            ],
            "payment_method_type": "mtn",
            "payment_reference": "",
            "postal_code": "12345",
            "third_party_reference_1": ""
        },
        "salt": "mySalt123",
        "sender": "Integration name",
        "timestamp": "Timestamp value",
        "signature":"XxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxX"
    }

Sample API Request for Cameroon (XAF Payouts)

For XAF Payouts, the sender’s details are required as part of local regulatory requirements.

{
        "client_id": "client_id",
        "params": {
            "amount": 1000,
            "city": "Yaounde",
            "client_callback_url": "https://webhook.site/url",
            "country_id": "4",
            "currency": "XAF",
            "email": "jane.doe@example.com",
            "first_name": "Jane",
            "last_name": "Doe",
            "line1": "CustomerStreet",
            "mobile": "237612345678",
            "sender_firstname":"Harvey",
            "sender_lastname":"Mike",
            "sender_phone_number":"2371xxxx6789",
            "orange": [
                {
                    "phone_number": "2376xxxxx678"
                }
            ],
            "payment_method_type": "orange",
            "payment_reference": "XAF_PAYOUT_001",
            "postal_code": "12345",
            "third_party_reference_1": ""
        },
        "salt": "mySalt456",
        "sender": "Integration name",
        "timestamp": "Timestamp value",
        "signature":"YyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyY"
    }

Sample Initial API Response (Successfully Initiated)

{
    "success": true,
    "message": "Payment process initiated successfully.",
    "data": {
        "reference": "S000001234",
        "type": "MPESA Send Money",
        "total": 500,
        "creation_date": "2026-08-12T09:53:40.000000Z",
        "execution_date": "2026-08-12T09:53:44.000000Z",
        "from": "John Doe",
        "to": "254712345678",
        "invoice_date": "2026-08-12",
        "invoice_amount": 500,
        "payment_step": 1
    },
    "status_code": "000000"
}

Sample Initial API Response (Failed to Initiate)

{
    "success": false,
    "message": "Payment process initiation failed. Please check the details and try again.",
    "status_code": "000005"
}

payment_step: 1 is only included when the request is successfully initiated with the processor (status_code: 000000). If initiation fails (status_code: 000005), the response has no payment_step field at all. Either way, this is an acknowledgement of the request, not the final result.

The message field in the data object describes the result of initiating the payout. Its exact wording may vary depending on the payment processor or channel, for example:

“Payment process initiated successfully.”

Refer to payment_step and status_code (above) to determine the correct handling, not this message text.

Handling Transaction Status

Once the transaction has been processed, you have two options for managing the transaction status:

Receiving a Callback. A callback response containing the transaction details will be sent to your configured URL. You can set up an endpoint on your front end to handle this callback and update the user interface accordingly, such as displaying success or failure messages based on the transaction outcome. See more about callback responses here

Sample Callback Response (Success)

{
"client_id": "Your client id",
"params": {
"account": "80xxxxx3",
"account_number": "",
"amount": 10,
"currency" : "KES",
"fee": 5,
"message": "Payment was transferred successfully.",
"mobile": "254123456789",
"paybill_number": "",
"payee": "JohnDoe 123",
"payment_channel": "Send Money",
"payment_reference": "OID51",
"payment_step": 2,
"payoutId": "bd8f51a2-xxxx-xxxx-xxxx-xxxxx9a",
"ref": "SII6ZH9PU0",
"status": "success",
"statusCode": "000000",
"third_party_reference_1": "TRANS1",
"third_party_reference_2": null,
"transaction_date": "2024-09-18 00:00:00",
"transaction_detail": "Disbursement made through M-Pesa Send Money",
"type": "Pay out"
},
"salt": "salt value",
"sender": "Integration name",
"timestamp": 123,
"signature": "7xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxb"
}

Sample Callback Response (Failed)

{
"client_id": "Your client id",
"params": {
"account": "80xxxxx3",
"account_number": "",
"amount": 10,
"currency" : "KES",
"fee": 5,
"message": "Payment was not transferred.",
"mobile": "254123456789",
"paybill_number": "",
"payee": "JohnDoe 123",
"payment_channel": "Send Money",
"payment_reference": "OID51",
"payment_step": 2,
"payoutId": "bd8f51a2-xxxx-xxxx-xxxx-xxxxx9a",
"ref": "SII6ZH9PU0",
"status": "failed",
"statusCode": "000005",
"third_party_reference_1": "TRANS1",
"third_party_reference_2": null,
"transaction_date": "2024-09-18 00:00:00",
"transaction_detail": "Disbursement made through M-Pesa Send Money",
"type": "Pay out"
},
"salt": "salt value",
"sender": "Integration name",
"timestamp": 123,
"signature": "7xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxb"
}

When "payment_step": 2 is present in the params of the callback body, it means this callback is final for the transaction: act on it. It’s sent for both a successful ("status_code": "000000") and a failed ("status_code": "000005") transaction status, not the request’s own success. Mark the transaction with whatever status and statusCode is in the params object: that’s the final outcome.

Periodically Querying Transaction Status. Alternatively, you can query the transaction status endpoint periodically (recommended for 2 minutes) to check for updates on the transaction status.

Conditional SMS Notifications for External Beneficiaries (KES Payouts)

For payout transactions in Kenyan Shillings (KES), you can request conditional SMS notifications to be sent to external beneficiaries. This feature allows you to opt-in for SMS alerts to recipients outside your organization. To enable this feature, contact our support team via email at support@niobi.co to request activation.

Get Started with Niobi

Collecting Payments

Making Payments

Sub-merchant Management

API Authentication

Transaction Status

Coverage

Going Live

Troubleshooting

Webhooks

Make Payments

Using the API

High-Level Integration

Sample API Request

Sample API Request for Cameroon (XAF Payouts)

Sample Initial API Response (Successfully Initiated)

Sample Initial API Response (Failed to Initiate)

Sample Callback Response (Success)

Sample Callback Response (Failed)

Conditional SMS Notifications for External Beneficiaries (KES Payouts)

​Using the API

​High-Level Integration

​Sample API Request

​Sample API Request for Cameroon (XAF Payouts)

​Sample Initial API Response (Successfully Initiated)

​Sample Initial API Response (Failed to Initiate)

​Sample Callback Response (Success)

​Sample Callback Response (Failed)

​Conditional SMS Notifications for External Beneficiaries (KES Payouts)

Using the API

High-Level Integration

Sample API Request

Sample API Request for Cameroon (XAF Payouts)

Sample Initial API Response (Successfully Initiated)

Sample Initial API Response (Failed to Initiate)

Sample Callback Response (Success)

Sample Callback Response (Failed)

Conditional SMS Notifications for External Beneficiaries (KES Payouts)