Idempotency for Payments

The Payment API endpoints require an idempotency key be sent in the header of your requests. These allow you to retry requests is you lose connection, while safely avoiding duplicate transactions.

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 rather than processing a subsequent transaction.

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.

Recommended Functions for Creating Idempotency Keys

You can submit any alphanumeric value for your idempotency key, but they need to be 25 characters long and must be unique. The generation and tracking of idempotency keys used for transactions will remain the merchants responsibility.

We recommend the following UUID functions for generating keys, however please note that because UUID generates a 36 character string, you will need to slice the string generated before passing this in your request.