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

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;
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.fee
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.fee
    // Log.v("Breez", "Fees: ${receiveFeeSats} sats")
} catch (e: Exception) {
    // handle error
}
C#
var description = "<invoice description>";
// Optionally set the invoice amount you wish the payer to send
var optionalAmountSats = 5_000UL;
var paymentMethod = new ReceivePaymentMethod.Bolt11Invoice(
    description: description,
    amountSats: optionalAmountSats
);
var request = new ReceivePaymentRequest(paymentMethod: paymentMethod);
var response = await sdk.ReceivePayment(request: request);

var paymentRequest = response.paymentRequest;
Console.WriteLine($"Payment Request: {paymentRequest}");
var receiveFeeSats = response.fee;
Console.WriteLine($"Fees: {receiveFeeSats} sats");
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.fee
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.fee
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.fee;
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
    logging.debug(f"Fees: {receive_fee_sats} sats")
    return response
except Exception as error:
    logging.error(error)
    raise
Go
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.Fee
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.

Bitcoin

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. If the Config's maximum deposit claim fee is not set or below the current Spark fee to claim the Bitcoin deposit, the deposit will need to be claimed or refunded manually. See Handling unclaimed deposits for more details on this process.

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;
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.fee
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.fee
    // Log.v("Breez", "Fees: ${receiveFeeSats} sats")
} catch (e: Exception) {
    // handle error
}
C#
var request = new ReceivePaymentRequest(
    paymentMethod: new ReceivePaymentMethod.BitcoinAddress()
);
var response = await sdk.ReceivePayment(request: request);

var paymentRequest = response.paymentRequest;
Console.WriteLine($"Payment Request: {paymentRequest}");
var receiveFeeSats = response.fee;
Console.WriteLine($"Fees: {receiveFeeSats} sats");
Javascript
const response = await sdk.receivePayment({
  paymentMethod: { type: 'bitcoinAddress' }
})

const paymentRequest = response.paymentRequest
console.log(`Payment Request: ${paymentRequest}`)
const receiveFeeSats = response.fee
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.fee
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.fee;
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
    logging.debug(f"Fees: {receive_fee_sats} sats")
    return response
except Exception as error:
    logging.error(error)
    raise
Go
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.Fee
log.Printf("Fees: %v sats", receiveFeesSat)

Spark

For payments between Spark users, you can use a Spark address or generate a Spark invoice to receive payments.

Spark address

Spark addresses are static.

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;
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.fee
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.fee
    // Log.v("Breez", "Fees: ${receiveFeeSats} sats")
} catch (e: Exception) {
    // handle error
}
C#
var request = new ReceivePaymentRequest(
    paymentMethod: new ReceivePaymentMethod.SparkAddress()
);
var response = await sdk.ReceivePayment(request: request);

var paymentRequest = response.paymentRequest;
Console.WriteLine($"Payment Request: {paymentRequest}");
var receiveFeeSats = response.fee;
Console.WriteLine($"Fees: {receiveFeeSats} sats");
Javascript
const response = await sdk.receivePayment({
  paymentMethod: { type: 'sparkAddress' }
})

const paymentRequest = response.paymentRequest
console.log(`Payment Request: ${paymentRequest}`)
const receiveFeeSats = response.fee
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.fee
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.fee;
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
    logging.debug(f"Fees: {receive_fee_sats} sats")
    return response
except Exception as error:
    logging.error(error)
    raise
Go
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.Fee
log.Printf("Fees: %v sats", receiveFeesSat)

Spark invoice

Spark invoices are single-use and may impose restrictions on the payment, such as amount, expiry, and who is able to pay it.

Rust
let optional_description = "<invoice description>".to_string();
let optional_amount_sats = Some(5_000);
let optional_expiry_time_seconds = Some(1716691200);
let optional_sender_public_key = Some("<sender public key>".to_string());

