Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Sending payments

Once the SDK is initialized, you can directly begin sending payments. The send process takes two steps:

  1. Preparing the Payment
  2. Sending the Payment

For sending payments via LNURL, see LNURL-Pay.

Preparing Payments API docs

During the prepare step, the SDK ensures that the inputs are valid with respect to the payment request type, and also returns the fees related to the payment so they can be confirmed.

The payment request field supports Lightning invoices, Bitcoin addresses, Spark addresses and Spark invoices.

Developer note

Payments can be sent without holding Bitcoin by converting on-the-fly as a step before sending a payment. See Converting tokens for more information.

Lightning

BOLT11 invoice

For BOLT11 invoices the amount can be optionally set. The amount set in the request is only taken into account if it's an amountless invoice.

If the invoice also contains a Spark address, the payment can be sent directly via a Spark transfer instead. When this is the case, the prepare response includes the Spark transfer fee. Note that only one fee is paid: either the Lightning fee or the Spark transfer fee, depending on which payment method is ultimately used. See Lightning for how to select the payment method.

Rust
let payment_request = "<bolt11 invoice>".to_string();
// Optionally set the amount you wish to pay the receiver
let optional_amount_sats = Some(5_000);

let prepare_response = sdk
    .prepare_send_payment(PrepareSendPaymentRequest {
        payment_request,
        amount: optional_amount_sats,
        token_identifier: None,
        conversion_options: None,
        fee_policy: None,
    })
    .await?;

// If the fees are acceptable, continue to create the Send Payment
if let SendPaymentMethod::Bolt11Invoice {
    spark_transfer_fee_sats,
    lightning_fee_sats,
    ..
} = prepare_response.payment_method
{
    // Fees to pay via Lightning
    info!("Lightning Fees: {lightning_fee_sats} sats");
    // Or fees to pay (if available) via a Spark transfer
    info!("Spark Transfer Fees: {spark_transfer_fee_sats:?} sats");
}
Swift
let paymentRequest = "<bolt11 invoice>"
// Optionally set the amount you wish to pay the receiver
let optionalAmountSats: BInt? = BInt(5_000)

let prepareResponse = try await sdk.prepareSendPayment(
    request: PrepareSendPaymentRequest(
        paymentRequest: paymentRequest,
        amount: optionalAmountSats,
        tokenIdentifier: nil,
        conversionOptions: nil,
        feePolicy: nil
    ))

if case let .bolt11Invoice(_, sparkTransferFeeSats, lightningFeeSats) = prepareResponse
    .paymentMethod
{
    // Fees to pay via Lightning
    print("Lightning Fees: \(lightningFeeSats) sats")
    // Or fees to pay (if available) via a Spark transfer
    if let sparkTransferFeeSats = sparkTransferFeeSats {
        print("Spark Transfer Fees: \(sparkTransferFeeSats) sats")
    }
}
Kotlin
val paymentRequest = "<bolt11 invoice>"
// Optionally set the amount you wish to pay the receiver
// Kotlin MPP (BigInteger from com.ionspin.kotlin.bignum.integer)
val optionalAmountSats = BigInteger.fromLong(5_000L)
// Android (BigInteger from java.math)
// val optionalAmountSats = BigInteger.valueOf(5_000L)

try {
    val req = PrepareSendPaymentRequest(
        paymentRequest,
        amount = optionalAmountSats,
        tokenIdentifier = null,
        conversionOptions = null,
        feePolicy = null,
    )
    val prepareResponse = sdk.prepareSendPayment(req)

    // If the fees are acceptable, continue to create the Send Payment
    val paymentMethod = prepareResponse.paymentMethod
    if (paymentMethod is SendPaymentMethod.Bolt11Invoice) {
        // Fees to pay via Lightning
        val lightningFeeSats = paymentMethod.lightningFeeSats
        // Or fees to pay (if available) via a Spark transfer
        val sparkTransferFeeSats = paymentMethod.sparkTransferFeeSats
        // Log.v("Breez", "Lightning Fees: ${lightningFeeSats} sats")
        // Log.v("Breez", "Spark Transfer Fees: ${sparkTransferFeeSats} sats")
    }
} catch (e: Exception) {
    // handle error
}
C#
var paymentRequest = "<bolt11 invoice>";
// Optionally set the amount you wish to pay the receiver
ulong? optionalAmountSats = 5_000UL;

var request = new PrepareSendPaymentRequest(
    paymentRequest: paymentRequest,
    amount: optionalAmountSats,
    tokenIdentifier: null,
    conversionOptions: null,
    feePolicy: null
);
var prepareResponse = await sdk.PrepareSendPayment(request: request);

// If the fees are acceptable, continue to create the Send Payment
if (prepareResponse.paymentMethod is SendPaymentMethod.Bolt11Invoice bolt11Method)
{
    // Fees to pay via Lightning
    var lightningFeeSats = bolt11Method.lightningFeeSats;
    // Or fees to pay (if available) via a Spark transfer
    var sparkTransferFeeSats = bolt11Method.sparkTransferFeeSats;
    Console.WriteLine($"Lightning Fees: {lightningFeeSats} sats");
    Console.WriteLine($"Spark Transfer Fees: {sparkTransferFeeSats} sats");
}
Javascript
const paymentRequest = '<bolt11 invoice>'
// Optionally set the amount you wish to pay the receiver
const optionalAmountSats = BigInt(5_000)

const prepareResponse = await sdk.prepareSendPayment({
  paymentRequest,
  amount: optionalAmountSats,
  tokenIdentifier: undefined,
  conversionOptions: undefined,
  feePolicy: undefined
})

// If the fees are acceptable, continue to create the Send Payment
if (prepareResponse.paymentMethod.type === 'bolt11Invoice') {
  // Fees to pay via Lightning
  const lightningFeeSats = prepareResponse.paymentMethod.lightningFeeSats
  // Or fees to pay (if available) via a Spark transfer
  const sparkTransferFeeSats = prepareResponse.paymentMethod.sparkTransferFeeSats
  console.debug(`Lightning Fees: ${lightningFeeSats} sats`)
  console.debug(`Spark Transfer Fees: ${sparkTransferFeeSats} sats`)
}
React Native
const paymentRequest = '<bolt11 invoice>'
// Optionally set the amount you wish to pay the receiver
const optionalAmountSats = BigInt(5_000)

const prepareResponse = await sdk.prepareSendPayment({
  paymentRequest,
  amount: optionalAmountSats,
  tokenIdentifier: undefined,
  conversionOptions: undefined,
  feePolicy: undefined
})

// If the fees are acceptable, continue to create the Send Payment
if (prepareResponse.paymentMethod?.tag === SendPaymentMethod_Tags.Bolt11Invoice) {
  // Fees to pay via Lightning
  const lightningFeeSats = prepareResponse.paymentMethod.inner.lightningFeeSats
  // Or fees to pay (if available) via a Spark transfer
  const sparkTransferFeeSats = prepareResponse.paymentMethod.inner.sparkTransferFeeSats
  console.debug(`Lightning Fees: ${lightningFeeSats} sats`)
  console.debug(`Spark Transfer Fees: ${sparkTransferFeeSats} sats`)
}
Flutter
String paymentRequest = "<bolt11 invoice>";
// Optionally set the amount you wish to pay the receiver
BigInt? optionalAmountSats = BigInt.from(5000);

