Riverty Logo


Please select your page


How to Manage Messages Lost in Transmission

Idempotency is the ability of an API to respond to a repeated identical call with an identical response, every time.

Practical use

IdemPotency will increase system resiliency. If a message is lost in transmission for any reason, the API call can be repeated until a satisfactory response arrives. So, it will help if a merchant or PSP stopped waiting for a response but Riverty still processed the order or ordermanagement operation. Instead of getting an error back from the retry, because it was already processed, it will return accepted and therefor the order will automatically be processed correctly in the system of the merchant or PSP. This will avoid manual work on both sides.

How does it work

You can send an IdemPotency key in the header of the transaction. If the transaction got a time-out you should use all the same transaction data for the retry. So also the same IdemPotency key. The Riverty API will know the IdemPotency key and show the response that was initially send back but never was received on the merchant or PSP side. Keep in mind that the IdemPotency key needs to be unique per transaction per merchant. Only keep it the same for retries.

Without idempotency, the Riverty API will treat every incoming call as a distinct transaction. For example, if a non-idempotent Authorize call is received multiple times, then the Riverty API will return a business error, because that Order Number has already been used by that merchant.

Idempotency is enabled for all clients on the Riverty API. However, it only works if the merchant or PSP includes an Idempotency Key in the API call. Without it, the call is treated as non-idempotent.


  • The Idempotency Key is a unique string, passed in the header of the API call (similarly to the API Key).Can include letters, numbers, hyphens and underscores. It cannot include other special characters.
  • Up to 50 characters long.
  • You cannot reuse idempotency keys between different endpoints or call types (e.g. Authorize, Capture, Refund) for the same merchant.
Riverty 2023