Idempotent requests

The UnivaPay API allows you to make idempotent requests. Idempotency provides an extra degree of safety, and helps assuring that a request will not be processed twice by some unexpected reason.

Idempotency is enabled only for POST and PATCH requests with valid authentication credentials, and is activated by passing an idempotency key through the Idempotency-Key header. Although its value can be any string, merchants are encouraged to use some randomly generated value, preferably a UUID.

It is always a good idea to use idempotency whenever possible, especially when creating or updating transaction tokens, charges, subscriptions and refunds.

Note that as this idempotent is provided on a best-effort basis, there is a possibility that it fails to check idempotency. In this case, API returns Idempotency-Status header with error and the request will be processed.

How idempotency works

Whenever an idempotency key is passed in a request, the UnivaPay API will first verify whether a previous request was made passing that same key.

In case of finding a match, the API returns the stored response for that request, instead of processing the request again.

If a matching entry is not found, then the request is processed as normal, and its response is stored along with the idempotency key, so that it can be used for future idempotent requests.

An idempotency key is valid for a period of 24 hours. This means that passing the same key for the second time after that period will result in the API processing the request as if it was the first time.

API responses from methods that allow idempotency include an Idempotency-Status header, which can take one of the following values:

  • disabled: for requests that don’t admit idempotency
  • successfully_stored: the current response has been stored in association with the passed idempotency key. This happens the first time the key is used. The next time the same key is passed, this stored response will be returned.
  • retrieved_idempotent_response: the header takes this value when a stored response associated with a passed idempotency key is returned. It indicates that the request was not processed again.
  • error: when the API encountered some problem while retrieving or storing some response on an idempotent request.
  • conflicting_key: when the passed idempotency key has been previously used for a different route or method.