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 settledStep 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.
{
"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
| Status | When |
|---|---|
403 | Value exceeds your limits. Read errorCode and limit; see Lightning Invoice. |
PAYOUT_FAILED | PIX could not be sent. Mark the order failed and contact support. |
PAYOUT_REFUNDED | Settled PIX was reversed. Mark the order refunded. |
Webhook signatures
Every delivery is signed. See Webhooks for the verification snippet.