Idempotency

Network failures happen. The Idempotency-Key header makes retries safe: BchainPay stores the response for 24 hours and returns it on any replay with the same key.

The header is required on all POST, PUT, and PATCH requests. Omitting it returns a 400 missing_idempotency_key error.

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" }'

Rules

Scenario	Behavior
Same key + same body	Original response is replayed. No side effects.
Same key + different body	`409 conflict` — "Resource already exists with different parameters."
Key on a different endpoint	Treated as a new request. Keys are scoped per merchant and per endpoint.
Key after 24 hours	Expired. The same key may be reused for a new request.

The key is any UTF-8 string. UUIDs are recommended.
Scope is per merchant (API key) and per endpoint.
Keys have a 24-hour TTL (configurable on the server side).

Generating keys

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

What is not covered

GET requests are naturally idempotent and do not require the header.