Skip to main content

Idempotency Keys

Use an Idempotency-Key header when creating payments. This lets your backend retry a request after a timeout or network interruption without accidentally creating multiple payment requests for the same order.

When to use one​

Send an idempotency key for every POST /v1/btc/payments request in production. Payment creation usually sits inside checkout, where retries are common and duplicate payment instructions would be confusing for customers.

Use a stable value tied to your own order:

order-10042-create-payment

Do not generate a new random value for each retry. The whole point is that the retry uses the same key as the original attempt.

Backend flow​

  1. Create or load your own order record.
  2. Build a stable idempotency key from that order ID.
  3. Call POST /v1/btc/payments with the Idempotency-Key header.
  4. Store the returned Manatee payment ID next to your order ID.
  5. On webhook delivery, use the payment ID to find the order.

Webhooks are also at-least-once​

Idempotency is not only for payment creation. Webhook delivery can be repeated, so your webhook handler should also be idempotent. Store X-Event-ID and ignore events that were already processed.