let response = sdk
    .receive_payment(ReceivePaymentRequest {
        payment_method: ReceivePaymentMethod::SparkInvoice {
            token_identifier: None,
            description: Some(optional_description),
            amount: optional_amount_sats,
            expiry_time: optional_expiry_time_seconds,
            sender_public_key: optional_sender_public_key,
        },
    })
    .await?;

let payment_request = response.payment_request;
info!("Payment request: {payment_request}");
let receive_fee_sats = response.fee;
info!("Fees: {receive_fee_sats} sats");
Swift
let optionalDescription = "<invoice description>"
let optionalAmountSats = BInt(5_000)
let optionalExpiryTimeSeconds: UInt64 = 1_716_691_200
let optionalSenderPublicKey = "<sender public key>"

let response =
    try await sdk
    .receivePayment(
        request: ReceivePaymentRequest(
            paymentMethod: ReceivePaymentMethod.sparkInvoice(
                amount: optionalAmountSats,
                tokenIdentifier: nil,
                expiryTime: optionalExpiryTimeSeconds,
                description: optionalDescription,
                senderPublicKey: optionalSenderPublicKey
            )
        ))

let paymentRequest = response.paymentRequest
print("Payment Request: {}", paymentRequest)
let receiveFeeSats = response.fee
print("Fees: {} sats", receiveFeeSats)
Kotlin
try {
    val optionalDescription = "<invoice description>"
    // Kotlin MPP (BigInteger from com.ionspin.kotlin.bignum.integer, which is included in
    // package)
    val optionalAmountSats = BigInteger.fromLong(5_000L)
    // Android (BigInteger from java.math)
    // val optionalAmountSats = BigInteger.valueOf(5_000L)
    val optionalExpiryTimeSeconds = 1716691200.toULong()
    val optionalSenderPublicKey = "<sender public key>"

    val request = ReceivePaymentRequest(
        ReceivePaymentMethod.SparkInvoice(
            tokenIdentifier = null,
            description = optionalDescription,
            amount = optionalAmountSats,
            expiryTime = optionalExpiryTimeSeconds,
            senderPublicKey = optionalSenderPublicKey
        )
    )
    val response = sdk.receivePayment(request)

    val paymentRequest = response.paymentRequest
    // Log.v("Breez", "Payment Request: ${paymentRequest}")
    val receiveFeeSats = response.fee
    // Log.v("Breez", "Fees: ${receiveFeeSats} sats")
} catch (e: Exception) {
    // handle error
}
C#
var optionalDescription = "<invoice description>";
var optionalAmountSats = new BigInteger(5000);
var optionalExpiryTimeSeconds = 1716691200UL;
var optionalSenderPublicKey = "<sender public key>";

var request = new ReceivePaymentRequest(
    paymentMethod: new ReceivePaymentMethod.SparkInvoice(
        description: optionalDescription,
        amount: optionalAmountSats,
        expiryTime: optionalExpiryTimeSeconds,
        senderPublicKey: optionalSenderPublicKey,
        tokenIdentifier: null
    )
);
var response = await sdk.ReceivePayment(request: request);

var paymentRequest = response.paymentRequest;
Console.WriteLine($"Payment Request: {paymentRequest}");
var receiveFeeSats = response.fee;
Console.WriteLine($"Fees: {receiveFeeSats} sats");
Javascript
const optionalDescription = '<invoice description>'
const optionalAmountSats = BigInt(5_000)
const optionalExpiryTimeSeconds = 1716691200
const optionalSenderPublicKey = '<sender public key>'

const response = await sdk.receivePayment({
  paymentMethod: {
    type: 'sparkInvoice',
    description: optionalDescription,
    amount: optionalAmountSats,
    expiryTime: optionalExpiryTimeSeconds,
    senderPublicKey: optionalSenderPublicKey
  }
})

const paymentRequest = response.paymentRequest
console.log(`Payment Request: ${paymentRequest}`)
const receiveFeeSats = response.fee
console.log(`Fees: ${receiveFeeSats} sats`)
React Native
const optionalDescription = '<invoice description>'
const optionalAmountSats = BigInt(5_000)
const optionalExpiryTimeSeconds = BigInt(1716691200)
const optionalSenderPublicKey = '<sender public key>'