final request = PrepareSendPaymentRequest(
    paymentRequest: paymentRequest,
    amount: optionalAmountSats,
    tokenIdentifier: null,
    conversionOptions: null,
    feePolicy: null);
final response = await sdk.prepareSendPayment(request: request);

// If the fees are acceptable, continue to create the Send Payment
final paymentMethod = response.paymentMethod;
if (paymentMethod is SendPaymentMethod_Bolt11Invoice) {
  // Fees to pay via Lightning
  final lightningFeeSats = paymentMethod.lightningFeeSats;
  // Or fees to pay (if available) via a Spark transfer
  final sparkTransferFeeSats = paymentMethod.sparkTransferFeeSats;
  print("Lightning Fees: $lightningFeeSats sats");
  print("Spark Transfer Fees: $sparkTransferFeeSats sats");
}
Python
payment_request = "<bolt11 invoice>"
optional_amount_sats = 5_000
try:
    request = PrepareSendPaymentRequest(
        payment_request=payment_request,
        amount=optional_amount_sats,
        token_identifier=None,
        conversion_options=None,
        fee_policy=None,
    )
    prepare_response = await sdk.prepare_send_payment(request=request)

    # If the fees are acceptable, continue to create the Send Payment
    if isinstance(
        prepare_response.payment_method, SendPaymentMethod.BOLT11_INVOICE
    ):
        # Fees to pay via Lightning
        lightning_fee_sats = prepare_response.payment_method.lightning_fee_sats
        # Or fees to pay (if available) via a Spark transfer
        spark_transfer_fee_sats = (
            prepare_response.payment_method.spark_transfer_fee_sats
        )
        logging.debug(f"Lightning Fees: {lightning_fee_sats} sats")
        logging.debug(f"Spark Transfer Fees: {spark_transfer_fee_sats} sats")
except Exception as error:
    logging.error(error)
    raise
Go
paymentRequest := "<bolt11 invoice>"
// Optionally set the amount you wish to pay the receiver
optionalAmountSats := new(big.Int).SetInt64(5_000)

request := breez_sdk_spark.PrepareSendPaymentRequest{
	PaymentRequest:    paymentRequest,
	Amount:            &optionalAmountSats,
	TokenIdentifier:   nil,
	ConversionOptions: nil,
	FeePolicy:         nil,
}
response, err := sdk.PrepareSendPayment(request)

if err != nil {
	var sdkErr *breez_sdk_spark.SdkError
	if errors.As(err, &sdkErr) {
		// Handle SdkError - can inspect specific variants if needed
		// e.g., switch on sdkErr variant for InsufficientFunds, NetworkError, etc.
	}
	return nil, err
}

// If the fees are acceptable, continue to create the Send Payment
switch paymentMethod := response.PaymentMethod.(type) {
case breez_sdk_spark.SendPaymentMethodBolt11Invoice:
	// Fees to pay via Lightning
	lightningFeeSats := paymentMethod.LightningFeeSats
	// Or fees to pay (if available) via a Spark transfer
	sparkTransferFeeSats := paymentMethod.SparkTransferFeeSats
	log.Printf("Lightning Fees: %v sats", lightningFeeSats)
	log.Printf("Spark Transfer Fees: %v sats", sparkTransferFeeSats)
}

Bitcoin

For Bitcoin addresses, the amount must be set in the request. The prepare response includes fee quotes for three payment speeds: Slow, Medium, and Fast.

Rust
let payment_request = "<bitcoin address>".to_string();
// Set the amount you wish to pay the receiver
let amount_sats = Some(50_000);

let prepare_response = sdk
    .prepare_send_payment(PrepareSendPaymentRequest {
        payment_request,
        amount: amount_sats,
        token_identifier: None,
        conversion_options: None,
        fee_policy: None,
    })
    .await?;

// Review the fee quote for each confirmation speed
if let SendPaymentMethod::BitcoinAddress { fee_quote, .. } = &prepare_response.payment_method {
    info!("Slow fee: {} sats", fee_quote.speed_slow.total_fee_sat());
    info!("Medium fee: {} sats", fee_quote.speed_medium.total_fee_sat());
    info!("Fast fee: {} sats", fee_quote.speed_fast.total_fee_sat());
}
Swift
let paymentRequest = "<bitcoin address>"
// Set the amount you wish to pay the receiver
let amountSats = BInt(50_000)

let prepareResponse = try await sdk.prepareSendPayment(
    request: PrepareSendPaymentRequest(
        paymentRequest: paymentRequest,
        amount: amountSats,
        tokenIdentifier: nil,
        conversionOptions: nil,
        feePolicy: nil
    ))

// Review the fee quote for each confirmation speed
if case let .bitcoinAddress(address: _, feeQuote: feeQuote) = prepareResponse.paymentMethod {
    let slowFeeSats = feeQuote.speedSlow.userFeeSat + feeQuote.speedSlow.l1BroadcastFeeSat
    let mediumFeeSats = feeQuote.speedMedium.userFeeSat + feeQuote.speedMedium.l1BroadcastFeeSat
    let fastFeeSats = feeQuote.speedFast.userFeeSat + feeQuote.speedFast.l1BroadcastFeeSat
    print("Slow fee: \(slowFeeSats) sats")
    print("Medium fee: \(mediumFeeSats) sats")
    print("Fast fee: \(fastFeeSats) sats")
}
Kotlin
val paymentRequest = "<bitcoin address>"
// Set the amount you wish to pay the receiver
// Kotlin MPP (BigInteger from com.ionspin.kotlin.bignum.integer)
val amountSats = BigInteger.fromLong(50_000L)
// Android (BigInteger from java.math)
// val amountSats = BigInteger.valueOf(50_000L)

try {
    val req = PrepareSendPaymentRequest(
        paymentRequest,
        amount = amountSats,
        tokenIdentifier = null,
        conversionOptions = null,
        feePolicy = null,
    )
    val prepareResponse = sdk.prepareSendPayment(req)

    // Review the fee quote for each confirmation speed
    val paymentMethod = prepareResponse.paymentMethod
    if (paymentMethod is SendPaymentMethod.BitcoinAddress) {
        val feeQuote = paymentMethod.feeQuote
        val slowFeeSats = feeQuote.speedSlow.userFeeSat + feeQuote.speedSlow.l1BroadcastFeeSat
        val mediumFeeSats = feeQuote.speedMedium.userFeeSat + feeQuote.speedMedium.l1BroadcastFeeSat
        val fastFeeSats = feeQuote.speedFast.userFeeSat + feeQuote.speedFast.l1BroadcastFeeSat
        // Log.v("Breez", "Slow fee: $slowFeeSats sats")
        // Log.v("Breez", "Medium fee: $mediumFeeSats sats")
        // Log.v("Breez", "Fast fee: $fastFeeSats sats")
    }
} catch (e: Exception) {
    // handle error
}
C#
var paymentRequest = "<bitcoin address>";
// Set the amount you wish to pay the receiver
ulong? amountSats = 50_000UL;

var request = new PrepareSendPaymentRequest(
    paymentRequest: paymentRequest,
    amount: amountSats,
    tokenIdentifier: null,
    conversionOptions: null,
    feePolicy: null
);
var prepareResponse = await sdk.PrepareSendPayment(request: request);

