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

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"
}