The Helcim Payment API endpoints can accept idempotency keys, which allow you to retry requests while safely avoiding duplicate transactions. These keys are sent in the header of the POST request.
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.
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.
determines if the response is idempotent or not
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.
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.
Updated 29 days ago