// Review the fee quote for each confirmation speed
if (prepareResponse.paymentMethod is SendPaymentMethod.BitcoinAddress bitcoinMethod)
{
    var feeQuote = bitcoinMethod.feeQuote;
    var slowFeeSats = feeQuote.speedSlow.userFeeSat + feeQuote.speedSlow.l1BroadcastFeeSat;
    var mediumFeeSats = feeQuote.speedMedium.userFeeSat + feeQuote.speedMedium.l1BroadcastFeeSat;
    var fastFeeSats = feeQuote.speedFast.userFeeSat + feeQuote.speedFast.l1BroadcastFeeSat;
    Console.WriteLine($"Slow fee: {slowFeeSats} sats");
    Console.WriteLine($"Medium fee: {mediumFeeSats} sats");
    Console.WriteLine($"Fast fee: {fastFeeSats} sats");
}
Javascript
const paymentRequest = '<bitcoin address>'
// Set the amount you wish to pay the receiver
const amountSats = BigInt(50_000)

const prepareResponse = await sdk.prepareSendPayment({
  paymentRequest,
  amount: amountSats,
  tokenIdentifier: undefined,
  conversionOptions: undefined,
  feePolicy: undefined
})

// Review the fee quote for each confirmation speed
if (prepareResponse.paymentMethod.type === 'bitcoinAddress') {
  const feeQuote = prepareResponse.paymentMethod.feeQuote
  const slowFeeSats = feeQuote.speedSlow.userFeeSat + feeQuote.speedSlow.l1BroadcastFeeSat
  const mediumFeeSats = feeQuote.speedMedium.userFeeSat + feeQuote.speedMedium.l1BroadcastFeeSat
  const fastFeeSats = feeQuote.speedFast.userFeeSat + feeQuote.speedFast.l1BroadcastFeeSat
  console.debug(`Slow fee: ${slowFeeSats} sats`)
  console.debug(`Medium fee: ${mediumFeeSats} sats`)
  console.debug(`Fast fee: ${fastFeeSats} sats`)
}
React Native
const paymentRequest = '<bitcoin address>'
// Set the amount you wish to pay the receiver
const amountSats = BigInt(50_000)

const prepareResponse = await sdk.prepareSendPayment({
  paymentRequest,
  amount: amountSats,
  tokenIdentifier: undefined,
  conversionOptions: undefined,
  feePolicy: undefined
})

// Review the fee quote for each confirmation speed
if (prepareResponse.paymentMethod?.tag === SendPaymentMethod_Tags.BitcoinAddress) {
  const feeQuote = prepareResponse.paymentMethod.inner.feeQuote
  const slowFeeSats = feeQuote.speedSlow.userFeeSat + feeQuote.speedSlow.l1BroadcastFeeSat
  const mediumFeeSats = feeQuote.speedMedium.userFeeSat + feeQuote.speedMedium.l1BroadcastFeeSat
  const fastFeeSats = feeQuote.speedFast.userFeeSat + feeQuote.speedFast.l1BroadcastFeeSat
  console.debug(`Slow fee: ${slowFeeSats} sats`)
  console.debug(`Medium fee: ${mediumFeeSats} sats`)
  console.debug(`Fast fee: ${fastFeeSats} sats`)
}
Flutter
String paymentRequest = "<bitcoin address>";
// Set the amount you wish to pay the receiver
BigInt? amountSats = BigInt.from(50000);

final request = PrepareSendPaymentRequest(
    paymentRequest: paymentRequest,
    amount: amountSats,
    tokenIdentifier: null,
    conversionOptions: null,
    feePolicy: null);
final response = await sdk.prepareSendPayment(request: request);

// Review the fee quote for each confirmation speed
final paymentMethod = response.paymentMethod;
if (paymentMethod is SendPaymentMethod_BitcoinAddress) {
  final feeQuote = paymentMethod.feeQuote;
  final slowFeeSats = feeQuote.speedSlow.userFeeSat + feeQuote.speedSlow.l1BroadcastFeeSat;
  final mediumFeeSats = feeQuote.speedMedium.userFeeSat + feeQuote.speedMedium.l1BroadcastFeeSat;
  final fastFeeSats = feeQuote.speedFast.userFeeSat + feeQuote.speedFast.l1BroadcastFeeSat;
  print("Slow fee: $slowFeeSats sats");
  print("Medium fee: $mediumFeeSats sats");
  print("Fast fee: $fastFeeSats sats");
}
Python
payment_request = "<bitcoin address>"
amount_sats = 50_000
try:
    request = PrepareSendPaymentRequest(
        payment_request=payment_request,
        amount=amount_sats,
        token_identifier=None,
        conversion_options=None,
        fee_policy=None,
    )
    prepare_response = await sdk.prepare_send_payment(request=request)

    # Review the fee quote for each confirmation speed
    if isinstance(
        prepare_response.payment_method, SendPaymentMethod.BITCOIN_ADDRESS
    ):
        fee_quote = prepare_response.payment_method.fee_quote
        slow_fee_sats = (
            fee_quote.speed_slow.user_fee_sat
            + fee_quote.speed_slow.l1_broadcast_fee_sat
        )
        medium_fee_sats = (
            fee_quote.speed_medium.user_fee_sat
            + fee_quote.speed_medium.l1_broadcast_fee_sat
        )
        fast_fee_sats = (
            fee_quote.speed_fast.user_fee_sat
            + fee_quote.speed_fast.l1_broadcast_fee_sat
        )
        logging.debug(f"Slow fee: {slow_fee_sats} sats")
        logging.debug(f"Medium fee: {medium_fee_sats} sats")
        logging.debug(f"Fast fee: {fast_fee_sats} sats")
except Exception as error:
    logging.error(error)
    raise
Go
paymentRequest := "<bitcoin address>"
// Set the amount you wish to pay the receiver
amountSats := new(big.Int).SetInt64(50_000)

request := breez_sdk_spark.PrepareSendPaymentRequest{
	PaymentRequest:    paymentRequest,
	Amount:            &amountSats,
	TokenIdentifier:   nil,
	ConversionOptions: nil,
	FeePolicy:         nil,
}
response, err := sdk.PrepareSendPayment(request)

if err != nil {
	var sdkErr *breez_sdk_spark.SdkError
	if errors.As(err, &sdkErr) {
		// Handle SdkError - can inspect specific variants if needed
		// e.g., switch on sdkErr variant for InsufficientFunds, NetworkError, etc.
	}
	return nil, err
}

// Review the fee quote for each confirmation speed
switch paymentMethod := response.PaymentMethod.(type) {
case breez_sdk_spark.SendPaymentMethodBitcoinAddress:
	feeQuote := paymentMethod.FeeQuote
	slowFeeSats := feeQuote.SpeedSlow.UserFeeSat + feeQuote.SpeedSlow.L1BroadcastFeeSat
	mediumFeeSats := feeQuote.SpeedMedium.UserFeeSat + feeQuote.SpeedMedium.L1BroadcastFeeSat
	fastFeeSats := feeQuote.SpeedFast.UserFeeSat + feeQuote.SpeedFast.L1BroadcastFeeSat
	log.Printf("Slow fee: %v sats", slowFeeSats)
	log.Printf("Medium fee: %v sats", mediumFeeSats)
	log.Printf("Fast fee: %v sats", fastFeeSats)
}

Spark

Spark address

For Spark addresses, the amount must be set in the request. Sending to a Spark address uses a direct Spark transfer.

