Idempotency Keys

The Helcim Payment API endpoints require idempotency keys, which allow you to retry requests while safely avoiding duplicate transactions. These unique 25 character alphanumeric keys are sent in the header of the POST request to Payment API endpoints.

What is an idempotency key?

An idempotency key is sent in the header of a Payment API request, to ensure that a transaction is only processed once. This helps to avoid duplicate transactions should you need to resubmit a request if your connection fails before receiving a response from the Helcim system.

Sending this key allows you to confidently re-submit any transaction requests through the Helcim Payment API and it will return the response of the initial transaction request if the previous request was successfully received, rather than processing a subsequent transaction.

The generation and tracking of idempotency keys used for transactions will remain the merchants responsibility.

How idempotency works in the Payment API

Idempotency keys submitted to the Payment API are cleared after 5 minutes, ensuring you have the opportunity to attempt transactions a second time. A submitted idempotency key will be associated with the specific transaction that it was originally sent with until they are cleared and cannot be reused until then.

The Helcim API will first check to see if the passed idempotency key exists in our system.

• If the idempotency key does not exist in our system, the Payment API will process the transaction request.
• If the idempotency key does exist and the payload sent in the request is identical to the previous payload received for that key, then Payment API will return the response from the first successful request.
• If the idempotency key does exist and the payload sent in the request is different from the previous payload received for that key, then the Payment API will return a 409 status code and an error object due to the same key being used.
• If the idempotency key does not exist in our system, but the payload of the request is identical to a previous payload received in the last 5 minutes, the Suspected Duplicate check will be triggered.

Headers

Determines if the response is idempotent or not.

Idempotent-Request: true

🚧

When processing a Capture, Refund or Reverse, you should use a unique idempotency key for the request and not the idempotency key associated with the original Purchase or Preauth transaction.

Recommended functions for creating idempotency keys.

You can submit any alphanumeric value for your idempotency key, so long as they are 25 characters long and unique.

Alternatively, you can use the following UUID functions for generating idempotency keys, however please note that because UUID functions generate a 36 character string, you will need to slice the string down to 25 characters before passing this in your request.

When testing requests in our API Reference section, the UUID check will fail it's validation, however the Helcim API will still accept the idempotency-key so long as it meets the requirements.