Docs
Search the docs
Find a page in the docs

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/payments
  • POST /v1/payments/{payment_id}/refunds
  • POST /v1/checkouts
  • POST /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.

curl -X POST https://api.camelpayment.com/v1/payments/pay_01JBX7Q2M4N8K5R6T9V3W1Y0ZA/refunds \
  -H "Authorization: Bearer $CAMEL_API_KEY" \
  -H "Idempotency-Key: refund-1524-1" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500000
  }'

How it works

You sendYou get
A new keyThe 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 body409. 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.