Skip to main content
Start free

Idempotency

Retry any POST safely, so a lost answer never creates a second payment.

Networks drop answers. If your request to create a payment timed out, you cannot tell whether the payment exists. Send an Idempotency-Key header with every POST, and a retry with the same key gets the first answer back instead of doing the work twice.

How it works

  • The key is any string of 1 to 255 characters. A value derived from your data (order-1042, refund-1042-1) works across your own restarts; a random UUID works within one process.
  • Bezanbecard stores the first answer to a key for 24 hours, together with a fingerprint of the method, the path and the body.
  • The same key with the same request replays the stored answer, status code included, with the header Idempotent-Replayed: true.
  • The same key with a different body is refused with 400 idempotency_key_reused (type idempotency_error): a key names one operation.
  • A retry that arrives while the first request is still running is refused with 409 idempotency_key_in_use. Wait a moment and retry.
  • A receipt sent as multipart/form-data (POST /v1/payments/:id/receipts) is fingerprinted by its fields and the SHA-256 of each file, not by the raw body. A retry with a new multipart boundary replays the first answer, and other files under the same key are idempotency_key_reused.
  • A request refused by validation (a missing or invalid parameter) is not stored, so you can fix it and send it again with the same key. Every other answer, an error from the server included, is stored and replayed.

Keys are scoped to the API key's account and mode.

curl https://a.bezanbecard.com/v1/payments \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{"amount":12500000,"reference":"1042"}'

The official libraries

All three libraries send an Idempotency-Key with every POST, and retry network failures, 409 conflicts, 429 and 5xx answers twice by default with the same key and a growing wait. You only pass a key yourself when the retry may come from a different process, such as a queue job.

What it does not cover

  • GET and DELETE requests need no key: reading twice changes nothing, and deleting twice answers the same.
  • POST /v1/connect/exchange has no key store: its one-time code is the protection. A plugin that loses the answer connects again.
  • Idempotency stops your retries from duplicating work. It does not stop two different keys from creating two payments for one order. Reuse the open payment of an order, or derive the key from the order, as the store plugins do.