Skip to main content
The Fintoc API supports idempotent requests. You can retry an idempotent request without performing the same operation twice. Use idempotency for resource creation requests that you might retry after a network error. Examples include charges, payment intents, and transfers. If a connection error occurs after you submit an idempotent request, you can retry the request without creating a second object. To make an idempotent request, include the Idempotency-Key: <idempotency-key-value> header. An idempotency key is a unique value that your client generates. Fintoc uses this key to recognize retries of the same request. Use UUID version 4 values or random strings with enough entropy to avoid collisions. Idempotency keys can contain up to 255 characters. Fintoc saves the status code and response body from the first request for each idempotency key, whether the request succeeds or fails. Subsequent requests with the same key return the saved result, including 4xx and 5xx errors. Replayed responses include the Idempotent-Replayed: true header.
Authentication neededFintoc does not save an idempotent result when authentication fails because the request does not reach the API endpoint.
For each retry, the idempotency layer compares the request parameters with the original request parameters. If the parameters differ, Fintoc returns a 400 Bad Request error with the code invalid_idempotent_request. If you send a request while an earlier request with the same key is still in progress, Fintoc does not process it a second time. Fintoc waits up to about 1 second for the first result and returns it. If the first request has not finished by then, Fintoc returns a 503 Service Unavailable error with the code idempotency_unavailable. Fintoc does not save this 503 response. Retry later with the same key to get the result of the first request.

​
Retry a transfer safely

A 5xx response or a timeout can still mean Fintoc created the transfer. Because Fintoc replays a saved 5xx response, retrying with the same key returns the same error and does not tell you whether the transfer exists. To avoid sending a payment twice:
  1. Store your own identifier for each payment in the transfer’s metadata, and send one Idempotency-Key per payment.
  2. If the request times out or the connection drops before you get a response, retry with the same key. You get either the saved result or the result of a new attempt.
  3. If you get a 5xx response, list transfers with account_id, direction=outbound, and since set to just before your request. Look for a transfer with your metadata identifier.
  4. If you find the transfer, track it through its status and webhooks. If you don’t, create the transfer with a new Idempotency-Key.
Fintoc can remove idempotency keys automatically once they are at least 24 hours old. If you reuse a key after Fintoc removes the original result, the API processes the request as new. All POST requests accept idempotency keys. Sending idempotency keys in GET and DELETE requests has no effect because GET and DELETE requests are idempotent by definition. The following examples create a charge with an idempotency key. You can retry the request without creating a duplicate charge.