Idempotency

For all POST endpoints, include an idempotency key in the request header (X-Idempotency-Key). This ensures that repeated requests are treated as a single operation, preventing accidental duplicate transactions.

curl --request POST \
--url 'https://api.flutterwave.cloud/developersandbox/charges' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--header 'X-Idempotency-Key: {{YOUR_UNIQUE_INDEMPOTENCY_KEY}}' \
--data '{}
'

When a subsequent request is made with the same idempotency key, we return the original response associated with the first request that used that key. This ensures that no duplicate objects are created on our end.

For such requests, the response will include the header X-Idempotency-Cache-Hit: true to indicate that the result was retrieved from an already existing idempotency key.

Best Practices for Managing Request Idempotency

1. Always ensure that your transaction, transfer, customer creation, and refund requests are idempotent by including an idempotency key when creating these resources.
2. We recommend using a UUID string as your idempotency key for each request to ensure uniqueness.
3. Implement webhooks to track any responses you might have missed due to network interruptions or timeouts.