emergepay Idempotency Keys Idempotency Keys · Gravity Payments Documentation

Cross Integration Idempotency Support

emergepay now offers support for idempotency keys across all of its public APIs. The key is added as an “idempotency-key” http header to requests made directly to API endpoints, and alternatively as a configuration value in emergepay’s SDKs.

Duplicate Protection

emergepay now offers support for traditional idempotency keys as a means for offering duplicate transaction protection.

Idempotency keys allow integrators to ensure that the same request, whether sent once or multiple times, will only be processed once through emergepay, and will always return the same response.

Idempotency keys are supported on all of emergepay’s public APIs.

Idempotent Request Handling

emergepay manages idempotency by creating a transaction session the first time a request is received on a specific endpoint with a unique idempotency key.

This session has a TTL of 24 hours, and any requests with the same idempotency key made to the same API endpoint over the duration of that session will be checked against the original request. The emergepay service will validate that the request payload is identical to the original payload with the same idempotency key, and emergepay will prevent the transaction from being reprocessed.

We recommend generating a version 4 UUID to ensure uniqueness when creating your idempotency keys.

One of the following response scenarios will follow any secondary requests that include a previously submitted idempotency key.

An http 409 response indicating that the submitted payload is not an exact match with the original payload. In this case the request fails to meet the distinctness requirement of idempotency, and so it is discarded.
An http 409 response indicating that the original transaction with the same idempotency key is still in progress. In this case the secondary request will be discarded.
The final response of the original transaction if the transaction has been completed.

Idempotency Key Generation

We recommend generating v4 UUIDs for idempotency key headers to guarantee uniqueness. Code samples in our documentation provide examples.

External Transaction Identifiers

External Transaction Ids are still required to be submitted with every transaction request and their purpose does not change in the emergepay environment.

External Transaction Ids are intended to function as unique transaction identifiers. From an idempotency perspective, External Transaction Ids are considered part of the request payload, and are used to validate that any secondary requests for a given idempotency key contain a payload identical to the original request with that key. But External Transaction Ids are not used as keys to track an idempotent request.

So External Transaction Ids should be consistent across an idempotent request. If a different External Transaction Id is submitted on a secondary request with the same idempotency key, we would return a 409 error because the request payload deviates from the original request for that key.