---
updatedAt: 2026-07-14T01:25:23.000Z
agentTools:
  projectIndex: https://docs.corelightning.org/llms.txt
---

# waitinvoice

# waitinvoice -- Command for waiting for specific payment

## SYNOPSIS

**waitinvoice** *label*

## DESCRIPTION

The **waitinvoice** RPC command waits until a specific invoice is paid, then returns that single entry as per **listinvoices**.

* **label** (one of): Unique label of the invoice waiting to be paid.:
  * (string)
  * (integer)

## RETURN VALUE

On success, an object is returned, containing:

* **label** (string): Unique label supplied at invoice creation.
* **payment\_hash** (hash): The hash of the *payment\_preimage* which will prove payment.
* **status** (string) (one of "paid", "expired"): Whether it's paid or expired.
* **expires\_at** (u64): UNIX timestamp of when it will become / became unpayable.
* **created\_index** (u64): 1-based index indicating order this invoice was created in. *(added v23.08)*
* **description** (string, optional): Description used in the invoice.
* **amount\_msat** (msat, optional): The amount required to pay this invoice.
* **bolt11** (string, optional): The BOLT11 string (always present unless *bolt12* is).
* **bolt12** (string, optional): The BOLT12 string (always present unless *bolt11* is).
* **updated\_index** (u64, optional): 1-based index indicating order this invoice was changed (only present if it has changed since creation). *(added v23.08)*

If **status** is "paid":

* **pay\_index** (u64): Unique incrementing index for this payment.
* **amount\_received\_msat** (msat): The amount actually received (could be slightly greater than *amount\_msat*, since clients may overpay).
* **paid\_at** (u64): UNIX timestamp of when it was paid.
* **payment\_preimage** (secret): Proof of payment.
* **paid\_outpoint** (object, optional): Outpoint this invoice was paid with. *(added v23.11)*:
  * **txid** (txid): ID of the transaction that paid the invoice. *(added v23.11)*
  * **outnum** (u32): The 0-based output number of the transaction that paid the invoice. *(added v23.11)*

## ERRORS

On error the returned object will contain `code` and `message` properties, with `code` being one of the following:

* -32602: If the given parameters are wrong.
* -1: If the invoice is deleted while unpaid, or the invoice does not exist.
* 903: If the invoice expires before being paid, or is already expired.

## AUTHOR

Christian Decker <decker.christian@gmail.com> is mainly responsible.

## SEE ALSO

lightning-waitanyinvoice(7), lightning-listinvoices(7), lightning-delinvoice(7), lightning-invoice(7)

## RESOURCES

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

## EXAMPLES

**Example 1**:

Request:

```shell
lightning-cli waitinvoice -k "label"="inv2"
```
```json
{
  "id": "example:waitinvoice#1",
  "method": "waitinvoice",
  "params": {
    "label": "inv2"
  }
}
```

Response:

```json
{
  "label": "inv2",
  "bolt11": "lnbcrt20n1pne035qsp59v3v5ksna0cgcgwupg6h4xsg3dvwk06ly4jh0ghytrcghrnypqnspp50te9vj4kzy733vkc29uv5elz30v9rzpyzq0kcsnyj0dq2h9mt4hsdq8d9h8vvsxqyjw5qcqp99qxpqysgqk8lwpzs9pmkm9a0mda42xcj3m7q29np2erxqp93dce9sreczgprqndyktadx78yljnsaw0zrkjw6hhkkzgthph94hcat9ej64p2jwdqqyysl70",
  "payment_hash": "7af2564ab6113d18b2d85178ca67e28bd8518824101f6c426493da055cbb5d6f",
  "amount_msat": 2000,
  "status": "paid",
  "pay_index": 5,
  "amount_received_msat": 2000,
  "paid_at": 1738000000,
  "payment_preimage": "09e7f193a0100ea809e7f193a0100ea809e7f193a0100ea809e7f193a0100ea8",
  "description": "inv2",
  "expires_at": 1738604800,
  "created_index": 13,
  "updated_index": 5
}
```

**Example 2**:

Request:

```shell
lightning-cli waitinvoice "inv3"
```
```json
{
  "id": "example:waitinvoice#2",
  "method": "waitinvoice",
  "params": [
    "inv3"
  ]
}
```

Response:

```json
{
  "label": "inv3",
  "bolt11": "lnbcrt30n1pne035qsp5kf8assunt7u085fxt3r99w7qaqazs69hm2msdull2kq9j8cj5maspp5evufghkqzgttz9e4ryjhdp96s94ruc6nqg5j8qersn0q9ruvvddsdq8d9h8vvcxqyjw5qcqp99qxpqysgqjrcg0wsa6njd5d6vkrgjw5swe6hn4zamvmvs4j5hza9pzex9amgzxtrncm0fyeaw72shurx7eqn2dnwsgdms8ye2tppgwsta79ent8cp20fpqq",
  "payment_hash": "cb38945ec01216b1173519257684ba816a3e6353022923832384de028f8c635b",
  "amount_msat": 3000,
  "status": "paid",
  "pay_index": 6,
  "amount_received_msat": 3000,
  "paid_at": 1738000000,
  "payment_preimage": "09e7f193a0100ea909e7f193a0100ea909e7f193a0100ea909e7f193a0100ea9",
  "description": "inv3",
  "expires_at": 1738604800,
  "created_index": 14,
  "updated_index": 6
}
```