const response = await sdk.receivePayment({
  paymentMethod: new ReceivePaymentMethod.SparkInvoice({
    description: optionalDescription,
    amount: optionalAmountSats,
    expiryTime: optionalExpiryTimeSeconds,
    senderPublicKey: optionalSenderPublicKey,
    tokenIdentifier: undefined
  })
})

const paymentRequest = response.paymentRequest
console.log(`Payment Request: ${paymentRequest}`)
const receiveFeeSats = response.fee
console.log(`Fees: ${receiveFeeSats} sats`)
Flutter
String optionalDescription = "<invoice description>";
BigInt optionalAmountSats = BigInt.from(5000);
BigInt optionalExpiryTimeSeconds = BigInt.from(1716691200);
String optionalSenderPublicKey = "<sender public key>";

ReceivePaymentRequest request =
    ReceivePaymentRequest(paymentMethod: ReceivePaymentMethod.sparkInvoice(
      description: optionalDescription,
      amount: optionalAmountSats,
      expiryTime: optionalExpiryTimeSeconds,
      senderPublicKey: optionalSenderPublicKey,
    ));
ReceivePaymentResponse response = await sdk.receivePayment(
  request: request,
);

String paymentRequest = response.paymentRequest;
print("Payment request: $paymentRequest");
BigInt receiveFeeSats = response.fee;
print("Fees: $receiveFeeSats sats");
Python
try:
    optional_description = "<invoice description>"
    optional_amount_sats = 5_000
    optional_expiry_time_seconds = 1716691200
    optional_sender_public_key = "<sender public key>"

    request = ReceivePaymentRequest(
        payment_method=ReceivePaymentMethod.SPARK_INVOICE(
            description=optional_description,
            amount=optional_amount_sats,
            expiry_time=optional_expiry_time_seconds,
            sender_public_key=optional_sender_public_key,
            token_identifier=None,
        )
    )
    response = await sdk.receive_payment(request=request)

    payment_request = response.payment_request
    logging.debug(f"Payment Request: {payment_request}")
    receive_fee_sats = response.fee
    logging.debug(f"Fees: {receive_fee_sats} sats")
    return response
except Exception as error:
    logging.error(error)
    raise
Go
optionalDescription := "<invoice description>"
optionalAmountSats := new(big.Int).SetInt64(5_000)
optionalExpiryTimeSeconds := uint64(1716691200)
optionalSenderPublicKey := "<sender public key>"

request := breez_sdk_spark.ReceivePaymentRequest{
	PaymentMethod: breez_sdk_spark.ReceivePaymentMethodSparkInvoice{
		Description:     &optionalDescription,
		Amount:          &optionalAmountSats,
		ExpiryTime:      &optionalExpiryTimeSeconds,
		SenderPublicKey: &optionalSenderPublicKey,
	},
}

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.Fee
log.Printf("Fees: %v sats", receiveFeesSat)

Waiting for a payment

It is generally recommended to use event flows to react to payment completion. However, there is a convenience function to wait for payment completion.

Rust
// Waiting for a payment given its payment request (Bolt11 or Spark invoice)
let payment_request = "<Bolt11 or Spark invoice>".to_string();

// Wait for a payment to be completed using a payment request
let payment_request_response = sdk
    .wait_for_payment(WaitForPaymentRequest {
        identifier: WaitForPaymentIdentifier::PaymentRequest(payment_request),
    })
    .await?;

info!("Payment received with ID: {}", payment_request_response.payment.id);

// Waiting for a payment given its payment id
let payment_id = "<payment id>".to_string();

// Wait for a payment to be completed using a payment id
let payment_id_response = sdk
    .wait_for_payment(WaitForPaymentRequest {
        identifier: WaitForPaymentIdentifier::PaymentId(payment_id),
    })
    .await?;

