home | help 
LIGHTNING-WAITSENDPAY(7)				LIGHTNING-WAITSENDPAY(7)

NAME
     waitsendpay -- Command for sending a payment via a route

SYNOPSIS
     waitsendpay payment_hash [timeout] [partid groupid]

DESCRIPTION
     The  waitsendpay  RPC  command polls or waits for the status of an outgoing
     payment that was initiated by a previous sendpay invocation.

     If the payment completed with success, this command returns  with	success.
     Otherwise,  if  the payment completed with failure, this command returns an
     error.

     *	payment_hash (hash): The hash of the payment_preimage.
     *	timeout (u32, optional): A timeout in seconds, for this RPC  command  to
	return.  If  the timeout is provided and the given amount of time passes
	without the payment definitely succeeding or  definitely  failing,  this
	command  returns  with	a 200 error code (payment still in progress). If
	timeout is not provided this call will wait indefinitely.  Indicating  a
	timeout  of 0 effectively makes this call a pollable query of the status
	of the payment.
     *	partid (u64, optional): Unique ID within this (multi-part)  payment.  It
	must match that of the sendpay command.
     *	groupid  (u64, optional): Grouping key to disambiguate multiple attempts
	to pay the same payment_hash.

RETURN VALUE
     On success, an object is returned, containing:

     *	created_index (u64): 1-based index indicating  order  this  payment  was
	created in. (added v23.11)
     *	id (u64): Old synonym for created_index.
     *	payment_hash  (hash):  The hash of the payment_preimage which will prove
	payment.
     *	status (string) (always "complete"): Status of the payment.
     *	created_at (u64): The UNIX timestamp showing when this payment was  ini-
	tiated.
     *	amount_sent_msat (msat): The amount sent.
     *	groupid  (u64, optional): Grouping key to disambiguate multiple attempts
	to pay an invoice or the same payment_hash.
     *	amount_msat (msat, optional): The amount delivered  to	destination  (if
	known).
     *	destination  (pubkey, optional): The final destination of the payment if
	known.
     *	updated_index (u64, optional): 1-based index indicating order this  pay-
	ment was changed (only present if it has changed since creation). (added
	v23.11)
     *	completed_at  (number,	optional):  The UNIX timestamp showing when this
	payment was completed.
     *	label (string, optional): The label, if given to sendpay.
     *	partid (u64, optional): The partid, if given to sendpay.
     *	bolt11 (string, optional): The bolt11 string (if pay supplied one).
     *	bolt12 (string, optional): The bolt12 string (if supplied for pay).

     If status is "complete": - payment_preimage (secret): The proof of payment:
     SHA256 of this payment_hash.

ERRORS
     On error, and even if the error occurred from a node other than  the  final
     destination, the route table will no longer be updated. Use the exclude pa-
     rameter of the getroute command to ignore the failing route.

     *	-1: Catchall nonspecific error.
     *	200: Timed out before the payment could complete.
     *	202:  Unparseable  onion reply. The data field of the error will have an
	onionreply field, a hex string representation of the raw onion reply.
     *	203: Permanent failure at destination. The data field of the error  will
	be routing failure object.
     *	204: Failure along route; retry a different route. The data field of the
	error will be routing failure object.
     *	208:  A  payment for payment_hash was never made and there is nothing to
	wait for.
     *	209: The payment already failed, but the  reason  for  failure	was  not
	stored. This should only occur when querying failed payments on very old
	databases.

     A routing failure object has the fields below:

     erring_index:  The  index of the node along the route that reported the er-
     ror. 0 for the local node, 1 for the first hop, and  so  on.   erring_node:
     The  hex  string  of  the	pubkey	id  of the node that reported the error.
     erring_channel: The short channel ID of the channel that has the error  (or
     the  final channel if the destination raised the error).  erring_direction:
     The direction of traversing the erring_channel: failcode: The failure code,
     as per BOLT #4.  failcodename: The  human-readable  name  corresponding  to
     failcode, if known.

AUTHOR
     ZmnSCPxj ZmnSCPxj@protonmail.com is mainly responsible.

SEE ALSO
     lightning-sendpay(7), lightning-xpay(7)

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

EXAMPLES
     Example 1:

     Request:

     $ lightning-cli waitsendpay -k "payment_hash"="paymenthashinvl0310031003100310031003100310031003100310031003100"

     {
       "id": "example:waitsendpay#1",
       "method": "waitsendpay",
       "params": {
	 "payment_hash": "paymenthashinvl0310031003100310031003100310031003100310031003100"
       }
     }

     Response:

     {
       "created_index": 2,
       "id": 2,
       "payment_hash": "paymenthashinvl0310031003100310031003100310031003100310031003100",
       "groupid": 1,
       "updated_index": 2,
       "destination": "nodeid030303030303030303030303030303030303030303030303030303030303",
       "amount_msat": 10000,
       "amount_sent_msat": 10001,
       "created_at": 1738000000,
       "completed_at": 1739000000,
       "status": "complete",
       "payment_preimage": "paymentpreimagew010101010101010101010101010101010101010101010101"
     }

Core Lightning v26.06.1 				LIGHTNING-WAITSENDPAY(7)
home | help