Concepts
Invoices
One-time payment requests
Reference
An invoice is a one-time payment request. It defines what the customer should pay and returns status, amount fields, and payment address details.
| Field | Purpose |
|---|---|
amount | Crypto-denominated amount |
amount_fiat + fiat_currency | Fiat-denominated amount |
idempotency_key | Duplicate protection for retries |
Usage
Create an invoice from your server. Send the payer to the returned checkout_url payment link, then confirm the result from your backend with a verified webhook or a server-side invoice status check.
curl -X POST https://dashboard.halfin.xyz/api/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 });
const { data } = await createInvoice({
client,
body: { currency: 'BTC', amount: '0.01000000', idempotency_key: 'order-0001' },
});Pitfalls
- Use idempotency keys when retrying invoice creation.
- Do not fulfill an order from a redirect alone. Confirm with webhooks or a server-side status check.
- Static address deposits create invoices after funds arrive; they are not checkout sessions.
Troubleshooting
Invoice remains pending means no sufficient on-chain payment has been confirmed yet.
Idempotency mismatch means the same key was retried with a different request body.