Concepts
Idempotency
Retry any create request safely. A repeated key returns the original response.
Networks fail. If a request times out, you can't tell whether the payment was created. An idempotency key lets you send it again without charging twice.
Send a key
Every request that creates or changes money requires an Idempotency-Key header of up to
255 characters:
POST /v1/paymentsPOST /v1/payments/{payment_id}/refundsPOST /v1/checkoutsPOST /v1/checkouts/{checkout_id}/capture
Use a value tied to the operation in your system, such as your order id, or a UUID you store.
How it works
| You send | You get |
|---|---|
| A new key | The request runs. |
| The same key and the same body | The original response, with the original status code, and the header Idempotent-Replayed: true. Nothing runs again. |
| The same key and a different body | 409. Use a new key. |
| The same key while the first request still runs | 409. Wait and retry. |
Keys are scoped to the project, the environment, and the endpoint, including the id in the path. The same key on a different endpoint is a different operation. Results are kept for at least 7 days.
Uncertain results
If the provider doesn't answer in time, Camel can't know whether the operation happened. It
returns 202 with the resource in status unknown, and finds out the real
result from the provider afterwards. You'll get a webhook when it settles.
Don't create a new payment for an unknown one; you could charge the customer twice. Retrying
with the same key is always safe: it returns the same response.