Step by Step

  1. Decode the invoice using a library in your favourite language or calling /invoice/decode

JavaScript: https://github.com/bitcoinjs/bolt11
Golang: https://github.com/nbd-wtf/ln-decodepay

If amount == 0 :
Ask to the user the amount he wishes to send.

  1. (Optional) Estimate fees with the amount if needed: /estimate-fee. And show it to the user.

  2. Call invoice/pay.

    3.1. If the response is a 200, check the payment status in the response body payment status.

    3.2 If invoice/pay returns an error, get the payment informations: /payment/from-bolt11

  3. If the payment is IN_FLIGHT, wait for the webhook to inform you if the payment was SUCCEEDED or FAILED

Payment Status

0UNKNOWNUnknown state
1IN_FLIGHTPayment is still in flight.
2SUCCEEDEDPayment completed successfully.
3FAILEDPayment failed to settle

Payment Failure Reason


Payment failed

If the payment fails, you can use them to get more details, if you encounter one of those (except 0), you can contact [email protected]

0FAILURE_REASON_NONEPayment isnt failed (yet).
1FAILURE_REASON_TIMEOUTThere are more routes to try, but the payment timeout was exceeded.
2FAILURE_REASON_NO_ROUTEAll possible routes were tried and failed permanently. Or were no routes to the destination at all.
3FAILURE_REASON_ERRORA non-recoverable error has occured.
4FAILURE_REASON_INCORRECT_PAYMENT_DETAILSPayment details incorrect (unknown hash, invalid amt or invalid final cltv delta)