Callback URLS

Our payments API uses callbacks to notify you of final statuses of payments.

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": "[e-mail]",
             "failureReason": {
                 "failureCode": "Failure Code from MNO in case of failure",
                 "failureMessage": "Descriptive message on the failure reason in case of failure"
             },
             "fees": 0.3,
             "message": "Transaction summary message",
             "mobile": "254711111111",
             "name": "Username",
             "payment_link_id": null,
             "payment_link_payment_id": null,
             "reference" :  " Transaction id",
             "status": "success",
             "statusCode": "000000",
             "third_party_reference_1": "TRANS1",
             "third_party_reference_2": null
   
             
         }   
   }
   

Through Payment Links

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,
    "depositId": "Axxxxxxxxxx1",
    "email": "[e-mail]",
    "failureReason": {
      "failureCode": "Failure Code from MNO in case of failure",
      "failureMessage": "Descriptive message on the failure reason in case of failure"
    },
    "fees": 0.3,
    "message": "Transaction summary message",
    "mobile": "254711111111",
    "name": "Username",
    "payment_link_id": null,
    "payment_link_payment_id": null,
    "reference" :  " Transaction id",
    "status": "success",
    "statusCode": "000000",
    "third_party_reference_1": "TRANS1",
    "third_party_reference_2": null
  }}

Callback for Payouts

For disbursements, you can configure your callback url as specified 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": "[e-mail]",
   "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": "AxxxxxxxxxxxxxxxxxxxxxxxxxxxxJ",
         "params": {
              "amount": 1000,
     "customer_identifier": 1234,
     "currency": "KES",
     "payment_reference": "TRANS-123456789",
     "first_name": "John",
     "last_name": "Doe",
     "mobile": "254123456789",
     "email": "[e-mail]",
     "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": "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"
   }
   

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",
     "currency":"Transaction currency",
      "depositId": "Transaction id of the deposit",
      "email": "Your email address",
      "failureReason": {
        "failureCode": "Failure Code from MNO in case of failure",
        "failureMessage": "Descriptive message on the failure reason in case of failure"
      },
      "mobile": "Mobile that made the deposit",
      "message": "Message describing deposit success or failure",
      "name": "Account username",
      "payment_link_id": null,
      "payment_link_payment_id": null,
      "reference" :  " Transaction id",
      "status": "Status of the deposit",
      "statusCode": "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",
    "account_number" : "Account number for paybill payment method",
    "amount": "Amount paid out",
    "currency":"Currency of the payment",
    "fee": "Fees incurred for the payment",
    "message": "Message describing the transaction status",
    "mobile": "Mobile number of the recipient",
    "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": "Status code of the transaction",
    "third_party_reference_1": "External reference",
    "third_party_reference_2": "External 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.

Timeout Callbacks

For deposit transactions, a callback response is typically sent if a 2-minute timeout occurs on our end. Once the transaction is successful, a successful callback will be sent, and the transaction status will be updated accordingly.

{
  "client_id": "Your client id",
  "sender": "Integration title",
  "salt": "Random salt value",
  "timestamp": "Timestamp",
  "params": {
     
      "depositId": "Transaction id of the deposit",
      "name": "Account username",
      "email": "Your email address",
      "amount": "Amount deposited",
      "mobile": "Mobile that made the deposit",
      "third_party_reference_1": "1st Third party reference",
      "third_party_reference_2": "2nd Third party reference",
      "status": "timeout",
      "statusCode": "000006",
      "message": "Transaction failed due to timeout."
  },
   "signature": "Request signature"
}     

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