Idempotency

title: "Idempotency" description: "Send an Idempotency-Key on every mutating request. Replays within 24 hours return the original response." section: "API reference" order: 2 updated: "2026-04-18" sourcePath: "content/docs/api/idempotency.mdx"

Network failures happen. To make retries safe, send an Idempotency-Key header on every POST and PATCH. BchainPay stores the response for 24 hours and returns it byte-for-byte on any replay with the same key.

curl -X POST https://api.bchainpay.com/v1/payment-intents \
  -H "Authorization: Bearer $BCHAINPAY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "amount_cents": 4999, "currency": "USD", "settlement_currency": "USDC", "network": "polygon" }'

Rules

• The key is a UTF-8 string, 1–255 chars. UUIDs work well.
• Scope is per API key, per endpoint. The same key on a different endpoint is a fresh request.
• Reuse with the same body → original response is returned, no side effect.
• Reuse with a different body → 409 idempotency_conflict. Pick a new key.
• Keys expire after 24 hours.

Generating keys

Generate the key before sending the request and persist it alongside your local order ID. On retry, send the same key — that is what makes the retry safe.

What is not retried

GET requests are naturally idempotent and ignore the header. DELETE is also idempotent on our side: deleting an already-deleted resource returns 404, not 409.