Create an account

Generate a sandbox API key

In the dashboard, go to Settings → API Keys and create a test key. It starts with sk_test_.

Configure a webhook endpoint (optional)

Add an HTTPS server endpoint and save the webhook secret — you need it for signature verification.

Create your first invoice

Nominate the amount in USD with amount_fiat + fiat_currency — halfin locks the equivalent crypto amount at creation time. This example requests $50.00, paid in USDT on Tron.

curl -X POST https://api-sandbox.thehalfin.com/v1/invoices \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_test_0000000000000000000000000000000000000000000000000000000000000000" \
  -d '{
    "amount_fiat": "50.00",
    "fiat_currency": "USD",
    "currency": "USDT",
    "network": "tron",
    "idempotency_key": "order-0001"
  }'

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

const client = createHalfin({
  apiKey: process.env.HALFIN_API_KEY!,
  baseUrl: 'https://api-sandbox.thehalfin.com',
});

const { data } = await createInvoice({
  client,
  body: {
    amount_fiat: '50.00',
    fiat_currency: 'USD',
    currency: 'USDT',
    network: 'tron',
    idempotency_key: 'order-0001',
  },
});

// Send the customer to checkout_url for payment
console.log(data.checkout_url);

The response includes a checkout_url — send your customer there to complete payment. The invoice starts in pending status.

Confirm payment server-side

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

When payment confirms, halfin delivers an invoice.paid webhook to your endpoint. Verify the signature, then check data.status == "paid" before fulfilling the order.

Next steps

Authentication — key format, environments, and security.
Invoices overview — statuses, deferred invoices, TTL, and underpayment handling.
Webhooks — all 13 events and delivery semantics.
Signature verification — verify webhook authenticity.

Quickstart