Rust
let payment_request = "<spark address>".to_string();
// Set the amount you wish to pay the receiver
let amount_sats = Some(50_000);

let prepare_response = sdk
    .prepare_send_payment(PrepareSendPaymentRequest {
        payment_request,
        amount: amount_sats,
        token_identifier: None,
        conversion_options: None,
        fee_policy: None,
    })
    .await?;

// If the fees are acceptable, continue to create the Send Payment
if let SendPaymentMethod::SparkAddress { fee, .. } = prepare_response.payment_method {
    info!("Fees: {} sats", fee);
}
Swift
let paymentRequest = "<spark address>"
// Set the amount you wish to pay the receiver
let amountSats = BInt(50_000)

let prepareResponse = try await sdk.prepareSendPayment(
    request: PrepareSendPaymentRequest(
        paymentRequest: paymentRequest,
        amount: amountSats,
        tokenIdentifier: nil,
        conversionOptions: nil,
        feePolicy: nil
    ))

if case let .sparkAddress(_, feeSats, _) = prepareResponse.paymentMethod {
    print("Fees: \(feeSats) sats")
}
Kotlin
val paymentRequest = "<spark address>"
// Set the amount you wish to pay the receiver
// Kotlin MPP (BigInteger from com.ionspin.kotlin.bignum.integer)
val amountSats = BigInteger.fromLong(50_000L)
// Android (BigInteger from java.math)
// val amountSats = BigInteger.valueOf(50_000L)

try {
    val req = PrepareSendPaymentRequest(
        paymentRequest,
        amount = amountSats,
        tokenIdentifier = null,
        conversionOptions = null,
        feePolicy = null,
    )
    val prepareResponse = sdk.prepareSendPayment(req)

    // If the fees are acceptable, continue to create the Send Payment
    val paymentMethod = prepareResponse.paymentMethod
    if (paymentMethod is SendPaymentMethod.SparkAddress) {
        val feeSats = paymentMethod.fee
        // Log.v("Breez", "Fees: ${feeSats} sats")
    }
} catch (e: Exception) {
    // handle error
}
C#
var paymentRequest = "<spark address>";
// Set the amount you wish to pay the receiver
ulong? amountSats = 50_000UL;

var request = new PrepareSendPaymentRequest(
    paymentRequest: paymentRequest,
    amount: amountSats,
    tokenIdentifier: null,
    conversionOptions: null,
    feePolicy: null
);
var prepareResponse = await sdk.PrepareSendPayment(request: request);

// If the fees are acceptable, continue to create the Send Payment
if (prepareResponse.paymentMethod is SendPaymentMethod.SparkAddress sparkMethod)
{
    var fee = sparkMethod.fee;
    Console.WriteLine($"Fees: {fee} sats");
}
Javascript
const paymentRequest = '<spark address>'
// Set the amount you wish to pay the receiver
const amountSats = BigInt(50_000)

const prepareResponse = await sdk.prepareSendPayment({
  paymentRequest,
  amount: amountSats,
  tokenIdentifier: undefined,
  conversionOptions: undefined,
  feePolicy: undefined
})

// If the fees are acceptable, continue to create the Send Payment
if (prepareResponse.paymentMethod.type === 'sparkAddress') {
  const feeSats = prepareResponse.paymentMethod.fee
  console.debug(`Fees: ${feeSats} sats`)
}
React Native
const paymentRequest = '<spark address>'
// Set the amount you wish to pay the receiver
const amountSats = BigInt(50_000)

const prepareResponse = await sdk.prepareSendPayment({
  paymentRequest,
  amount: amountSats,
  tokenIdentifier: undefined,
  conversionOptions: undefined,
  feePolicy: undefined
})

// If the fees are acceptable, continue to create the Send Payment
if (prepareResponse.paymentMethod?.tag === SendPaymentMethod_Tags.SparkAddress) {
  const feeSats = prepareResponse.paymentMethod.inner.fee
  console.debug(`Fees: ${feeSats} sats`)
}
Flutter
String paymentRequest = "<spark address>";
// Set the amount you wish to pay the receiver
BigInt? amountSats = BigInt.from(50000);

final request = PrepareSendPaymentRequest(
    paymentRequest: paymentRequest,
    amount: amountSats,
    tokenIdentifier: null,
    conversionOptions: null,
    feePolicy: null);
final response = await sdk.prepareSendPayment(request: request);

// If the fees are acceptable, continue to create the Send Payment
final paymentMethod = response.paymentMethod;
if (paymentMethod is SendPaymentMethod_SparkAddress) {
  final feeSats = paymentMethod.fee;
  print("Fees: $feeSats sats");
}
Python
payment_request = "<spark address>"
amount_sats = 50_000
try:
    request = PrepareSendPaymentRequest(
        payment_request=payment_request,
        amount=amount_sats,
        token_identifier=None,
        conversion_options=None,
        fee_policy=None,
    )
    prepare_response = await sdk.prepare_send_payment(request=request)

    # If the fees are acceptable, continue to create the Send Payment
    if isinstance(prepare_response.payment_method, SendPaymentMethod.SPARK_ADDRESS):
        fee = prepare_response.payment_method.fee
        logging.debug(f"Fees: {fee} sats")
except Exception as error:
    logging.error(error)
    raise
Go
paymentRequest := "<spark address>"
// Set the amount you wish to pay the receiver
amountSats := new(big.Int).SetInt64(50_000)

request := breez_sdk_spark.PrepareSendPaymentRequest{
	PaymentRequest:    paymentRequest,
	Amount:            &amountSats,
	TokenIdentifier:   nil,
	ConversionOptions: nil,
	FeePolicy:         nil,
}
response, err := sdk.PrepareSendPayment(request)

if err != nil {
	var sdkErr *breez_sdk_spark.SdkError
	if errors.As(err, &sdkErr) {
		// Handle SdkError - can inspect specific variants if needed
		// e.g., switch on sdkErr variant for InsufficientFunds, NetworkError, etc.
	}
	return nil, err
}

// If the fees are acceptable, continue to create the Send Payment
switch paymentMethod := response.PaymentMethod.(type) {
case breez_sdk_spark.SendPaymentMethodSparkAddress:
	feeSats := paymentMethod.Fee
	log.Printf("Fees: %v sats", feeSats)
}

Spark invoice

For Spark invoices, the amount can be optionally set. It is only required if the invoice doesn't specify an amount. If the invoice specifies an amount, providing a different amount is not supported.

Developer note

Spark invoices may require a token (non-Bitcoin) as the payment asset. To determine the requirements of a Spark invoice and any restrictions it may impose, see the Parsing inputs page. To learn more about tokens, see the Handling tokens page.
Rust
let payment_request = "<spark invoice>".to_string();
// Optionally set the amount you wish to pay the receiver
let optional_amount_sats = Some(50_000);

let prepare_response = sdk
    .prepare_send_payment(PrepareSendPaymentRequest {
        payment_request,
        amount: optional_amount_sats,
        token_identifier: None,
        conversion_options: None,
        fee_policy: None,
    })
    .await?;

// If the fees are acceptable, continue to create the Send Payment
if let SendPaymentMethod::SparkInvoice { fee, .. } = prepare_response.payment_method {
    info!("Fees: {} sats", fee);
}
Swift
let paymentRequest = "<spark invoice>"
// Optionally set the amount you wish to pay the receiver
let optionalAmountSats: BInt? = BInt(50_000)

