Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nicosaporiti/buda-lightning-invoice/llms.txt

Use this file to discover all available pages before exploring further.

This is the second step of the LNURL-pay flow. After a Lightning wallet fetches /.well-known/lnurlp/:username and reads the payment parameters, it calls this callback endpoint with the amount the user wishes to pay, expressed in millisatoshis. The server converts that amount to satoshis, creates a Lightning invoice via the Buda.com API, and returns a BOLT11 payment request for the wallet to pay. 
GET /callback

​
Query parameters

​
amount
integer
required
Amount to invoice in millisatoshis. Must be an integer greater than or equal to 1000 (i.e., at least 1 satoshi). The server divides this value by 1000 to convert to satoshis before forwarding the request to Buda.com — so amount=10000 creates a 10-satoshi invoice.
​
comment
string
An optional, user-supplied payment comment up to 140 characters (per LUD-09). Used as the invoice memo. If omitted, defaults to "Pago desde Lightning Address".

​
Response (200 OK)

​
pr
string
The BOLT11 payment request string generated by Buda.com. This is the invoice the wallet should pay. Starts with lnbc on Bitcoin mainnet.
​
successAction
object
An action object displayed to the user by the wallet after a successful payment, as defined by the LNURL-pay spec.
​
routes
array
Always an empty array []. This is a standard LNURL-pay response field reserved for routing hints; no hints are needed here.

​
Error responses

Both error types return HTTP 400 Bad Request. Validation error — amount is missing, non-integer, or below 1000 msats: 
{
  "ok": false,
  "errors": {
    "amount": { "msg": "Ingrese un número entero mayor a 1000 msats" }
  }
}
Buda API error — the upstream Buda.com invoice creation failed: 
{
  "ok": false,
  "error": "Buda error ..."
}

​
Examples

Request 
curl "https://budaln.fly.dev/callback?amount=10000&comment=Thanks"
Success response 
{
  "pr": "lnbc100n1p3q9h8app5...",
  "successAction": {
    "tag": "message",
    "message": "Gracias por tu pago"
  },
  "routes": []
}
Validation error response (amount too low) 
{
  "ok": false,
  "errors": {
    "amount": { "msg": "Ingrese un número entero mayor a 1000 msats" }
  }
}

​
Amount conversion

The amount query parameter must be supplied in millisatoshis, following the LNURL-pay specification. The server internally computes: 
satoshis = amount / 1000
before calling Buda.com to create the invoice. For example:
amount (msats)Invoice value (sats)
10001 sat
1000010 sats
100000100 sats
100000000100,000 sats
The minimum accepted value is 1000 msats (1 satoshi), not 1 msat. Requests with amount below 1000 will fail validation and return a 400 error. This matches the minSendable value advertised by the /.well-known/lnurlp/:username endpoint.
This endpoint is normally called automatically by Lightning wallets as part of the LNURL-pay protocol — developers rarely need to call it manually. The typical flow is: wallet fetches /.well-known/lnurlp/:username → wallet calls /callback?amount={msats} → wallet receives and pays the BOLT11 invoice in pr.

Build docs developers (and LLMs) love

Get started for freeTalk to us