Idempotency

Idempotency guarantees that a given API request is only processed once and the corresponding action is only executed once. This ensures that failures and retries do not result in duplicates. Any subsequent API request received with a previously used idempotency key will return a 409 - Conflict with error= idempotency_key_conflict.

The Numeral API supports idempotency through the optional addition of a unique ID in the Idempotency-Key HTTP header of your API requests:

curl --request POST \
     --url https://sandbox.numeral.io/v1/payment_orders \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'Idempotency-Key: YOUR_IDEMPOTENCY_KEY' \
     --header 'X-Api-Key: YOUR_API_KEY' \
     --data '{ /* payment order body */ }'

If such a 409 — Conflict error occurs, the Numeral API will return the following body:

{
	"error": "idempotency_key_conflict",
	"message": "An object sharing the same idempotency_key already exists.",
	"idempotency_key": "a8a66613-96ec-40b6-8557-77e88dce003a", /* your idempotency key */
	"existing_record": {
		"id": "7dda60e1-e72b-4532-85b0-cfa0f8cbfc9d",
		"object": "payment_order",
		/* rest of the object */
	}
}

Below is important information about idempotency keys:

• Idempotency keys typically contain your internal UUIDs, but any format is accepted as long as it is a string
• Idempotency keys can be used when creating payment orders, expected payments, and payment captures
• Idempotency keys are scoped to your organization. They only apply to your own API keys and API requests
• Idempotency checks are not applied across objects. The same idempotency key can be used for a payment order and an expected payment
• GETAPI requests are idempotent by nature and do not require nor support idempotency keys