let prepareResponse = try await sdk.prepareSendPayment(
    request: PrepareSendPaymentRequest(
        paymentRequest: paymentRequest,
        amount: optionalAmountSats,
        tokenIdentifier: nil,
        conversionOptions: nil,
        feePolicy: nil
    ))

if case let .sparkInvoice(_, feeSats, _) = prepareResponse.paymentMethod {
    print("Fees: \(feeSats) sats")
}
Kotlin
val paymentRequest = "<spark invoice>"
// Optionally set the amount you wish to pay the receiver
// Kotlin MPP (BigInteger from com.ionspin.kotlin.bignum.integer)
val optionalAmountSats = BigInteger.fromLong(50_000L)
// Android (BigInteger from java.math)
// val optionalAmountSats = BigInteger.valueOf(50_000L)

try {
    val req = PrepareSendPaymentRequest(
        paymentRequest,
        amount = optionalAmountSats,
        tokenIdentifier = null,
        conversionOptions = null,
        feePolicy = null,
    )
    val prepareResponse = sdk.prepareSendPayment(req)

    // If the fees are acceptable, continue to create the Send Payment
    val paymentMethod = prepareResponse.paymentMethod
    if (paymentMethod is SendPaymentMethod.SparkInvoice) {
        val feeSats = paymentMethod.fee
        // Log.v("Breez", "Fees: ${feeSats} sats")
    }
} catch (e: Exception) {
    // handle error
}
C#
var paymentRequest = "<spark invoice>";
// Optionally set the amount you wish to pay the receiver
ulong? optionalAmountSats = 50_000UL;

var request = new PrepareSendPaymentRequest(
    paymentRequest: paymentRequest,
    amount: optionalAmountSats,
    tokenIdentifier: null,
    conversionOptions: null,
    feePolicy: null
);
var prepareResponse = await sdk.PrepareSendPayment(request: request);

// If the fees are acceptable, continue to create the Send Payment
if (prepareResponse.paymentMethod is SendPaymentMethod.SparkInvoice sparkInvoiceMethod)
{
    var fee = sparkInvoiceMethod.fee;
    Console.WriteLine($"Fees: {fee} sats");
}
Javascript
const paymentRequest = '<spark invoice>'
// Optionally set the amount you wish to pay the receiver
const optionalAmountSats = BigInt(50_000)

const prepareResponse = await sdk.prepareSendPayment({
  paymentRequest,
  amount: optionalAmountSats,
  tokenIdentifier: undefined,
  conversionOptions: undefined,
  feePolicy: undefined
})

// If the fees are acceptable, continue to create the Send Payment
if (prepareResponse.paymentMethod.type === 'sparkInvoice') {
  const feeSats = prepareResponse.paymentMethod.fee
  console.debug(`Fees: ${feeSats} sats`)
}
React Native
const paymentRequest = '<spark invoice>'
// Optionally set the amount you wish to pay the receiver
const optionalAmountSats = BigInt(50_000)

const prepareResponse = await sdk.prepareSendPayment({
  paymentRequest,
  amount: optionalAmountSats,
  tokenIdentifier: undefined,
  conversionOptions: undefined,
  feePolicy: undefined
})

// If the fees are acceptable, continue to create the Send Payment
if (prepareResponse.paymentMethod?.tag === SendPaymentMethod_Tags.SparkInvoice) {
  const feeSats = prepareResponse.paymentMethod.inner.fee
  console.debug(`Fees: ${feeSats} sats`)
}
Flutter
String paymentRequest = "<spark invoice>";
// Optionally set the amount you wish to pay the receiver
BigInt? optionalAmountSats = BigInt.from(50000);

final request = PrepareSendPaymentRequest(
    paymentRequest: paymentRequest,
    amount: optionalAmountSats,
    tokenIdentifier: null,
    conversionOptions: null,
    feePolicy: null);
final response = await sdk.prepareSendPayment(request: request);

// If the fees are acceptable, continue to create the Send Payment
final paymentMethod = response.paymentMethod;
if (paymentMethod is SendPaymentMethod_SparkInvoice) {
  final feeSats = paymentMethod.fee;
  print("Fees: $feeSats sats");
}
Python
payment_request = "<spark invoice>"
optional_amount_sats = 50_000
try:
    request = PrepareSendPaymentRequest(
        payment_request=payment_request,
        amount=optional_amount_sats,
        token_identifier=None,
        conversion_options=None,
        fee_policy=None,
    )
    prepare_response = await sdk.prepare_send_payment(request=request)

    # If the fees are acceptable, continue to create the Send Payment
    if isinstance(prepare_response.payment_method, SendPaymentMethod.SPARK_INVOICE):
        fee = prepare_response.payment_method.fee
        logging.debug(f"Fees: {fee} sats")
except Exception as error:
    logging.error(error)
    raise
Go
paymentRequest := "<spark invoice>"
// Optionally set the amount you wish to pay the receiver
optionalAmountSats := new(big.Int).SetInt64(50_000)

request := breez_sdk_spark.PrepareSendPaymentRequest{
	PaymentRequest:    paymentRequest,
	Amount:            &optionalAmountSats,
	TokenIdentifier:   nil,
	ConversionOptions: nil,
	FeePolicy:         nil,
}
response, err := sdk.PrepareSendPayment(request)

if err != nil {
	var sdkErr *breez_sdk_spark.SdkError
	if errors.As(err, &sdkErr) {
		// Handle SdkError - can inspect specific variants if needed
		// e.g., switch on sdkErr variant for InsufficientFunds, NetworkError, etc.
	}
	return nil, err
}

// If the fees are acceptable, continue to create the Send Payment
switch paymentMethod := response.PaymentMethod.(type) {
case breez_sdk_spark.SendPaymentMethodSparkInvoice:
	feeSats := paymentMethod.Fee
	log.Printf("Fees: %v sats", feeSats)
}

Fee Policy

By default, fees are added on top of the amount (FeePolicy::FeesExcludedFeePolicy.FEES_EXCLUDEDFeePolicy.feesExcludedFeePolicy.FeesExcludedFeePolicy.FeesExcludedFeePolicy.FeesExcludedFeePolicy.FeesExcludedFeePolicyFeesExcludedFeePolicy.FeesExcluded). Use FeePolicy::FeesIncludedFeePolicy.FEES_INCLUDEDFeePolicy.feesIncludedFeePolicy.FeesIncludedFeePolicy.FeesIncludedFeePolicy.FeesIncludedFeePolicy.FeesIncludedFeePolicyFeesIncludedFeePolicy.FeesIncluded to deduct fees from the amount instead—the receiver gets the amount minus fees.

This is particularly useful when you want to spend your entire balance in a single payment—simply provide your full balance as the amount. Note: FeePolicy::FeesIncludedFeePolicy.FEES_INCLUDEDFeePolicy.feesIncludedFeePolicy.FeesIncludedFeePolicy.FeesIncludedFeePolicy.FeesIncludedFeePolicy.FeesIncludedFeePolicyFeesIncludedFeePolicy.FeesIncluded is not compatible with payment requests that specify an amount (e.g., BOLT11 invoices and Spark invoices with amount).

Rust
// By default (FeePolicy::FeesExcluded), fees are added on top of the amount.
// Use FeePolicy::FeesIncluded to deduct fees from the amount instead.
// The receiver gets amount minus fees.
let payment_request = "<payment request>".to_string();
let amount_sats = Some(50_000);

