On this page
One key for the same intent
Send Idempotency-Key when creating a transaction. The contract makes the header optional, but using it is recommended to tolerate a lost connection after the server receives your request. Generate and persist the key before the first POST; reuse it only for the same creation and payload.
Idempotency-Key: onboarding-demo-0001A lost response does not mean a lost creation
Suppose your server sends a request and receives a timeout. The transaction may already exist. Retrying with a new key can create a second journey. Repeating the same POST with the same key and payload can recover the idempotent creation; its documented response remains 201.
Use external_id for business correlation, without treating it as an automatic replacement for the header. Preserve the relationship between key, attempt and transaction in your system.
Handle conflicts explicitly
Using the same key with a different payload returns 409 with code idempotency_conflict. Do not bypass this result by silently changing the key. Determine whether the customer changed the data or your application reconstructed the request inconsistently.
A genuinely new intent gets a new key. A technical retry preserves the previous intent. Do not assume an undocumented key-retention window.
Creation idempotency does not replace webhook deduplication. Use event_id for events and make business side effects idempotent as well.