payLightningInvoice

Pays a Lightning invoice via the SparkWallet.

Before calling, reject expired BOLT11 invoices. In SDK 0.12.1, a swap can lock funds before the payment request is rejected. A failed call does not guarantee that no transfer started or that funds are immediately spendable. See expiry and failed-send handling.

Method Signature

interface PayLightningInvoiceParams {
  invoice: string;
  maxFeeSats: number;
  preferSpark?: boolean;
  amountSatsToSend?: number;
  transferId?: UUID;
}

async payLightningInvoice(params: PayLightningInvoiceParams): Promise<LightningSendRequest | WalletTransfer>

Parameters

string

required

The BOLT11-encoded Lightning invoice to pay

number

required

Maximum fee in satoshis to pay for the invoice

boolean

When true, initiate a Spark transfer if a valid Spark address is found in the invoice (default: false)

number

Amount in satoshis to send for zero-amount invoices. Rejected if the invoice already specifies an amount.

UUID

Optional transfer UUID for retrying the same logical payment. Generate it with generateTransferId() from the SDK and persist it before the first attempt. Reuse the same ID and payment parameters when retrying; do not generate a new ID for each attempt. This is a UUID object, not an arbitrary string. Reconcile a failed attempt before retrying.

Returns

LightningSendRequest | WalletTransfer

required

The Lightning payment request details, or a WalletTransfer if preferSpark is true and a valid Spark address was found in the invoice

The payment preimage is not returned immediately. To retrieve the preimage after payment completes, call getLightningSendRequest(id) with the returned request ID.

When preferSpark: true and the invoice contains a valid Spark fallback address, the method returns a WalletTransfer instead of LightningSendRequest. If no valid Spark address is found, it falls back to Lightning.

Examples

import { generateTransferId } from "@buildonspark/spark-sdk";

// Pay a regular invoice via Lightning
const payment_response = await wallet.payLightningInvoice({
  invoice: "lnbc100n...", // Regular Lightning invoice with amount
  maxFeeSats: 5,
});
console.log("Payment Response:", payment_response);

// Pay a zero-amount invoice
const zeroAmountPayment = await wallet.payLightningInvoice({
  invoice: "lnbc...", // Zero-amount Lightning invoice
  maxFeeSats: 5,
  amountSatsToSend: 1000, // Specify amount for zero-amount invoice
});
console.log("Zero-amount Payment Response:", zeroAmountPayment);

// Prefer Spark transfer if invoice has Spark fallback address
const sparkPreferred = await wallet.payLightningInvoice({
  invoice: "lnbc100n...", // Invoice with Spark fallback
  maxFeeSats: 5,
  preferSpark: true, // Will use Spark transfer if available
});
// Returns WalletTransfer if Spark used, LightningSendRequest otherwise

// Allocate once per logical payment and persist before the first attempt.
const transferId = generateTransferId();
const idempotentPayment = await wallet.payLightningInvoice({
  invoice: "lnbc100n...",
  maxFeeSats: 5,
  transferId,
});
// Retain transferId for reconciliation and any retry of this same payment.

Introduction

Wallets

Wallet Viewer

Utilities

Issuance

payLightningInvoice

Method Signature

Parameters

Returns

Examples

​Method Signature

​Parameters

​Returns

​Examples

Method Signature

Parameters

Returns

Examples