Idempotent Requests

Our APIs protect your application against cases where you might end up sending unintended repeat requests. This could be caused by a communication breakdown (mainly network issues) or your application having broken logic.

For example, imagine a scenario where you initiate a POST request to top up PhoneNumber1 with KES 100 worth of credits. However, due to network issues, you do not receive a valid response from our APIs, even though the airtime was delivered to PhoneNumber1. In this case, you might actually want to retry the POST request but also ensure that we do not send the airtime again.

However, you might run into cases where you actually want to send the same request more than once. In that case, you can set a special header Idempotence-Key to a unique value of your choosing and resend the request. If you send another request with the same Idempotence-Key within a given period of time, we will respond with a failure status notifying you that we have detected a duplicate request.

You can add idempotence keys to your requests to ensure that we send a request from your application once. This feature is currently supported for Airtime Topup and Payment Disbursement APIs.

Along with the standard request headers, you can add an Idempotence-Key

Parameter Description
Idempotence-Key
String
Optional
A unique value of your choosing that identifies a request sent to our APIs e.g req-1234