xpay -- Command for sending a payment

SYNOPSIS

xpay invstring [amount_msat] [maxfee] [layers] [retry_for] [partial_msat] [maxdelay] [payer_note] [label] [localinvreqid]

DESCRIPTION

Command added in v24.11.

The xpay RPC command attempts to make the specified payment: it can look up BIP353 names (such as ₿[email protected]), it can resolve simple offers (lno1...), and pay bolt11 (lnbc...) and bolt12 invoices (lni1...).

This plugin is both simpler and more sophisticated than the older 'pay' plugin.

• invstring (string): bolt11 or bolt12 invoice, a bolt12 (non-recursive) offer or a BIP353 name. If it's a bip353 name, an offer is fetched with fetchbip353 if available. If it's an offer, the invoice is fetched using fetchinvoice automatically.
• amount_msat (msat, optional): Only possible for a bolt11 invoice which does not have an amount (in which case, it's compulsory). amount_msat is in millisatoshi precision; it can be a whole number, or a whole number with suffix msat or sat, or a three decimal point number with suffix sat, or an 1 to 11 decimal point number suffixed by btc.
• maxfee (msat, optional): maxfee creates an absolute limit on what fee we will pay. The default is 5000msat, or 1% (whatever is greater).
• layers (array of strings, optional): These are askrene layers to apply in addition to xpay's own: these can alter the topology or provide additional information on the lightning network. This lets you exclude particular nodes or channels, or bias against them: see askrene-create-layer.:
  • (string, optional): name of an existing layer
• retry_for (u32, optional): Until retry_for seconds passes, the command will keep finding routes and retrying the payment. The default is 60 seconds.
• partial_msat (msat, optional): Explicitly state that you are only paying some part of the invoice. Presumably someone else is paying the rest (otherwise the payment will time out at the recipient).
• maxdelay (u32, optional): A payment may be delayed for up to maxdelay blocks by another node; clients should be prepared for this worst case. The default is 2016. (added v25.02)
• payer_note (string, optional): A message that a payer is willing to send to a payee within an invoice request. (added v26.04)
• label (string, optional): Attach a label to payments for which is returned in listpays and listsendpays. This is for your own use: it is not visible to the recipient. (added v26.06)
• localinvreqid (hex, optional): localinvreqid is used by offers to link a payment attempt to a local invoice_request offer created by lightningd-invoicerequest(7). This ensures that we only make a single payment for an offer, and that the offer is marked used once paid. (added v26.06)

RETURN VALUE

On success, an object is returned, containing:

• payment_preimage (secret): The proof of payment: SHA256 of this payment_hash.
• failed_parts (u64): How many separate payment parts failed.
• successful_parts (u64): How many separate payment parts succeeded (or are anticipated to succeed). This will be at least one.
• amount_msat (msat): Amount the recipient received.
• amount_sent_msat (msat): Total amount we sent (including fees).

ERRORS

The following error codes may occur:

• -1: Catchall nonspecific error.
• 203: Permanent failure from destination (e.g. it said it didn't recognize invoice)
• 205: Couldn't find, or find a way to, the destination.
• 207: Invoice has expired.
• 219: Invoice has already been paid.
• 209: Other payment error.

AUTHOR

Rusty Russell [email protected] is mainly responsible.

SEE ALSO

lightning-listpays(7), lightning-decode(7)

RESOURCES

Main web site: https://github.com/ElementsProject/lightning

EXAMPLES

Example 1:

Request:

lightning-cli xpay "lnbcrt100n1pnt2bolt11invl040100000000bolt11invl040100000000bolt11invl040100000000bolt11invl040100000000bolt11invl040100000000bolt11invl040100000000bolt11invl040100000000bolt11invl040100000000bolt11invl040100000000bolt11invl040100000000"

{
  "id": "example:xpay#1",
  "method": "xpay",
  "params": [
    "lnbcrt100n1pnt2bolt11invl040100000000bolt11invl040100000000bolt11invl040100000000bolt11invl040100000000bolt11invl040100000000bolt11invl040100000000bolt11invl040100000000bolt11invl040100000000bolt11invl040100000000bolt11invl040100000000"
  ]
}

Response:

{
  "payment_preimage": "paymentpreimgxp1010101010101010101010101010101010101010101010101",
  "amount_msat": 10000,
  "amount_sent_msat": 10002,
  "failed_parts": 0,
  "successful_parts": 1
}

Example 2:

Request:

lightning-cli xpay -k "invstring"="lni1qqg0qe03030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303" "payer_note"="Coffee payment"

{
  "id": "example:xpay#2",
  "method": "xpay",
  "params": {
    "invstring": "lni1qqg0qe03030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303",
    "payer_note": "Coffee payment"
  }
}

Response:

{
  "payment_preimage": "paymentpreimgxp2020202020202020202020202020202020202020202020202",
  "amount_msat": 1000,
  "amount_sent_msat": 1000,
  "failed_parts": 0,
  "successful_parts": 1
}