Lightning ↔ PIX

End-to-end flow — issue a Lightning invoice; once paid, settle BRL via PIX in seconds.

What this flow does

A payer pays a BOLT11 Lightning invoice. Hodle settles BRL via PIX to the recipient chosen when you create the invoice.

Sequence

1. POST /api/lightning/invoice    → invoice (bolt11) + transactionId + expiresAt
2. (off-chain) payer pays the invoice before expiresAt
3. Hodle receives the sats and sends the PIX
4. Webhook PAYOUT_SUCCESSFUL       → PIX settled

Step 1 — Issue the invoice

curl -X POST https://api.hodle.com.br/api/lightning/invoice \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "value": 10000,
    "pixKey": "recipient@example.com",
    "pixKeyType": "EMAIL"
  }'
const res = await fetch('https://api.hodle.com.br/api/lightning/invoice', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.HODLE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    value: 10000,
    pixKey: 'recipient@example.com',
    pixKeyType: 'EMAIL',
  }),
})
const { transactionId, invoice, expiresAt } = await res.json()
import os, requests

res = requests.post(
    "https://api.hodle.com.br/api/lightning/invoice",
    headers={
        "Authorization": f"Bearer {os.environ['HODLE_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "value": 10000,
        "pixKey": "recipient@example.com",
        "pixKeyType": "EMAIL",
    },
)
data = res.json()

value is what the recipient receives, in BRL cents (min R$ 5.00, max R$ 3,000.00 by default). The invoice is priced at value + fee, quoted in satoshis at the moment of creation.

200 OK
{
  "success": true,
  "transactionId": "65f1a8b2c3d4e5f6a7b8c9d1",
  "trackId": "3dbbb785-8a1d-41c4-9d15-171e0ddc7c3d",
  "invoice": "lnbc1020n1p5u2g2qsp5...",
  "expiresAt": "2026-09-26T13:18:29.000Z",
  "valueInSatoshis": 28172,
  "pixKey": "recipient@example.com",
  "qrCode": null,
  "valueInBrl": 102,
  "fee": 2,
  "quote": {
    "brlAmount": 102,
    "btcAmount": 0.00028172,
    "satoshis": 28172,
    "btcToBrlRate": 362069.04
  }
}

Store transactionId against your order and display invoice as a QR code or copyable string. Full reference: Lightning Invoice.

Step 2 — Payer pays the invoice

The invoice is payable until expiresAt. If it expires unpaid, no webhook fires; issue a new one.

Step 3 — Settlement (transparent)

Once paid, Hodle sends the PIX to the key or QR code from step 1.

Step 4 — Listen for PAYOUT_SUCCESSFUL

Configure PAYOUT_SUCCESSFUL in API Keys → Webhooks. It confirms PIX settlement; there is no separate invoice-paid event.

{
  "event": "PAYOUT_SUCCESSFUL",
  "data": {
    "success": true,
    "transactionId": "65f1a8b2c3d4e5f6a7b8c9d1",
    "trackId": "3dbbb785-8a1d-41c4-9d15-171e0ddc7c3d",
    "status": "COMPLETED",
    "asset": "LIGHTNING",
    "network": "lightning",
    "valueInBrl": "100.00",
    "fee": "2.00",
    "pixKey": "recipient@example.com",
    "endToEndId": "E12345678202609261314abcdef123456",
    "invoice": "lnbc1020n1p5u2g2qsp5...",
    "txHash": "lnbc1020n1p5u2g2qsp5...",
    "valueInSatoshis": 28172
  }
}

Match data.transactionId to your order and mark it settled. You can also match data.invoice to the BOLT11. Full payload: Webhooks.

Errors

StatusWhen
403Value exceeds your limits. Read errorCode and limit; see Lightning Invoice.
PAYOUT_FAILEDPIX could not be sent. Mark the order failed and contact support.
PAYOUT_REFUNDEDSettled PIX was reversed. Mark the order refunded.

Webhook signatures

Every delivery is signed. See Webhooks for the verification snippet.