Invoices

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.

Invoices can also expose settlement target snapshot fields: target_settlement_asset, settlement_target_currency, and settlement_target_network. These describe how the merchant account expects the paid invoice to be credited. A converted invoice can be paid while settlement is still in progress, so the merchant balance is not available until the settlement credit completes. When conversion is disabled, the invoice uses passthrough settlement and each payment is credited in the paid currency and network.

Usage

Create an invoice from your server, then display the returned payment address and amount in your own UI.

curl -X POST https://api.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' },
});

# Python SDK coming soon. Use the cURL example for now.

Pitfalls

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.