Pay Lightning Invoice

Overview

Payment receivers generate a Lightning invoice. You can pay a valid invoice by providing the invoice string and optional parameters such as fee limits and additional metadata. Payments route over the Lightning Network and typically settle (or fail) immediately.

📘

Note

Currently, BitGo limits individual Lightning transactions to a value of $500 USD or less.

Custody Lightning - Pay Invoice

The following endpoints are specific to Custody Lightning wallets.

Endpoint: Lightning - Pay a Lightning Invoice

export BITGO_EXPRESS_HOST="<YOUR_LOCALHOST>"
export COIN="tlnbtc"
export WALLET_ID="<YOUR_WALLET_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export ADDRESS="<DESTINATION_ADDRESS>"
export AMOUNT="<AMOUNT_IN_BASE_UNITS>"
export WALLET_PASSPHRASE="<YOUR_WALLET_PASSPHRASE>"

curl -X POST \
  https://$BITGO_EXPRESS_HOST/api/v2/$COIN/wallet/$WALLET_ID/lightning/payment \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "invoice": string,                       # Encoded payment request (required)
    "passphrase": "'"$WALLET_PASSPHRASE"'",  # Wallet passphrase (required)
    "amountMsat": string,     # Amount to pay in millisatoshis (optional, required for zero-amount invoices)
    "feeLimitMsat": string,   # Maximum fee to pay in millisatoshis
    "feeLimitRatio": number,  # Maximum fee expressed as a ratio of the payment amount
    "sequenceId": string,     # Custom identifier for tracking the payment
    "comment": string         # Additional note or comment for internal reference
}'
  const { BitGo } = require('bitgo');
  const { getLightningWallet } = require('@bitgo/abstract-lightning');
  const accessToken = '<YOUR_ACCESS_TOKEN>';

  // Initialize the SDK
  const bitgo = new BitGo({
    accessToken: accessToken,
    env: 'test',
    customRootURI: 'https://app.bitgo-test.com',
  });

  // Enter your Lightning wallet
  const walletId = '<YOUR_WALLET_ID>'
  const existingWallet = await bitgo.coin('tlnbtc').wallets().get({ id: walletId });
  const lightningWallet = getLightningWallet(existingWallet);

  const payInvoice = await lightningWallet.payInvoice({
    invoice: 'lnbtc...',
    passphrase: 'your wallet passphrase',
  });
  console.dir(payInvoice);

Step Result

{
    "txRequestId": string,        // Unique identifier for the transaction request
    "txRequestState": delivered,  // State of the transaction request
    "paymentStatus": {
      "status": pending,          // Payment status
      "paymentHash": string,      // Unique identifier of the payment
      "paymentPreimage": string,  // Payment preimage (proof of payment)
      "amountMsat": string,       // Final amount paid in millisatoshis
      "feeMsat": string,          // Network fees paid in millisatoshis
      "failureReason": string     // Reason for failure if payment failed
    },
    "transfer": {
      "id": string,
      "coin": string,
      "wallet": string,
      "walletType": string,
      "enterprise": string,
      "organization": string,
      "txid": string,
      "state": string,            // initialized, unconfirmed, confirmed
      "type": string,             // send, receive
      "value": number             // millisatoshis
      "valueString": string,      // millisatoshis
      "coinSpecific": {
        "isOffchain": boolean,
        "invoice": string
      },
    }
}

See Also

Blockchain Reference: Bitcoin Lightning Network