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

Every write takes an idempotencyKey — a unique ID you generate, like a UUID — 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.

​
Two rules

  1. Generate one new key per operation — each transfer, payment, settlement, reversal, adjustment, and pay-in 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 transfers, payment requests (create, settle, reverse, and update), pay-in sessions, and virtual bank accounts.
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.

Payment requests

Reserve, settle, reverse — each with its own key.