Idempotency

What is Idempotency?

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

Why is Idempotency Important?

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 order management operation. Instead of getting an error back from the retry, because it was already processed, the call 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.

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.

How does Idempotency Work?

You can send an Idempotency key in the header of the transaction. If the transaction receives a time-out you should use all the same transaction data for the retry, including the idempotency key. The Riverty API will know the Idempotency key and show the response that was initially sent back, but never was received on the merchant's or PSP's side. Keep in mind that the Idempotency key needs to be unique per transaction per 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.

Idempoteny Key Characteristics

  • A unique string, passed in the header of the API call (similarly to the API Key), which Can include letters, numbers, hyphens and underscores, but not other special characters
  • Up to 50 characters long
  • Cannot be used between different endpoints or call types (e.g. Authorize, Capture, Refund) for the same merchant