let prepare_response = sdk
    .prepare_send_payment(PrepareSendPaymentRequest {
        payment_request,
        amount: amount_sats,
        token_identifier: None,
        conversion_options: None,
        fee_policy: Some(FeePolicy::FeesIncluded),
    })
    .await?;

// The response shows the fee policy used
info!("Fee policy: {:?}", prepare_response.fee_policy);
info!("Amount: {}", prepare_response.amount);
// The receiver gets amount - fees (fees are available in prepare_response.payment_method)
Swift
// By default (.feesExcluded), fees are added on top of the amount.
// Use .feesIncluded to deduct fees from the amount instead.
// The receiver gets amount minus fees.
let paymentRequest = "<payment request>"
let amountSats: BInt? = BInt(50_000)

let prepareResponse = try await sdk.prepareSendPayment(
    request: PrepareSendPaymentRequest(
        paymentRequest: paymentRequest,
        amount: amountSats,
        tokenIdentifier: nil,
        conversionOptions: nil,
        feePolicy: .feesIncluded
    ))

// The response shows the fee policy used
print("Fee policy: \(String(describing: prepareResponse.feePolicy))")
print("Amount: \(String(describing: prepareResponse.amount))")
// The receiver gets amount - fees (fees are available in prepareResponse.paymentMethod)
Kotlin
// By default (FeePolicy.FEES_EXCLUDED), fees are added on top of the amount.
// Use FeePolicy.FEES_INCLUDED to deduct fees from the amount instead.
// The receiver gets amount minus fees.
val paymentRequest = "<payment request>"
// Kotlin MPP (BigInteger from com.ionspin.kotlin.bignum.integer)
val amountSats = BigInteger.fromLong(50_000L)
// Android (BigInteger from java.math)
// val amountSats = BigInteger.valueOf(50_000L)

try {
    val req = PrepareSendPaymentRequest(
        paymentRequest,
        amount = amountSats,
        tokenIdentifier = null,
        conversionOptions = null,
        feePolicy = FeePolicy.FEES_INCLUDED,
    )
    val prepareResponse = sdk.prepareSendPayment(req)

    // The response shows the fee policy used
    // Log.v("Breez", "Fee policy: ${prepareResponse.feePolicy}")
    // Log.v("Breez", "Amount: ${prepareResponse.amount}")
    // The receiver gets amount - fees (fees are available in prepareResponse.paymentMethod)
} catch (e: Exception) {
    // handle error
}
C#
// By default (FeePolicy.FeesExcluded), fees are added on top of the amount.
// Use FeePolicy.FeesIncluded to deduct fees from the amount instead.
// The receiver gets amount minus fees.
var paymentRequest = "<payment request>";
ulong? amountSats = 50_000UL;

var request = new PrepareSendPaymentRequest(
    paymentRequest: paymentRequest,
    amount: amountSats,
    tokenIdentifier: null,
    conversionOptions: null,
    feePolicy: FeePolicy.FeesIncluded
);
var prepareResponse = await sdk.PrepareSendPayment(request: request);

// The response shows the fee policy used
Console.WriteLine($"Fee policy: {prepareResponse.feePolicy}");
Console.WriteLine($"Amount: {prepareResponse.amount}");
// The receiver gets amount - fees (fees are available in prepareResponse.paymentMethod)
Javascript
// By default ({ type: 'feesExcluded' }), fees are added on top of the amount.
// Use { type: 'feesIncluded' } to deduct fees from the amount instead.
// The receiver gets amount minus fees.
const paymentRequest = '<payment request>'
const amountSats = BigInt(50_000)
const feePolicy: FeePolicy = 'feesIncluded'

const prepareResponse = await sdk.prepareSendPayment({
  paymentRequest,
  amount: amountSats,
  tokenIdentifier: undefined,
  conversionOptions: undefined,
  feePolicy
})

// The response shows the fee policy used
console.log(`Fee policy: ${JSON.stringify(prepareResponse.feePolicy)}`)
console.log(`Amount: ${prepareResponse.amount}`)
// The receiver gets amount - fees (fees are available in prepareResponse.paymentMethod)
React Native
// By default (FeePolicy.FeesExcluded), fees are added on top of the amount.
// Use FeePolicy.FeesIncluded to deduct fees from the amount instead.
// The receiver gets amount minus fees.
const paymentRequest = '<payment request>'
const amountSats = BigInt(50_000)

const prepareResponse = await sdk.prepareSendPayment({
  paymentRequest,
  amount: amountSats,
  tokenIdentifier: undefined,
  conversionOptions: undefined,
  feePolicy: FeePolicy.FeesIncluded
})

// The response shows the fee policy used
console.log(`Fee policy: ${JSON.stringify(prepareResponse.feePolicy)}`)
console.log(`Amount: ${prepareResponse.amount}`)
// The receiver gets amount - fees (fees are available in prepareResponse.paymentMethod)
Flutter
// By default (FeePolicy.feesExcluded), fees are added on top of the amount.
// Use FeePolicy.feesIncluded to deduct fees from the amount instead.
// The receiver gets amount minus fees.
String paymentRequest = "<payment request>";
BigInt? amountSats = BigInt.from(50000);

final request = PrepareSendPaymentRequest(
    paymentRequest: paymentRequest,
    amount: amountSats,
    tokenIdentifier: null,
    conversionOptions: null,
    feePolicy: FeePolicy.feesIncluded);
final response = await sdk.prepareSendPayment(request: request);

// The response shows the fee policy used
print("Fee policy: ${response.feePolicy}");
print("Amount: ${response.amount}");
// The receiver gets amount - fees (fees are available in response.paymentMethod)
Python
# By default (FeePolicy.FEES_EXCLUDED), fees are added on top of the amount.
# Use FeePolicy.FEES_INCLUDED to deduct fees from the amount instead.
# The receiver gets amount minus fees.
payment_request = "<payment request>"
amount_sats = 50_000
try:
    request = PrepareSendPaymentRequest(
        payment_request=payment_request,
        amount=amount_sats,
        token_identifier=None,
        conversion_options=None,
        fee_policy=FeePolicy.FEES_INCLUDED,
    )
    prepare_response = await sdk.prepare_send_payment(request=request)

    # The response shows the fee policy used
    logging.debug(f"Fee policy: {prepare_response.fee_policy}")
    logging.debug(f"Amount: {prepare_response.amount}")
    # The receiver gets amount - fees (fees are available in prepare_response.payment_method)
except Exception as error:
    logging.error(error)
    raise
Go
// By default (FeePolicyFeesExcluded), fees are added on top of the amount.
// Use FeePolicyFeesIncluded to deduct fees from the amount instead.
// The receiver gets amount minus fees.
paymentRequest := "<payment request>"
amountSats := new(big.Int).SetInt64(50_000)
feePolicy := breez_sdk_spark.FeePolicyFeesIncluded

request := breez_sdk_spark.PrepareSendPaymentRequest{
	PaymentRequest:    paymentRequest,
	Amount:            &amountSats,
	TokenIdentifier:   nil,
	ConversionOptions: nil,
	FeePolicy:         &feePolicy,
}
response, err := sdk.PrepareSendPayment(request)

if err != nil {
	var sdkErr *breez_sdk_spark.SdkError
	if errors.As(err, &sdkErr) {
		// Handle SdkError - can inspect specific variants if needed
		// e.g., switch on sdkErr variant for InsufficientFunds, NetworkError, etc.
	}
	return nil, err
}

