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 Mambu Payments 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: a8a66613-96ec-40b6-8557-77e88dce003a' \
     --header 'X-Api-Key: YOUR_API_KEY' \
     --data '{ /* payment order body */ }'

If such a 409 — Conflict error occurs, the Mambu Payments 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. Indempotency keys:

Have a maximum length of 255 characters
Typically contain your internal UUIDs, but any format is accepted as long as it is a string
Can be used when creating payment orders, expected payments, payment captures, and payee verification requests
Can be used within bulk actions
Are scoped to your organization. They only apply to your own API keys and API requests
Are not checked across objects. The same idempotency key can be used for a payment order and an expected payment
Are not supported for GETAPI requests that are idempotent by nature