---
title: Idempotency and references
description: 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.

## References

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.