// The response shows the fee policy used
log.Printf("Fee policy: %v", response.FeePolicy)
log.Printf("Amount: %v", response.Amount)
// The receiver gets amount - fees (fees are available in response.PaymentMethod)

Sending Payments API docs

Once the payment has been prepared and the fees are accepted, the payment can be sent by passing:

  • Prepare Response - The response from the Preparing the Payment step.
  • Options - Any payment method specific options for the payment (see below).
  • Idempotency Key - An optional UUID that identifies the payment. If set, providing the same idempotency key for multiple requests will ensure that only one payment is made.

Lightning

In the optional send payment options for BOLT11 invoices, you can set:

  • Prefer Spark - Set the preference to use Spark to transfer the payment if the invoice contains a Spark address. By default, using Spark transfers are disabled.
  • Completion Timeout - By default, this function returns immediately. You can override this behavior by specifying a completion timeout in seconds. If the timeout is reached, a pending payment object is returned. If the payment completes within the timeout, the completed payment object is returned.
Rust
let options = Some(SendPaymentOptions::Bolt11Invoice {
    prefer_spark: false,
    completion_timeout_secs: Some(10),
});
let optional_idempotency_key = Some("<idempotency key uuid>".to_string());
let send_response = sdk
    .send_payment(SendPaymentRequest {
        prepare_response,
        options,
        idempotency_key: optional_idempotency_key,
    })
    .await?;
let payment = send_response.payment;
info!("Payment: {payment:?}");
Swift
let options = SendPaymentOptions.bolt11Invoice(preferSpark: false, completionTimeoutSecs: 10)
let optionalIdempotencyKey = "<idempotency key uuid>"
let sendResponse = try await sdk.sendPayment(
    request: SendPaymentRequest(
        prepareResponse: prepareResponse,
        options: options,
        idempotencyKey: optionalIdempotencyKey
    ))
let payment = sendResponse.payment
Kotlin
try {
    val options = SendPaymentOptions.Bolt11Invoice(
        preferSpark = false, 
        completionTimeoutSecs = 10u
    )
    val optionalIdempotencyKey = "<idempotency key uuid>"
    val sendResponse = sdk.sendPayment(
        SendPaymentRequest(
            prepareResponse,
            options,
            optionalIdempotencyKey
        )
    )
    val payment = sendResponse.payment
} catch (e: Exception) {
    // handle error
}
C#
var options = new SendPaymentOptions.Bolt11Invoice(
    preferSpark: false,
    completionTimeoutSecs: 10
);
var optionalIdempotencyKey = "<idempotency key uuid>";
var request = new SendPaymentRequest(
    prepareResponse: prepareResponse,
    options: options,
    idempotencyKey: optionalIdempotencyKey
);
var sendResponse = await sdk.SendPayment(request: request);
var payment = sendResponse.payment;
Javascript
const options: SendPaymentOptions = {
  type: 'bolt11Invoice',
  preferSpark: false,
  completionTimeoutSecs: 10
}
const optionalIdempotencyKey = '<idempotency key uuid>'
const sendResponse = await sdk.sendPayment({
  prepareResponse,
  options,
  idempotencyKey: optionalIdempotencyKey
})
const payment = sendResponse.payment
React Native
const options = new SendPaymentOptions.Bolt11Invoice({
  preferSpark: false,
  completionTimeoutSecs: 10
})
const optionalIdempotencyKey = '<idempotency key uuid>'
const sendResponse = await sdk.sendPayment({
  prepareResponse,
  options,
  idempotencyKey: optionalIdempotencyKey
})
const payment = sendResponse.payment
Flutter
final options = SendPaymentOptions.bolt11Invoice(
    preferSpark: false, completionTimeoutSecs: 10);
String? optionalIdempotencyKey = "<idempotency key uuid>";
final request = SendPaymentRequest(
    prepareResponse: prepareResponse,
    options: options,
    idempotencyKey: optionalIdempotencyKey);
SendPaymentResponse response = await sdk.sendPayment(request: request);
Payment payment = response.payment;
Python
try:
    options = SendPaymentOptions.BOLT11_INVOICE(
        prefer_spark=False, completion_timeout_secs=10
    )
    optional_idempotency_key = "<idempotency key uuid>"
    request = SendPaymentRequest(
        prepare_response=prepare_response,
        options=options,
        idempotency_key=optional_idempotency_key,
    )
    send_response = await sdk.send_payment(request=request)
    payment = send_response.payment
except Exception as error:
    logging.error(error)
    raise
Go
var completionTimeoutSecs uint32 = 10
var options breez_sdk_spark.SendPaymentOptions = breez_sdk_spark.SendPaymentOptionsBolt11Invoice{
	PreferSpark:           false,
	CompletionTimeoutSecs: &completionTimeoutSecs,
}

optionalIdempotencyKey := "<idempotency key uuid>"
request := breez_sdk_spark.SendPaymentRequest{
	PrepareResponse: prepareResponse,
	Options:         &options,
	IdempotencyKey:  &optionalIdempotencyKey,
}
response, err := sdk.SendPayment(request)

if err != nil {
	var sdkErr *breez_sdk_spark.SdkError
	if errors.As(err, &sdkErr) {
		// Handle SdkError - can inspect specific variants if needed
		// e.g., switch on sdkErr variant for InsufficientFunds, NetworkError, etc.
	}
	return nil, err
}

payment := response.Payment

Bitcoin

In the optional send payment options for Bitcoin addresses, you can set:

  • Confirmation Speed - The priority that the Bitcoin transaction confirms, that also effects the fee paid. By default, it is set to Fast.
Rust
// Select the confirmation speed for the on-chain transaction
let options = Some(SendPaymentOptions::BitcoinAddress {
    confirmation_speed: OnchainConfirmationSpeed::Medium,
});
let optional_idempotency_key = Some("<idempotency key uuid>".to_string());
let send_response = sdk
    .send_payment(SendPaymentRequest {
        prepare_response,
        options,
        idempotency_key: optional_idempotency_key,
    })
    .await?;
let payment = send_response.payment;
info!("Payment: {payment:?}");
Swift
// Select the confirmation speed for the on-chain transaction
let options = SendPaymentOptions.bitcoinAddress(
    confirmationSpeed: OnchainConfirmationSpeed.medium
)
let optionalIdempotencyKey = "<idempotency key uuid>"
let sendResponse = try await sdk.sendPayment(
    request: SendPaymentRequest(
        prepareResponse: prepareResponse,
        options: options,
        idempotencyKey: optionalIdempotencyKey
    ))
