Lightning Invoice

POST /api/lightning/invoice

Generate a Lightning invoice. When the invoice is paid, a PIX payout is automatically sent to the specified PIX key or QR code.

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,
    "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,
    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,
        "pixKey": "user@email.com",
        "pixKeyType": "EMAIL",
    },
)
data = res.json()

Body examples

With PIX key

{
  "value": 1000,
  "pixKey": "user@email.com",
  "pixKeyType": "EMAIL"
}

With PIX QR Code

{
  "value": 1000,
  "qrCode": "00020126580014br.gov.bcb.pix..."
}

Parameters

Field	Type	Required	Description
`value`	number	Yes	Amount in BRL cents. Min `10` (R$ 0.10), max `25000` (R$ 250.00).
`pixKey`	string	No	PIX key for the payout. Mutually exclusive with `qrCode`.
`pixKeyType`	string	No	Type of the PIX key: `PHONE`, `CPF`, `EMAIL`, `RANDOM`, or `CNPJ`.
`qrCode`	string	No	PIX QR Code in copy-paste format. Mutually exclusive with `pixKey`.
`refundAddress`	string	No	Lightning address for refunds in case of failure.

You must provide either pixKey or qrCode, but not both.

Fees

A 2% fee is applied to the value.

fee = value * 0.02
total = value + fee

For example, a deposit of R$ 10.00 (value 1000) has a fee of R$ 0.20.

Response

200 OK

{
  "success": true,
  "invoice": "lnbc32310n1p5u2g2qsp5...",
  "valueInSatoshis": 276190,
  "pixKey": "13d3109f-3a1e-4c56-b76d-d2db7213b9f2",
  "qrCode": null,
  "valueInBrl": "1000.00",
  "fee": "170.00",
  "quote": {
    "brlAmount": "1000.00",
    "btcAmount": 0.0027619041618037344,
    "satoshis": 276190,
    "btcToBrlRate": 362069.04418686405
  }
}

Fields

Field	Type	Description
`success`	boolean	Whether the invoice was created.
`invoice`	string	Lightning invoice to be paid.
`valueInSatoshis`	number	Value converted to satoshis.
`pixKey`	string \| null	The PIX key used.
`qrCode`	string \| null	The PIX QR code used.
`valueInBrl`	string	Value in BRL.
`fee`	string	Fee in BRL.
`quote.brlAmount`	string	BRL amount quoted.
`quote.btcAmount`	number	Amount in BTC.
`quote.satoshis`	number	Amount in satoshis.
`quote.btcToBrlRate`	number	BTC to BRL exchange rate.

Errors

400 Bad Request

{
  "success": false,
  "error": "Provide either pixKey or qrCode, not both"
}

Lightning Invoice

On this page