Skip to main content
Every request that moves money takes an idempotency_key. This applies to collections, payouts, batches, settlements and transfers.
  • The key is 8 to 100 characters and must be unique within your business.
  • Same key, same body: you get the original payment back, and nothing new happens. A replayed payout answers 200 with replayed: true instead of 202.
  • Same key, different body: you get 409 idempotency_key_reused, and nothing new happens.

Choose a key from your own records

Base the key on something that already identifies the payment in your system, such as an order, an invoice or a payroll line. Don’t generate a fresh random key on each attempt: a retry would then look like a new payment.
If you deliberately want to pay again for the same order, for example after a failed attempt, use a new key such as order-1042-attempt-2.

When to retry

Batch items each have their own idempotency_key, up to 60 characters. Each must be unique within the batch.