How do idempotency keys work?
Send a unique idempotency key with a request so a retry can't create a duplicate. Reusing a key returns the original result instead of acting twice — essential for payouts.
An idempotency key is a unique value you attach to a request so that if you send it more than once — after a timeout or a network retry — Fynex acts on it only once. Reusing the same key returns the result of the original request instead of creating a duplicate. This matters most for payouts, where a duplicate would move money twice.
How to use it
- Generate a unique key per action (for example a UUID) and send it with the request.
- Reuse the same key when you retry the same action after an uncertain response (a timeout, a dropped connection). Fynex recognises it and returns the original outcome.
- Use a new key for a genuinely new action — a new key means a new payout.
What Fynex enforces
- Payouts require an idempotency key, scoped to your account. If you resend the same key, you’ll get back the existing payout rather than a second one — the error you’d see for a clashing reuse is “payout with this idempotency key already exists”.
- Checkout sessions are idempotent too — the same key won’t open a duplicate session.
Why it matters
When a request times out you often can’t tell whether it succeeded. Without an idempotency key, retrying risks a double payout; with one, retrying is safe — worst case you get the same result back. Always retry payout and checkout calls with the original key rather than a fresh one.