Documentation
Lightning Addresses
Paying to lightning address

Paying to lightning address


How to pay another lightning address

The steps for paying a lightning address are very similar to how you pay an LNURL QR. When a user enters a lightning address on your service, two ways to pay to send payments to the lightning address;

  • Paying through a Callback
  • Paying directly through Bitnob

Pay using callback

Handshake

To pay a LnAdddress, a handshake protocol must be established by sending the LnAdddress to be decoded (opens in a new tab) and getting a callback. The callback is the URL of the service to call for the next steps of paying to the LnAddress.

Payload

JSON
 
{
  "lnAddress": "bernard@bitnob.com"
}

Response You will receive this data if the username exists on that service

JSON
 
{
    "status": true,
    "message": "lightning address decoded successfully",
    "data": {
        "image": "",
        "identifier": "bernard@bitnob.com",
        "description": "Send satoshis to bernard@bitnob.com",
        "callback": "https://bitnob.com/.well-known/lnurlp/bernard",
        "commentAllowed": 100,
        "satMinSendable": 1,
        "satMaxSendable": 100000
    }
}

Read on the Decoded LNURL/LNAddress Response (opens in a new tab) to see a breakdown of the response.

Next, a callback query is made to generate a lightning invoice for the receiver

Callback query

After getting the callback, a GET request is made using this format. This request is made to generate a lightning invoice to make payment on behalf of the receiver. The amount sent must be within the satMinSendable and satMaxSendablefrom the handshake response.


https://bitcoin.org/.well-known/lnurlp/satoshi?amount=<amount>&comment=<comment>

Pay directly through Bitnob

When you send the below payload to Pay Lightning Address, Bitnob will request an invoice for the specified amount from that service, run checks and complete the payment on your behalf. When the payment is completed, you will receive a btc.lightning.send.success webhook response with the payment details.

Payload

{
  "lnAddress": "bernard@bitnob.com",
  "satoshis": 10,
  "reference": "referencecode", //generated by your service to keep track of payment
  "comment": "add payment comment here",
  "customerEmail": "<customer_email>"
}

Bitnob uses the information sent here to request for, validate and pay an invoice to the service hosting the lightning address.

Response

📘 Recommended Approach

We recommend using the 2nd approach. With this approach, you don't need to contact the service yourself. Once you supply the encoded LNURL, amount, reference, comment, and customer email to us, we will handle the rest of it for you.

🚧 Charging your customers before paying a Lightning address

Because Bitnob handles the payment of invoices, you need to deduct the amount you send to us from the customer's account. One way to do this is to create a pending transaction with the reference you send to us, when we send a webhook response to you, you can update the transaction status based on the kind of response you receive.

There are different ways of doing this based on your architecture, the most important thing is to ensure you charge the user before asking us to pay the lightning address