Idempotent Requests

The Fordefi API supports idempotency to enable you to safely retry Create Transaction requests, while preventing inadvertent duplication of operations.

This feature is most useful when a response is not received or when the initial API call did not complete successfully. Clients can make repeated identical calls, yielding the same outcome, as if they were making a single request.

  • To perform an idempotent request, provide an additional X-Idempotence-Id: <ID> header to the Create Transaction request.
  • To retrieve an idempotence ID, issue a call to List Transactions. The ID is located under managed_transaction_data.

Fordefi's idempotency mechanism functions by storing the resulting status code and response body from the initial request made with a specific idempotency ID, regardless of whether the request was successful or not. Subsequent requests bearing the same ID will return identical results, complete with a 200 HTTP status code and the created transaction.

An idempotency ID is a unique value, generated programmatically by the client, which the server uses to recognize subsequent retries of the same request. While the method of generating unique IDs is at your discretion, they must be in UUID format. We recommend using V4 UUIDs. Fordefi checks that the IDs are valid. There is no defined maximum length for an ID.

Results are only retained if the /api/v1/transactions endpoint has commenced execution. If incoming parameters fail validation or if the request conflicts with another concurrent execution, no idempotent result is stored because no API endpoint has begun execution. In such cases, it is safe to retry these requests.