info!("Payment received with ID: {}", payment_id_response.payment.id);
Swift
// Waiting for a payment given its payment request (Bolt11 or Spark invoice)
let paymentRequest = "<Bolt11 or Spark invoice>"

// Wait for a payment to be completed using a payment request
let paymentRequestResponse = try await sdk.waitForPayment(
    request: WaitForPaymentRequest(
        identifier: WaitForPaymentIdentifier.paymentRequest(paymentRequest)
    )
)

print("Payment received with ID: \(paymentRequestResponse.payment.id)")

// Waiting for a payment given its payment id
let paymentId = "<payment id>"

// Wait for a payment to be completed using a payment id
let paymentIdResponse = try await sdk.waitForPayment(
    request: WaitForPaymentRequest(
        identifier: WaitForPaymentIdentifier.paymentId(paymentId)
    )
)

print("Payment received with ID: \(paymentIdResponse.payment.id)")
Kotlin
try {
    // Waiting for a payment given its payment request (Bolt11 or Spark invoice)
    val paymentRequest = "<Bolt11 or Spark invoice>"

    // Wait for a payment to be completed using a payment request
    val paymentRequestResponse = sdk.waitForPayment(
        WaitForPaymentRequest(
            WaitForPaymentIdentifier.PaymentRequest(paymentRequest)
        )
    )

    // Log.v("Breez", "Payment received with ID: ${paymentRequestResponse.payment.id}")

    // Waiting for a payment given its payment id
    val paymentId = "<payment id>"

    // Wait for a payment to be completed using a payment id
    val paymentIdResponse = sdk.waitForPayment(
        WaitForPaymentRequest(
            WaitForPaymentIdentifier.PaymentId(paymentId)
        )
    )

    // Log.v("Breez", "Payment received with ID: ${paymentIdResponse.payment.id}")
} catch (e: Exception) {
    // handle error
}
C#
// Waiting for a payment given its payment request (Bolt11 or Spark invoice)
var paymentRequest = "<Bolt11 or Spark invoice>";

// Wait for a payment to be completed using a payment request
var paymentRequestResponse = await sdk.WaitForPayment(
    request: new WaitForPaymentRequest(
        identifier: new WaitForPaymentIdentifier.PaymentRequest(v1: paymentRequest)
    )
);

Console.WriteLine($"Payment received with ID: {paymentRequestResponse.payment.id}");

// Waiting for a payment given its payment id
var paymentId = "<payment id>";

// Wait for a payment to be completed using a payment id
var paymentIdResponse = await sdk.WaitForPayment(
    request: new WaitForPaymentRequest(
        identifier: new WaitForPaymentIdentifier.PaymentId(v1: paymentId)
    )
);

Console.WriteLine($"Payment received with ID: {paymentIdResponse.payment.id}");
Javascript
// Waiting for a payment given its payment request (Bolt11 or Spark invoice)
const paymentRequest = '<Bolt11 or Spark invoice>'

// Wait for a payment to be completed using a payment request
const paymentRequestResponse = await sdk.waitForPayment({
  identifier: paymentRequest as { type: 'paymentRequest' } & string
})

console.log(`Payment received with ID: ${paymentRequestResponse.payment.id}`)

// Waiting for a payment given its payment id
const paymentId = '<payment id>'

// Wait for a payment to be completed using a payment id
const paymentIdResponse = await sdk.waitForPayment({
  identifier: paymentId as { type: 'paymentId' } & string
})

console.log(`Payment received with ID: ${paymentIdResponse.payment.id}`)
React Native
// Waiting for a payment given its payment request (Bolt11 or Spark invoice)
const paymentRequest = '<Bolt11 or Spark invoice>'

// Wait for a payment to be completed using a payment request
const paymentRequestResponse = await sdk.waitForPayment({
  identifier: new WaitForPaymentIdentifier.PaymentRequest(paymentRequest)
})

console.log(`Payment received with ID: ${paymentRequestResponse.payment.id}`)

