Idempotency
Retry safely without creating duplicate invoices, payouts, or refunds.
Idempotency lets you safely retry a create request after a network failure without creating a duplicate resource. Submitting the same key a second time returns the original resource rather than creating a new one. Submitting the same key with a different body returns an error with code idempotency_key_mismatch (HTTP 422 for Create Invoice, 409 for Create Refund).
Two mechanisms — use the right one per operation
Create Invoice and Create Payout accept an optional idempotency_key body field. Create Refund requires a mandatory Idempotency-Key request header. These are different by design — use the correct mechanism for each operation.
| Operation | Mechanism | Required? |
|---|---|---|
| Create Invoice | idempotency_key body field | Optional |
| Create Payout | idempotency_key body field | Optional |
| Create Refund | Idempotency-Key header | Required |
Create Invoice / Create Payout (body field)
curl -X POST https://api-sandbox.thehalfin.com/v1/invoices \
-H "Content-Type: application/json" \
-H "X-API-Key: $HALFIN_API_KEY" \
-d '{"currency":"BTC","amount":"0.01000000","idempotency_key":"order-0001"}'import { createHalfin, createInvoice } from '@halfin/sdk-merchant';
const client = createHalfin({ apiKey: process.env.HALFIN_API_KEY! });
await createInvoice({
client,
body: { currency: 'BTC', amount: '0.01000000', idempotency_key: 'order-0001' },
});Create Refund (header)
curl -X POST https://api-sandbox.thehalfin.com/v1/refunds \
-H "Content-Type: application/json" \
-H "X-API-Key: $HALFIN_API_KEY" \
-H "Idempotency-Key: refund-order-0001" \
-d '{
"invoice_id": "00000000-0000-0000-0000-000000000001",
"currency": "BTC",
"amount": "0.01000000",
"destination": "bc1qexampleaddress000000000000000"
}'Best practices
- Use a stable identifier from your order, job, or payout as the idempotency key.
- Keep the same key across all retries of the same operation.
- Do not reuse one key across unrelated operations.
Troubleshooting
idempotency_key_mismatch (HTTP 422 for Create Invoice, 409 for Create Refund) — the key was already used with a different request body. Either reuse the original body exactly, or start a new operation with a fresh key.