Idempotency Keys

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

The key is added as an idempotencyKey HTTP header to requests made directly to API endpoints, and alternatively as a configuration value in emergepay’s SDKs.

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.

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

The session has a TTL of 24 hours. Requests with the same idempotency key made to the same API endpoint over the duration of that session are 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 reprocessing.

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.