Get started

Idempotency

Network failures are the rule, not the exception. To make a POST safe to retry, supply an Idempotency-Key header. Baynoy caches the response for 24 hours; subsequent retries with the same key return the cached body without re-running the side effects.

Enforced on every Bearer-authenticated POST: /v1/customers, /v1/refunds, /v1/invoices, /v1/invoices/{id}/send, /v1/payment-links, /v1/products, /v1/prices. Body fingerprint mismatch on a reused key returns 409 idempotency_key_in_use.

Header format

curl https://baynoy.com/api/v1/refunds \
  -H "Authorization: Bearer sk_live_…" \
  -H "Idempotency-Key: refund-7f9b3d2c-a14e-4c01" \
  -d '{"paymentId":"...","amount":2000}'

Keys must be 8–255 characters from the set [A-Za-z0-9._\-:/]. UUIDs are ideal. Reuse the same key on every retry of the SAME logical operation.

Cache semantics

Same key + same body → cached response is returned with theIdempotent-Replayed: true header so you can tell a replay apart from a fresh response.
Same key + different body → 409idempotency_key_in_use. Almost always a programmer error (key reused across two distinct operations). Pick a fresh key.
No key → request runs through normally; retries are NOT safe.

Body fingerprint

The cache fingerprint is a SHA256 of the raw request bytes. JSON re-serialization (key ordering, whitespace) WILL produce a different hash. If your HTTP client re-encodes the body, retries with the same key may flip to 409 — pin the body to a stable string before sending and reuse that exact string on retry.

Which endpoints honor it

Every POST endpoint accepts Idempotency-Key. Most useful on:

POST /v1/refunds — never accidentally double-refund.
POST /v1/customers — survives flaky links during onboarding.
POST /v1/invoices — invoice numbers are unique; the key prevents two rows with the same merchant-side reference.