Idempotency
How not to charge twice
Networks are unreliable: a response can get lost even though the money has already been charged. That is why
POST /v1/cards and POST /v1/charges require an Idempotency-Key header of 8 to 128 characters [A-Za-z0-9._:-].
| Retry with the same key | Result |
|---|---|
| same body, first request finished | the stored response, header Idempotent-Replayed: true |
| same body, first request still running | 409, code -11003: retry later |
| different body | 422, code -11002 |
Errors are not remembered: you can send a corrected request with the same key.
The second safeguard is externalId: even with a new key, a second charge for the same order is not created.
Recommendation: build the key from your own operation ID, for example order-777-charge.