// Waiting for a payment given its payment id
const paymentId = '<payment id>'

// Wait for a payment to be completed using a payment id
const paymentIdResponse = await sdk.waitForPayment({
  identifier: new WaitForPaymentIdentifier.PaymentId(paymentId)
})

console.log(`Payment received with ID: ${paymentIdResponse.payment.id}`)
Flutter
// Waiting for a payment given its payment request (Bolt11 or Spark invoice)
String paymentRequest = "<Bolt11 or Spark invoice>"; 

// Wait for a payment to be completed using a payment request
WaitForPaymentResponse paymentRequestResponse = await sdk.waitForPayment(
  request: WaitForPaymentRequest(
    identifier: WaitForPaymentIdentifier.paymentRequest(paymentRequest),
  ),
);
print("Payment received with ID: ${paymentRequestResponse.payment.id}");

// Waiting for a payment given its payment id
String paymentId = "<payment id>";

// Wait for a payment to be completed using a payment request
WaitForPaymentResponse paymentIdResponse = await sdk.waitForPayment(
  request: WaitForPaymentRequest(
    identifier: WaitForPaymentIdentifier.paymentId(paymentId),
  ),
);

print("Payment received with ID: ${paymentIdResponse.payment.id}");
Python
try:
    # Waiting for a payment given its payment request (Bolt11 or Spark invoice)
    payment_request = "<Bolt11 or Spark invoice>"

    # Wait for a payment to be completed using a payment request
    payment_request_response = await sdk.wait_for_payment(
        request=WaitForPaymentRequest(
            identifier=WaitForPaymentIdentifier.PAYMENT_REQUEST(payment_request)
        )
    )

    logging.debug(f"Payment received with ID: {payment_request_response.payment.id}")

    # Waiting for a payment given its payment id
    payment_id = "<payment id>"

    # Wait for a payment to be completed using a payment id
    payment_id_response = await sdk.wait_for_payment(
        request=WaitForPaymentRequest(
            identifier=WaitForPaymentIdentifier.PAYMENT_ID(payment_id)
        )
    )

    logging.debug(f"Payment received with ID: {payment_id_response.payment.id}")
except Exception as error:
    logging.error(error)
    raise
Go
// Waiting for a payment given its payment request (Bolt11 or Spark invoice)
paymentRequest := "<Bolt11 or Spark invoice>"

// Wait for a payment to be completed using a payment request
paymentRequestResponse, err := sdk.WaitForPayment(breez_sdk_spark.WaitForPaymentRequest{
	Identifier: breez_sdk_spark.WaitForPaymentIdentifierPaymentRequest{
		Field0: paymentRequest,
	},
})

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

log.Printf("Payment received with ID: %v", paymentRequestResponse.Payment.Id)

// Waiting for a payment given its payment id
paymentId := "<payment id>"

// Wait for a payment to be completed using a payment id
paymentIdResponse, err := sdk.WaitForPayment(breez_sdk_spark.WaitForPaymentRequest{
	Identifier: breez_sdk_spark.WaitForPaymentIdentifierPaymentId{
		Field0: paymentId,
	},
})

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

log.Printf("Payment received with ID: %v", paymentIdResponse.Payment.Id)

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.

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 was detected and the claim process will start.Show payment as pending.
PaymentSucceededThe Spark transfer is claimed and the payment is complete.Update the balance and show payment as complete.

Bitcoin

EventDescriptionUX Suggestion
UnclaimedDepositsThe 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 Handling unclaimed deposits.
ClaimedDepositsThe SDK successfully claimed static address deposits.
PaymentPendingThe Spark transfer was detected and the claim process will start.Show payment as pending.
PaymentSucceededThe Spark transfer is claimed and the payment is complete.Update the balance and show payment as complete.

Spark

EventDescriptionUX Suggestion
PaymentPendingThe Spark transfer was detected and the claim process will start.Show payment as pending.
PaymentSucceededThe Spark transfer is claimed and the payment is complete.Update the balance and show payment as complete.