Idempotency
A retry should retrieve the previous operation rather than duplicate a charge.
One key per business action
Send Idempotency-Key containing 16–128 alphanumeric, hyphen, underscore, period, or colon characters. Reuse the key to retry the same request. Generate a new key only for a new action.
Session creation stores a unique workspace/key combination in PostgreSQL and a canonical request digest. Concurrent requests converge on the same session.
| Retry | Result |
|---|---|
| Same key and same body | Same session and URL |
| Same key, different body | 409 IDEMPOTENCY_CONFLICT |
| Key in another workspace | Independent namespace |
Optional fields are normalized by the schema before hashing. Prefilled email/document are part of the request too.
Payments
A unique constraint allows one payment per checkout. Retrying with the same key and body returns that payment. A different key or body returns CHECKOUT_USED.
Events
Every event has a deduplication key. Delivery can repeat after a timeout or dropped connection, even with a valid signature. Consumers should make event.id unique in their database.