Idempotency
Send an Idempotency-Key header on any POST you might retry, on /v1/* and on /api/partner/*:
POST /v1/payment_setups
Idempotency-Key: 6f1a2c9e-merchant-1042-way3| Case | Answer |
|---|---|
| Same key, same body | Runs again safely and answers with Idempotent-Replayed: true. SET's creates are idempotent by content, so the same objects come back. |
| Same key, different body | 422 idempotency_key_reused |
| Same key while the first request is still running | 409 |
Keys are kept 24 hours. SET never stores an answer that can carry bank details; it re-runs the request instead. In staging, sandbox POSTs replay the stored answer.
Even without the header, creates are content-idempotent: the same customer externalId, the same bank account, or the same setup sent twice answers with the existing object. Each provider write carries an idempotency key derived from its content, so a retry never creates a second account at the provider.
Events are announced once: *.created fires only when an object is new.