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.
ParameterTypeRequiredDescription
AmountNumberYesThe amount to be paid from your account. This is in absolute form (e.g. 100 KES to be passed as 100).
CurrencyStringYesThe currency in which the payment will be made.
Payment ReferenceStringYesInformation you will use to refer to the transaction later.
First NameStringYesThe first name of the recipient.
Last NameStringYesThe last name of the recipient.
MobileStringYesThe phone number of the recipient.
EmailStringYesThe email of the recipient.
Country IDStringYesThe ID of the country the payment will be made to. The full list can be found here.
CityStringYesThe city of the recipient.
Postal CodeStringYesThe postal code of the recipient.
Line1StringYesThe address line of the recipient.
DescriptionStringNoA description or message from the payer who is making the payment.
Client Callback URLStringYesThe callback URL for payment confirmation response.
Third Party ReferenceStringNoInformation you’d like to use to refer to the deposit later.
Payment Method TypeStringYesThe payment channel that will be used for the payment.
Payment Method ObjectObjectYesAn object containing the phone number of the recipient, associated with the selected payment method type.
You will then generate a signature using the parameters above and proceed to make an api request using the payload. 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.

​
Sample Flow

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

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": "192.0.0.1",
            "third_party_reference_1": ""
        },
        "salt": "mySalt123",
        "sender": "Integration name",
        "timestamp": "Timestamp value",
        "signature":"XxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxX"
    }
2

Handling Transaction Status

Once the transaction has been processed, you have two options for managing the transaction status:
  1. 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

    "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",
"payoutId": "bd8f51a2-xxxx-xxxx-xxxx-xxxxx9a",
"ref": "SII6ZH9PU0",
"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"
}
  2. Constantly Querying Transaction Status. Alternatively, you can query the transaction status endpoint periodically (recommended for 2 minutes) to check for updates on the transaction status.