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

With PIX QR Code
{
  "value": 1000,
  "qrCode": "00020126580014br.gov.bcb.pix..."
}

Parameters

FieldTypeRequiredDescription
valuenumberYesPIX amount in BRL cents. Min 500; maximum: your outbound limit. Dynamic QR codes override the amount.
pixKeystringNoRecipient PIX key.
pixKeyTypestringNoPHONE, CPF, EMAIL, RANDOM or CNPJ.
qrCodestringNoPIX BR Code in copy-paste format.
refundAddressstringNoLightning address for refunds in case of failure.
subAccountIdstringNoSubaccount under your API key. Defaults to your main account.
externalIdstringPer accountIdempotency 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:

LimitDefault
Minimum per invoiceR$ 5.00
Maximum per invoiceR$ 3,000.00
Monthly outbound totalR$ 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

200 OK
{
  "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

FieldTypeDescription
successbooleanWhether the invoice was created.
transactionIdstringId of the payout. The PAYOUT_* webhooks carry the same value.
trackIdstringTracking id of the payout, also echoed by the webhooks.
invoicestringBOLT11 invoice to be paid. Echoed as invoice in the webhooks.
expiresAtstringISO 8601 instant after which the invoice can no longer be paid.
valueInSatoshisnumberInvoice amount in satoshis.
pixKeystring | nullThe PIX key used.
qrCodestring | nullThe PIX QR code used.
valueInBrlnumberInvoice amount in BRL (value + fee).
feenumberFee in BRL.
quote.brlAmountnumberBRL amount quoted.
quote.btcAmountnumberAmount in BTC.
quote.satoshisnumberAmount in satoshis.
quote.btcToBrlRatenumberBTC 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

StatusWhen
400Invalid fields or destination, value below the minimum, missing externalId when required, or invoice/quote creation failed.
401Missing or invalid API key.
403Outbound account limit exceeded (PER_TX_LIMIT_EXCEEDED or MONTHLY_LIMIT_EXCEEDED). Do not retry without changing the amount or account limit.
404Subaccount not found within your account.
409externalId already used for a different value or destination.
403 Forbidden
{
  "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"
  }
}