Ansa’s APIs support idempotency, allowing you to safely retry requests without the risk of performing the same action multiple times—such as accidentally charging a customer twice.

This is particularly useful when requests fail due to network issues or transient errors. By retrying a failed request with the same idempotency key, you can ensure that the requested operation has completed successfully without resulting in duplicate transactions.

To use idempotency, include the Ansa-Idempotency-Key header in your API requests. While all endpoints accept this header, it only applies to state-changing operations — typically POST requests that initiate financial transactions. It has no effect on GET requests or other read-only endpoints.

Example cURL request including an idempotency key header:

curl  https://api-sandbox.getansa.com/v1/{merchant_id}/customers/{customer-id}/add-balance
-H "Authorization: ansa_sk_sandbox_c06f7fee-..."
-H "Ansa-Idempotency-Key: 5529d106-a3cb-4452-8698-886995adb420"
-d amount=1000
-d currency=usd
-d payment_method_id="b000731e-0b43-43ac-be02-22a87947742a"

Client SDKs

When using an Ansa provided client SDK, you do not need to manage idempotency keys yourself. The payment session manages the idempotency key as part of the session for you.

If you do want to manage idempotency on your own, it is possible to override the idempotency key used in the request by providing it as a parameter in most calls.