Idempotency and references

How to retry safely and how references identify payments.

Networks fail. A request can time out after the server already acted on it. Idempotency lets you retry without paying twice.

Idempotency-Key

Send an Idempotency-Key header on every POST. It is required. A POST without one is rejected with 400 invalid_input.

You send	You get
A new key	The request runs.
The same key and the same body	The original response, replayed.
The same key and a different body	`409 idempotency_key_reused`. Nothing runs.

Use a value that is unique per payment attempt you intend, such as your order ID. Generate it once and store it, so a retry sends the same one.

If a request times out, retry with the same key and the same body. You will not create a second payment.

Every collection and payout has a reference. You choose it.

A reference is unique per business, forever. You cannot reuse one, even after the payment has failed. Sending it again under a new key with the same body returns the original payment. With a different body you get 409 duplicate_reference and nothing runs.
Use it to read the payment back: GET /v1/collections/{reference} or GET /v1/payouts/{reference}.
Pick something you can trace to your own records, such as an order or invoice number.

To try again after a failed payment, create a new payment with a new reference.