Lightning Invoice
Generate a Lightning invoice that triggers a PIX payout when paid.
POST /api/lightning/invoice
Creates an invoice that pays a PIX key or BR Code when funded.
Request
curl --request POST \
--url https://api.hodle.com.br/api/lightning/invoice \
--header "Authorization: Bearer $API_KEY" \
--header "Content-Type: application/json" \
--data '{
"value": 1000,
"externalId": "order-1234",
"pixKey": "user@email.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: 1000,
externalId: 'order-1234',
pixKey: 'user@email.com',
pixKeyType: 'EMAIL',
}),
})
const data = 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": 1000,
"externalId": "order-1234",
"pixKey": "user@email.com",
"pixKeyType": "EMAIL",
},
)
data = res.json()Body examples
{
"value": 1000,
"qrCode": "00020126580014br.gov.bcb.pix..."
}Parameters
| Field | Type | Required | Description |
|---|---|---|---|
value | number | Yes | PIX amount in BRL cents. Min 500; maximum: your outbound limit. Dynamic QR codes override the amount. |
pixKey | string | No | Recipient PIX key. |
pixKeyType | string | No | PHONE, CPF, EMAIL, RANDOM or CNPJ. |
qrCode | string | No | PIX BR Code in copy-paste format. |
refundAddress | string | No | Lightning address for refunds in case of failure. |
subAccountId | string | No | Subaccount under your API key. Defaults to your main account. |
externalId | string | Per account | Idempotency key, 1–128 characters after trimming. Required when invoice idempotency is enabled on your account; otherwise ignored. Reuse on retries to receive the original invoice with alreadyProcessed: true. |
You must provide either pixKey or qrCode, but not both.
Limits
Invoices use your outbound PIX limits:
| Limit | Default |
|---|---|
| Minimum per invoice | R$ 5.00 |
| Maximum per invoice | R$ 3,000.00 |
| Monthly outbound total | R$ 120,000.00 |
Limits reset each calendar month; no daily or nighttime limit applies. Ask support to raise them.
Fees
The default fee is 2%, minimum R$ 1.00. Account pricing and affiliate discounts may change it. The invoice charges value + fee; the recipient receives value.
Response
{
"success": true,
"transactionId": "65f1a8b2c3d4e5f6a7b8c9d1",
"trackId": "3dbbb785-8a1d-41c4-9d15-171e0ddc7c3d",
"invoice": "lnbc1020n1p5u2g2qsp5...",
"expiresAt": "2026-09-26T13:18:29.000Z",
"valueInSatoshis": 28172,
"pixKey": "12345678000190",
"qrCode": null,
"valueInBrl": 102,
"fee": 2,
"quote": {
"brlAmount": 102,
"btcAmount": 0.00028172,
"satoshis": 28172,
"btcToBrlRate": 362069.04
}
}Fields
| Field | Type | Description |
|---|---|---|
success | boolean | Whether the invoice was created. |
transactionId | string | Id of the payout. The PAYOUT_* webhooks carry the same value. |
trackId | string | Tracking id of the payout, also echoed by the webhooks. |
invoice | string | BOLT11 invoice to be paid. Echoed as invoice in the webhooks. |
expiresAt | string | ISO 8601 instant after which the invoice can no longer be paid. |
valueInSatoshis | number | Invoice amount in satoshis. |
pixKey | string | null | The PIX key used. |
qrCode | string | null | The PIX QR code used. |
valueInBrl | number | Invoice amount in BRL (value + fee). |
fee | number | Fee in BRL. |
quote.brlAmount | number | BRL amount quoted. |
quote.btcAmount | number | Amount in BTC. |
quote.satoshis | number | Amount in satoshis. |
quote.btcToBrlRate | number | BTC to BRL exchange rate. |
Expiry
Pay before expiresAt. An expired invoice fires no webhook; create a new one with a new externalId when idempotency is enabled.
Webhooks
Listen for PAYOUT_SUCCESSFUL when the PIX settles, PAYOUT_FAILED on failure and PAYOUT_REFUNDED on reversal. There is no separate invoice-paid event.
Match the event to the invoice by data.transactionId (or data.invoice, the same BOLT11 returned here). See the Lightning-funded payload.
Errors
| Status | When |
|---|---|
400 | Invalid fields or destination, value below the minimum, missing externalId when required, or invoice/quote creation failed. |
401 | Missing or invalid API key. |
403 | Outbound account limit exceeded (PER_TX_LIMIT_EXCEEDED or MONTHLY_LIMIT_EXCEEDED). Do not retry without changing the amount or account limit. |
404 | Subaccount not found within your account. |
409 | externalId already used for a different value or destination. |
{
"success": false,
"error": "Valor excede o limite por transação de saída de R$ 3000.00",
"errorCode": "PER_TX_LIMIT_EXCEEDED",
"limit": {
"direction": "OUT",
"monthlyLimitBrlCents": 12000000,
"monthlyUsedBrlCents": 0,
"monthlyAvailableBrlCents": 12000000,
"perTxLimitBrlCents": 300000,
"resetsAt": "2026-10-01T03:00:00.000Z"
}
}