Prerequisites

Create an account

Generate an API key

In the dashboard, go to Settings -> API Keys and create a test key.

Configure webhooks

Add a server endpoint and save the webhook secret for signature verification.

First invoice

Create invoices from your server with an idempotency key:

curl -X POST https://api.halfin.xyz/api/v1/invoices \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_test_0000000000000000000000000000000000000000000000000000000000000000" \
  -d '{
    "currency": "BTC",
    "amount": "0.001",
    "description": "Order #1234",
    "idempotency_key": "order-1234"
  }'

import { createHalfin, createInvoice } from '@halfin/sdk-merchant';

const client = createHalfin({
  apiKey: process.env.HALFIN_API_KEY!,
  baseUrl: 'https://api.halfin.xyz/api',
});

const { data } = await createInvoice({
  client,
  body: {
    currency: 'BTC',
    amount: '0.001',
    description: 'Order #1234',
    idempotency_key: 'order-1234',
  },
});

Use the invoice status, payment address details, and webhooks to decide when an order can be fulfilled.

Never fulfill an order from a browser redirect or client-side signal alone. Confirm payment server-side through a verified webhook or an invoice status check.

Next steps

Authentication - API key format and handling.
Invoices - invoice fields, statuses, and settlement timing.
Webhooks - events and signature verification.
API Reference - generated per-operation pages.

Get Started