Skip to main content

​
Why

You send a request, but the network drops the response before it reaches you. Did it go through? With an idempotency key you can just retry: the same key returns the original result instead of doing the work a second time.

​
How it works

The operations that create money movement take an idempotencyKey — a UUID you generate — in the request body:
  • The first call with a key runs the operation.
  • The same key with the same body returns that original result — the operation runs once, however many times you retry.

​
What a replay actually returns

A retry only replays cleanly when the original succeeded. Every other case is an error, and one of them surprises people:
A failed original spends the key. Retrying a failed operation with the same key does not re-run it — it returns 422. To retry after a failure, generate a fresh key. This is the opposite of what “idempotent retry” usually implies, so it is worth handling explicitly.
Treat 409 as “wait and re-read” rather than an error to surface: the original is still running, and retrying the same key once it settles gives you the result. Keys are unique per company across all idempotent endpoints, not per endpoint — so a key used on a transfer cannot be reused on a pay-out.

​
Two rules

  1. Generate one new key per operation — each transfer, pay-in, pay-out, and virtual bank account gets its own.
  2. Reuse a key only to retry that exact call. For a genuinely new operation, generate a new key.
A key is required on exactly these five operations — and accepted nowhere else: Every other endpoint ignores the field. Reads are naturally safe to repeat, and the remaining writes are either idempotent by construction or keyed on a resource you already name in the path.
Save the key before you send the request. If your process restarts mid-flight, the retry reuses the same key and lands exactly once.

​
Next steps

API conventions

Pagination, versioning, and the shared idempotency rules.

Transfers

Fiat and crypto transfers — each with its own key.