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.

Recommended key format

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-Manatee-Event-Id and ignore events that were already processed.