Receiving payments API docs

Once the SDK is initialized, you can directly begin receiving payments. The SDK currently supports three methods of receiving: Lightning, Bitcoin and Spark.

Lightning

BOLT11 invoice

When receiving via Lightning, we can generate a BOLT11 invoice to be paid. Setting the invoice amount fixes the amount the sender should pay.

Note: the payment may fallback to a direct Spark payment (if the payer's client supports this).

Rust

let description = "<invoice description>".to_string();
// Optionally set the invoice amount you wish the payer to send
let optional_amount_sats = Some(5_000);

let response = sdk
    .receive_payment(ReceivePaymentRequest {
        payment_method: ReceivePaymentMethod::Bolt11Invoice {
            description,
            amount_sats: optional_amount_sats,
        },
    })
    .await?;

let payment_request = response.payment_request;
info!("Payment request: {payment_request}");
let receive_fee_sats = response.fee_sats;
info!("Fees: {receive_fee_sats} sats");

Swift

let description = "<invoice description>"
// Optionally set the invoice amount you wish the payer to send
let optionalAmountSats: UInt64 = 5_000
let response = try await sdk
    .receivePayment(request: ReceivePaymentRequest(
        paymentMethod: ReceivePaymentMethod.bolt11Invoice(
            description: description,
            amountSats: optionalAmountSats
        )
    ));

let paymentRequest = response.paymentRequest;
print("Payment Request: {}", paymentRequest);
let receiveFeeSats = response.feeSats;
print("Fees: {} sats", receiveFeeSats);

Kotlin

try {
    val description = "<invoice description>"
    // Optionally set the invoice amount you wish the payer to send
    val optionalAmountSats = 5_000.toULong()

    val request = ReceivePaymentRequest(
        ReceivePaymentMethod.Bolt11Invoice(description, optionalAmountSats)
    )
    val response = sdk.receivePayment(request)

    val paymentRequest = response.paymentRequest
    // Log.v("Breez", "Payment Request: ${paymentRequest}")
    val receiveFeeSats = response.feeSats
    // Log.v("Breez", "Fees: ${receiveFeeSats} sats")
} catch (e: Exception) {
    // handle error
}

Javascript

const description = '<invoice description>'
// Optionally set the invoice amount you wish the payer to send
const optionalAmountSats = 5_000

const response = await sdk.receivePayment({
  paymentMethod: {
    type: 'bolt11Invoice',
    description,
    amountSats: optionalAmountSats
  }
})

const paymentRequest = response.paymentRequest
console.log(`Payment Request: ${paymentRequest}`)
const receiveFeeSats = response.feeSats
console.log(`Fees: ${receiveFeeSats} sats`)

React Native

const description = '<invoice description>'
// Optionally set the invoice amount you wish the payer to send
const optionalAmountSats = BigInt(5_000)

const response = await sdk.receivePayment({
  paymentMethod: new ReceivePaymentMethod.Bolt11Invoice({
    description,
    amountSats: optionalAmountSats
  })
})

const paymentRequest = response.paymentRequest
console.log(`Payment Request: ${paymentRequest}`)
const receiveFeeSats = response.feeSats
console.log(`Fees: ${receiveFeeSats} sats`)

Flutter

String description = "<invoice description>";
// Optionally set the invoice amount you wish the payer to send
BigInt optionalAmountSats = BigInt.from(5000);

// Create an invoice and set the amount you wish the payer to send
ReceivePaymentRequest request = ReceivePaymentRequest(
    paymentMethod: ReceivePaymentMethod.bolt11Invoice(
        description: description, amountSats: optionalAmountSats));
ReceivePaymentResponse response = await sdk.receivePayment(
  request: request,
);

String paymentRequest = response.paymentRequest;
print("Payment request: $paymentRequest");
BigInt receiveFeeSats = response.feeSats;
print("Fees: $receiveFeeSats sats");

Python

try:
    description = "<invoice description>"
    # Optionally set the invoice amount you wish the payer to send
    optional_amount_sats = 5_000
    payment_method = ReceivePaymentMethod.BOLT11_INVOICE(
        description=description, amount_sats=optional_amount_sats
    )
    request = ReceivePaymentRequest(payment_method=payment_method)
    response = await sdk.receive_payment(request=request)

    payment_request = response.payment_request
    logging.debug(f"Payment Request: {payment_request}")
    receive_fee_sats = response.fee_sats
    logging.debug(f"Fees: {receive_fee_sats} sats")
    return response
except Exception as error:
    logging.error(error)
    raise

description := "<invoice description>"
// Optionally set the invoice amount you wish the payer to send
optionalAmountSats := uint64(5_000)

request := breez_sdk_spark.ReceivePaymentRequest{
    PaymentMethod: breez_sdk_spark.ReceivePaymentMethodBolt11Invoice{
        Description: description,
        AmountSats:  &optionalAmountSats,
    },
}

response, err := sdk.ReceivePayment(request)

if sdkErr := err.(*breez_sdk_spark.SdkError); sdkErr != nil {
    return nil, err
}

paymentRequest := response.PaymentRequest
log.Printf("Payment Request: %v", paymentRequest)
receiveFeesSat := response.FeeSats
log.Printf("Fees: %v sats", receiveFeesSat)

LNURL-Pay & Lightning address

To receive via LNURL-Pay and/or a Lightning address, follow these instructions.

Note: Lightning payments work in Spark even if the receiver is offline. To understand how it works under the hood, read this.

For onchain payments you can use the static Bitcoin address to receive payments. The SDK monitors the specified address for new UTXOs and automatically initiates the claim process when funds are detected.

Rust

let response = sdk
    .receive_payment(ReceivePaymentRequest {
        payment_method: ReceivePaymentMethod::BitcoinAddress,
    })
    .await?;

let payment_request = response.payment_request;
info!("Payment request: {payment_request}");
let receive_fee_sats = response.fee_sats;
info!("Fees: {receive_fee_sats} sats");

Swift

let response = try await sdk
    .receivePayment(request: ReceivePaymentRequest(
        paymentMethod: ReceivePaymentMethod.bitcoinAddress
    ));

let paymentRequest = response.paymentRequest;
print("Payment Request: {}", paymentRequest);
let receiveFeeSats = response.feeSats;
print("Fees: {} sats", receiveFeeSats);

Kotlin

try {
    val request = ReceivePaymentRequest(
        ReceivePaymentMethod.BitcoinAddress
    )
    val response = sdk.receivePayment(request)

    val paymentRequest = response.paymentRequest
    // Log.v("Breez", "Payment Request: ${paymentRequest}")
    val receiveFeeSats = response.feeSats
    // Log.v("Breez", "Fees: ${receiveFeeSats} sats")
} catch (e: Exception) {
    // handle error
}

Javascript

const response = await sdk.receivePayment({
  paymentMethod: { type: 'bitcoinAddress' }
})

const paymentRequest = response.paymentRequest
console.log(`Payment Request: ${paymentRequest}`)
const receiveFeeSats = response.feeSats
console.log(`Fees: ${receiveFeeSats} sats`)

React Native

const response = await sdk.receivePayment({
  paymentMethod: new ReceivePaymentMethod.BitcoinAddress()
})

const paymentRequest = response.paymentRequest
console.log(`Payment Request: ${paymentRequest}`)
const receiveFeeSats = response.feeSats
console.log(`Fees: ${receiveFeeSats} sats`)

Flutter

ReceivePaymentRequest request = ReceivePaymentRequest(
    paymentMethod: ReceivePaymentMethod.bitcoinAddress());
ReceivePaymentResponse response = await sdk.receivePayment(
  request: request,
);

String paymentRequest = response.paymentRequest;
print("Payment request: $paymentRequest");
BigInt receiveFeeSats = response.feeSats;
print("Fees: $receiveFeeSats sats");

Python

try:
    request = ReceivePaymentRequest(
        payment_method=ReceivePaymentMethod.BITCOIN_ADDRESS
    )
    response = await sdk.receive_payment(request=request)

    payment_request = response.payment_request
    logging.debug(f"Payment Request: {payment_request}")
    receive_fee_sats = response.fee_sats
    logging.debug(f"Fees: {receive_fee_sats} sats")
    return response
except Exception as error:
    logging.error(error)
    raise

request := breez_sdk_spark.ReceivePaymentRequest{
    PaymentMethod: breez_sdk_spark.ReceivePaymentMethodBitcoinAddress{},
}

response, err := sdk.ReceivePayment(request)

if sdkErr := err.(*breez_sdk_spark.SdkError); sdkErr != nil {
    return nil, err
}

paymentRequest := response.PaymentRequest
log.Printf("Payment Request: %v", paymentRequest)
receiveFeesSat := response.FeeSats
log.Printf("Fees: %v sats", receiveFeesSat)

Spark

For payments between Spark users, you can use the static Spark address to receive payments.

Rust

let response = sdk
    .receive_payment(ReceivePaymentRequest {
        payment_method: ReceivePaymentMethod::SparkAddress,
    })
    .await?;

let payment_request = response.payment_request;
info!("Payment request: {payment_request}");
let receive_fee_sats = response.fee_sats;
info!("Fees: {receive_fee_sats} sats");

Swift

let response = try await sdk
    .receivePayment(request: ReceivePaymentRequest(
        paymentMethod: ReceivePaymentMethod.sparkAddress
    ));

let paymentRequest = response.paymentRequest;
print("Payment Request: {}", paymentRequest);
let receiveFeeSats = response.feeSats;
print("Fees: {} sats", receiveFeeSats);

Kotlin

try {
    val request = ReceivePaymentRequest(
        ReceivePaymentMethod.SparkAddress
    );
    val response = sdk.receivePayment(request)

    val paymentRequest = response.paymentRequest
    // Log.v("Breez", "Payment Request: ${paymentRequest}")
    val receiveFeeSats = response.feeSats
    // Log.v("Breez", "Fees: ${receiveFeeSats} sats")
} catch (e: Exception) {
    // handle error
}

Javascript

const response = await sdk.receivePayment({
  paymentMethod: { type: 'sparkAddress' }
})

const paymentRequest = response.paymentRequest
console.log(`Payment Request: ${paymentRequest}`)
const receiveFeeSats = response.feeSats
console.log(`Fees: ${receiveFeeSats} sats`)

React Native

const response = await sdk.receivePayment({
  paymentMethod: new ReceivePaymentMethod.SparkAddress()
})

const paymentRequest = response.paymentRequest
console.log(`Payment Request: ${paymentRequest}`)
const receiveFeeSats = response.feeSats
console.log(`Fees: ${receiveFeeSats} sats`)

Flutter

ReceivePaymentRequest request =
    ReceivePaymentRequest(paymentMethod: ReceivePaymentMethod.sparkAddress());
ReceivePaymentResponse response = await sdk.receivePayment(
  request: request,
);

String paymentRequest = response.paymentRequest;
print("Payment request: $paymentRequest");
BigInt receiveFeeSats = response.feeSats;
print("Fees: $receiveFeeSats sats");

Python

try:
    request = ReceivePaymentRequest(
        payment_method=ReceivePaymentMethod.SPARK_ADDRESS
    )
    response = await sdk.receive_payment(request=request)

    payment_request = response.payment_request
    logging.debug(f"Payment Request: {payment_request}")
    receive_fee_sats = response.fee_sats
    logging.debug(f"Fees: {receive_fee_sats} sats")
    return response
except Exception as error:
    logging.error(error)
    raise

request := breez_sdk_spark.ReceivePaymentRequest{
    PaymentMethod: breez_sdk_spark.ReceivePaymentMethodSparkAddress{},
}

response, err := sdk.ReceivePayment(request)

if sdkErr := err.(*breez_sdk_spark.SdkError); sdkErr != nil {
    return nil, err
}

paymentRequest := response.PaymentRequest
log.Printf("Payment Request: %v", paymentRequest)
receiveFeesSat := response.FeeSats
log.Printf("Fees: %v sats", receiveFeesSat)

Event Flows

Once a receive 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.

Event	Description	UX Suggestion
Synced	The SDK has synced payments in the background.	Update the payments list and balance. See listing payments and fetching the balance.

Lightning

Event	Description	UX Suggestion
PaymentSucceeded	The Spark transfer is claimed and the payment is complete.	Update the balance and show payment as complete.

Bitcoin

Event	Description	UX Suggestion
ClaimDepositsFailed	The SDK attempted to claim static address deposits but they failed from one of several reasons. Either the claim fee exceeded the maximum allowed limit or there was an issue finding the available UTXO.	Allow the user to refund these failed deposits. See Refunding payments.
ClaimDepositsSucceeded	The SDK successfully claimed static address deposits.
PaymentSucceeded	The Spark transfer is claimed and the payment is complete.	Update the balance and show payment as complete.

Spark

Event	Description	UX Suggestion
PaymentSucceeded	The Spark transfer is claimed and the payment is complete.	Update the balance and show payment as complete.

Keyboard shortcuts

Breez SDK - Nodeless (Spark)