let payment = sendResponse.payment
Kotlin
try {
    // Select the confirmation speed for the on-chain transaction
    val options = SendPaymentOptions.BitcoinAddress(
        confirmationSpeed = OnchainConfirmationSpeed.MEDIUM
    )
    val optionalIdempotencyKey = "<idempotency key uuid>"
    val sendResponse = sdk.sendPayment(
        SendPaymentRequest(
            prepareResponse,
            options,
            optionalIdempotencyKey
        )
    )
    val payment = sendResponse.payment
} catch (e: Exception) {
    // handle error
}
C#
// Select the confirmation speed for the on-chain transaction
var options = new SendPaymentOptions.BitcoinAddress(
    confirmationSpeed: OnchainConfirmationSpeed.Medium
);
var optionalIdempotencyKey = "<idempotency key uuid>";
var request = new SendPaymentRequest(
    prepareResponse: prepareResponse,
    options: options,
    idempotencyKey: optionalIdempotencyKey
);
var sendResponse = await sdk.SendPayment(request: request);
var payment = sendResponse.payment;
Javascript
// Select the confirmation speed for the on-chain transaction
const options: SendPaymentOptions = {
  type: 'bitcoinAddress',
  confirmationSpeed: 'medium'
}
const optionalIdempotencyKey = '<idempotency key uuid>'
const sendResponse = await sdk.sendPayment({
  prepareResponse,
  options,
  idempotencyKey: optionalIdempotencyKey
})
const payment = sendResponse.payment
React Native
// Select the confirmation speed for the on-chain transaction
const options = new SendPaymentOptions.BitcoinAddress({
  confirmationSpeed: OnchainConfirmationSpeed.Medium
})
const optionalIdempotencyKey = '<idempotency key uuid>'
const sendResponse = await sdk.sendPayment({
  prepareResponse,
  options,
  idempotencyKey: optionalIdempotencyKey
})
const payment = sendResponse.payment
Flutter
// Select the confirmation speed for the on-chain transaction
final options = SendPaymentOptions.bitcoinAddress(
    confirmationSpeed: OnchainConfirmationSpeed.medium);
String? optionalIdempotencyKey = "<idempotency key uuid>";
final request = SendPaymentRequest(
    prepareResponse: prepareResponse,
    options: options,
    idempotencyKey: optionalIdempotencyKey);
SendPaymentResponse response = await sdk.sendPayment(request: request);
Payment payment = response.payment;
Python
try:
    # Select the confirmation speed for the on-chain transaction
    options = SendPaymentOptions.BITCOIN_ADDRESS(
        confirmation_speed=OnchainConfirmationSpeed.MEDIUM
    )
    optional_idempotency_key = "<idempotency key uuid>"
    request = SendPaymentRequest(
        prepare_response=prepare_response,
        options=options,
        idempotency_key=optional_idempotency_key,
    )
    send_response = await sdk.send_payment(request=request)
    payment = send_response.payment
except Exception as error:
    logging.error(error)
    raise
Go
// Select the confirmation speed for the on-chain transaction
var options breez_sdk_spark.SendPaymentOptions = breez_sdk_spark.SendPaymentOptionsBitcoinAddress{
	ConfirmationSpeed: breez_sdk_spark.OnchainConfirmationSpeedMedium,
}
optionalIdempotencyKey := "<idempotency key uuid>"
request := breez_sdk_spark.SendPaymentRequest{
	PrepareResponse: prepareResponse,
	Options:         &options,
	IdempotencyKey:  &optionalIdempotencyKey,
}
response, err := sdk.SendPayment(request)

if err != nil {
	var sdkErr *breez_sdk_spark.SdkError
	if errors.As(err, &sdkErr) {
		// Handle SdkError - can inspect specific variants if needed
		// e.g., switch on sdkErr variant for InsufficientFunds, NetworkError, etc.
	}
	return nil, err
}

payment := response.Payment

Spark

In the optional send payment options for Spark addresses, you can set:

  • HTLC Options - Enables Spark HTLC payments, which are an advanced feature that allows for conditional payments. See the Spark HTLC Payments page for more details and example usage.
Rust
let optional_idempotency_key = Some("<idempotency key uuid>".to_string());
let send_response = sdk
    .send_payment(SendPaymentRequest {
        prepare_response,
        options: None,
        idempotency_key: optional_idempotency_key,
    })
    .await?;
let payment = send_response.payment;
info!("Payment: {payment:?}");
Swift
let optionalIdempotencyKey = "<idempotency key uuid>"
let sendResponse = try await sdk.sendPayment(
    request: SendPaymentRequest(
        prepareResponse: prepareResponse,
        idempotencyKey: optionalIdempotencyKey
    ))
let payment = sendResponse.payment
Kotlin
try {
    val optionalIdempotencyKey = "<idempotency key uuid>"
    val sendResponse = sdk.sendPayment(
        SendPaymentRequest(
            prepareResponse,
            idempotencyKey = optionalIdempotencyKey
        )
    )
    val payment = sendResponse.payment
} catch (e: Exception) {
    // handle error
}
C#
var optionalIdempotencyKey = "<idempotency key uuid>";
var request = new SendPaymentRequest(
    prepareResponse: prepareResponse,
    idempotencyKey: optionalIdempotencyKey
);
var sendResponse = await sdk.SendPayment(request: request);
var payment = sendResponse.payment;
Javascript
const optionalIdempotencyKey = '<idempotency key uuid>'
const sendResponse = await sdk.sendPayment({
  prepareResponse,
  idempotencyKey: optionalIdempotencyKey
})
const payment = sendResponse.payment
React Native
const optionalIdempotencyKey = '<idempotency key uuid>'
const sendResponse = await sdk.sendPayment({
  prepareResponse,
  options: undefined,
  idempotencyKey: optionalIdempotencyKey
})
const payment = sendResponse.payment
Flutter
String? optionalIdempotencyKey = "<idempotency key uuid>";
final request = SendPaymentRequest(
    prepareResponse: prepareResponse, idempotencyKey: optionalIdempotencyKey);
SendPaymentResponse response = await sdk.sendPayment(request: request);
Payment payment = response.payment;
Python
try:
    optional_idempotency_key = "<idempotency key uuid>"
    request = SendPaymentRequest(
        prepare_response=prepare_response, idempotency_key=optional_idempotency_key
    )
    send_response = await sdk.send_payment(request=request)
    payment = send_response.payment
except Exception as error:
    logging.error(error)
    raise
Go
optionalIdempotencyKey := "<idempotency key uuid>"
request := breez_sdk_spark.SendPaymentRequest{
	PrepareResponse: prepareResponse,
	IdempotencyKey:  &optionalIdempotencyKey,
}
response, err := sdk.SendPayment(request)

if err != nil {
	var sdkErr *breez_sdk_spark.SdkError
	if errors.As(err, &sdkErr) {
		// Handle SdkError - can inspect specific variants if needed
		// e.g., switch on sdkErr variant for InsufficientFunds, NetworkError, etc.
	}
	return nil, err
}

payment := response.Payment

Event Flows

Once a send payment is initiated, you can follow and react to the different payment events using the guide below for each payment method. See Listening to events for how to subscribe to events.

EventDescriptionUX Suggestion
SyncedThe SDK has synced payments in the background.Update the payments list and balance. See listing payments and fetching the balance.

Lightning

EventDescriptionUX Suggestion
PaymentPendingThe Spark transfer has been started. Awaiting Lightning payment completion.Show payment as pending.
PaymentSucceededThe Lightning invoice has been paid either over Lightning or via a Spark transferUpdate the balance and show payment as complete.
PaymentFailedThe attempt to pay the Lightning invoice failed.

Bitcoin

EventDescriptionUX Suggestion
PaymentPendingThe Spark transfer has been started. Awaiting on-chain withdrawal completion.Show payment as pending.
PaymentSucceededThe payment amount was successfully withdrawn on-chain.Update the balance and show payment as complete.

Spark

EventDescriptionUX Suggestion
PaymentSucceededThe Spark transfer is complete.Update the balance and show payment as complete.