​
Configuring a Callback URL

You can configure a callback URL by including your specified URL as a parameter in the API request body. This setup allows you to receive real-time notifications for both payouts and pay-ins, ensuring seamless integration with your system.

​
Callback for Payins

​
Through USSD Push

For collections using USSD push, you can configure your callback url as specificed below.

1

Pass in the url you’d like to receive the callback response on under the params object as “callback_url”.

{
"params": {
  "amount": "Deposit_amount",
  "mobile": "Mobile_number",
  "country_id": "Country_id",
  "currency": "Currency",
  "payment_method_type": "Payment_method_type",
  "callback_url": "Your_callback-url",
  "third_party_reference_1": "Third_party_reference"
  }
}
2

Generate a signature for the specified parameters using the generate signature endpoint

3

Make the API request using the payload generated.

    { 
      "client_id": "AxxxxxxxxxxxxxxxxxxxxxxxxxxxxJ",
      "params": {
          "amount": 10,
          "callback_url": "https://your-domain.com/niobi/result",
          "country_id": 1,
          "currency": "KES",
          "mobile": "254711111111",
          "payment_method_type": "send money",
          "third_party_reference_1": "TRANS1"
      },
      "salt": "mySalt123",
      "sender": "Integration Name",
      "timestamp": 123,
      "signature": "0xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx5"
    }
4

Once the transaction is processed you will receive a callback response as shown below.

{
 "client_id": "AxxxxxxxxxxxxxxxxxxxxxxxxxxxxJ",
  "salt": "mySalt123",
  "sender": "Integration Name",
  "timestamp": 123,
  "signature": "0xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx5"
  "params": {
          "amount": 10,
          "depositId": "Axxxxxxxxxx1",
          "email": "hello@niobi.co",
          "mobile": "254711111111",
          "name": "Username",
          "status": "success",
          "status_code": "000000",
          "third_party_reference_1": "TRANS1",
          "third_party_reference_2": null
      }   
}

For payins collected via payment links, you can configure your callback url as part of the params field while creating a payment link. Once a payment will be made to your account using the payment link, you will receive a response on the callback.

{
  "params": {
    "amount": 10,
    "mobile": "254711111111",
    "country_id": 1,
    "currency": "KES",
    "payment_method_type": "send money",
    "callback_url": "https://domain.com/link",
    "third_party_reference_1": "DEP1"
  }}

​
Callback for Payouts

For disbursements, you can configure your callback url as specificed below.

1

Pass in the url you’d like to receive the callback response on under the params object as “callback_url”.

{
"params": {
"amount": 1000,
"customer_identifier": 1234,
"currency": "KES",
"payment_reference": "TRANS-123456789",
"first_name": "John",
"last_name": "Doe",
"mobile": "254123456789",
"email": "john@doe.com",
"country_id": "1",
"city": "Nairobi",
"postal_code": "001001",
"line1": "abc, xyz",
"description": "abc, xyz",
"client_callback_url": "https://your-domain.com/niobi/result",
"third_party_reference_1": "TRANS1",
"third_party_reference_2": "<string>",
"payment_method_type": "send money",
"sendmoney": [
  {
    "phone_number": "254123456789"
  }
]
}
}
2

Generate signature for the specified parameters using the generate signature endpoint

3

Make the api request using the payload generated.

{ "client_id": "AeiQYngNXwZK8vrvjdO6RyrI8hsDtUk4v3KWCBGJ",
      "params": {
           "amount": 1000,
  "customer_identifier": 1234,
  "currency": "KES",
  "payment_reference": "TRANS-123456789",
  "first_name": "John",
  "last_name": "Doe",
  "mobile": "254123456789",
  "email": "john@doe.com",
  "country_id": "1",
  "city": "Nairobi",
  "postal_code": "001001",
  "line1": "abc, xyz",
  "description": "abc, xyz",
  "client_callback_url": "https://your-domain.com/niobi/result",
  "third_party_reference_1": "TRANS1",
  "third_party_reference_2": "<string>",
  "payment_method_type": "send money",
  "sendmoney": [
    {
      "phone_number": "254123456789"
    }
  ]
      },
      "salt": "mySalt123",
      "sender": "Testerr",
      "timestamp": 1726586109,
      "signature": "06390dff8b362a06a72da9f7400c18e88d4164b4c9b90d8ec2db0a369b050375"}
4

Once the transaction is processed you will receive a callback response as shown below.

{
"client_id": "Your client id",
"params": {
   "account": "80000003",
  "account_number": "70000003",
  "amount": 1,
  "fee": 25,
  "invoice_no": "PAY-289044",
  "message": "Payment was transferred successfully.",
  "mobile": "+254740845185",
  "niobi_ref": "$2y$10$xNi2CeynNnYZILfQeuGYUORFzGdBM0/yYY1rcl9Bbad5469GgcMGi",
  "paybill_number": "810592",
  "payee": "JohnDoe 123",
  "payment_channel": "M-Pesa Paybill",
  "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 Paybill",
  "type": "Pay out"
},
"salt": "salt value",
"sender": "Integration name",
"timestamp": 123,
"signature": "7xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxb"
}

​
Response Structure

Below is a summary of the response structure of the callback responses expected.

​
Payins

{
  "client_id": "Your client id",
  "sender": "Integration title",
  "salt": "Random salt value",
  "timestamp": "Timestamp",
  "params": {
     "amount": "Amount deposited",
      "depositId": "Transaction id of the deposit",
      "email": "Your email address",
      "mobile": "Mobile that made the deposit",
      "message": "Message describing deposit success or failure",
      "name": "Account username",
      "status": "Status of the deposit",
      "status_code": "Status code of the transaction"
      "third_party_reference_1": "TRANS1",
      "third_party_reference_2": null,
  },
   "signature": "Request signature"
}

Please note that the “depositId” field represnets the transaction id of the deposit.

​
Payouts

{
  "client_id": "Your client id",
  "sender": "Integration title",
  "salt": "Random salt value",
  "timestamp": "Timestamp",
  "params": {
    "account": "The account number of the account the payment was made from",
    "amount": "Amount paid out",
    "fee": "Fees incurred for the payment",
    "invoice_no": "Invoice number of the payment made (System generated)",
    "message": "Message describing the transaction status",
    "mobile": "Mobile number of the recipient",
    "niobi_ref": "Transaction reference specfic to Niobi",
    "payee": "Full name of the recipient",
    "payment_channel": "Payment channel",
    "payment_reference": "Unique information passed by user to identify transaction",
    "payoutId": "Unique transaction id of the payment",
    "ref": "Transaction reference shared by provider",
    "statusCode": "Sstatus code of the transaction",
    "third_party_reference_1": "reference",
    "third_party_reference_2": "reference",
    "transaction_date": "Date payment was made",
    "transaction_detail": "Message with details of the transaction",
    "type": "Transaction type"
  },
   "signature": "Request signature"
}

Please note that the “depositId” field represents the transaction id of the deposit.

​
Resending Callbacks

You can resend callbacks in case of a delivery failure through the payment portal. To do this, access the specific transaction and click on “Resend Callback.”

To learn more about transaction status codes, refer to the Status Codes section
FAQs