API Idempotence

Idemptotence is the property of certain operations in mathematics and computer science whereby they can be applied multiple times without changing the result beyond the initial application.

When talking about API calls, idempotency means that if you attempt an operation twice or more, only the first attempt will be processed. Idempotence prevents the processing of duplicate requests by using unique keys.

If a network connection error or a timeout error appears when creating a card payment, you can do a retry. But still, in this case, there is the possibility that the card payment has already been created, leading you only to generate a duplicate payment when you do the retry.

In order to avoid this undesired scenario, we have implemented a new piece of functionality using Unique Keys, which make it safe to retry non-idempotent API requests. These Unique Keys or Idempotence keys ensure that no matter the number of retries for a specific call only one response action is executed, and the payment is not duplicated.

Our API supports idempotence for safely retrying requests and guarantees that the operation is performed only once. Therefore, if you create a card payment that fails due to a network connection error, you can retry the request with the same idempotence key to guarantee that only a single card payment is created.

Idempotence keys are unique value generated keys, for example, UUIDs, that you submit as a request header and guarantee that only one resource will be created regardless of how many times a request is sent to the server.

Idempotence keys can be generated using your own preferred method or any appropriately random string. Still, we recommend to generate your own Unique Keys (Idempotence keys) using V4 UUIDs.

For card payments we’ll always send back the same response for requests made with the same key, and keys can’t be reused with different request parameters. The keys are stored for a period of 24 hours.

You can also visit our Nuvei SDK .NET section for more information on how you can generate and plug in your Unique Key Generator.