{
  "$schema": "../rpc-schema-draft.json",
  "type": "object",
  "rpc": "waitinvoice",
  "title": "Command for waiting for specific payment",
  "description": [
    "The **waitinvoice** RPC command waits until a specific invoice is paid, then returns that single entry as per **listinvoices**."
  ],
  "request": {
    "required": [
      "label"
    ],
    "additionalProperties": true,
    "properties": {
      "label": {
        "oneOf": [
          {
            "type": "string"
          },
          {
            "type": "integer"
          }
        ],
        "description": [
          "Unique label of the invoice waiting to be paid."
        ]
      }
    }
  },
  "response": {
    "required": [
      "label",
      "payment_hash",
      "status",
      "created_index",
      "expires_at"
    ],
    "additionalProperties": true,
    "properties": {
      "label": {
        "type": "string",
        "description": [
          "Unique label supplied at invoice creation."
        ]
      },
      "description": {
        "type": "string",
        "description": [
          "Description used in the invoice."
        ]
      },
      "payment_hash": {
        "type": "hash",
        "description": [
          "The hash of the *payment_preimage* which will prove payment."
        ]
      },
      "status": {
        "type": "string",
        "enum": [
          "paid",
          "expired"
        ],
        "description": [
          "Whether it's paid or expired."
        ]
      },
      "expires_at": {
        "type": "u64",
        "description": [
          "UNIX timestamp of when it will become / became unpayable."
        ]
      },
      "amount_msat": {
        "type": "msat",
        "description": [
          "The amount required to pay this invoice."
        ]
      },
      "bolt11": {
        "type": "string",
        "description": [
          "The BOLT11 string (always present unless *bolt12* is)."
        ]
      },
      "bolt12": {
        "type": "string",
        "description": [
          "The BOLT12 string (always present unless *bolt11* is)."
        ]
      },
      "created_index": {
        "type": "u64",
        "added": "v23.08",
        "description": [
          "1-based index indicating order this invoice was created in."
        ]
      },
      "updated_index": {
        "type": "u64",
        "added": "v23.08",
        "description": [
          "1-based index indicating order this invoice was changed (only present if it has changed since creation)."
        ]
      }
    },
    "allOf": [
      {
        "if": {
          "additionalProperties": true,
          "properties": {
            "status": {
              "type": "string",
              "enum": [
                "paid"
              ]
            }
          }
        },
        "then": {
          "additionalProperties": false,
          "required": [
            "pay_index",
            "amount_received_msat",
            "paid_at",
            "payment_preimage"
          ],
          "properties": {
            "label": {},
            "description": {},
            "payment_hash": {},
            "status": {},
            "msatoshi": {},
            "amount_msat": {},
            "bolt11": {},
            "bolt12": {},
            "expires_at": {},
            "created_index": {},
            "updated_index": {},
            "pay_index": {
              "type": "u64",
              "description": [
                "Unique incrementing index for this payment."
              ]
            },
            "amount_received_msat": {
              "type": "msat",
              "description": [
                "The amount actually received (could be slightly greater than *amount_msat*, since clients may overpay)."
              ]
            },
            "paid_at": {
              "type": "u64",
              "description": [
                "UNIX timestamp of when it was paid."
              ]
            },
            "paid_outpoint": {
              "type": "object",
              "description": [
                "Outpoint this invoice was paid with."
              ],
              "added": "v23.11",
              "additionalProperties": false,
              "required": [
                "txid",
                "outnum"
              ],
              "properties": {
                "txid": {
                  "added": "v23.11",
                  "type": "txid",
                  "description": [
                    "ID of the transaction that paid the invoice."
                  ]
                },
                "outnum": {
                  "added": "v23.11",
                  "type": "u32",
                  "description": [
                    "The 0-based output number of the transaction that paid the invoice."
                  ]
                }
              }
            },
            "payment_preimage": {
              "type": "secret",
              "description": [
                "Proof of payment."
              ]
            }
          }
        },
        "else": {
          "additionalProperties": false,
          "properties": {
            "label": {},
            "description": {},
            "payment_hash": {},
            "status": {},
            "msatoshi": {},
            "amount_msat": {},
            "bolt11": {},
            "bolt12": {},
            "created_index": {},
            "updated_index": {},
            "expires_at": {}
          }
        }
      }
    ]
  },
  "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": [
    {
      "request": {
        "id": "example:waitinvoice#1",
        "method": "waitinvoice",
        "params": {
          "label": "inv2"
        }
      },
      "response": {
        "label": "inv2",
        "bolt11": "lnbcrt20n1pn2s38fsp55xnux6tuzuutlqhekzytnexpqj6w3q00h6e7wu08ex43rdr4xqdqpp5znq67nu5secgcf79ncjtqfdpjfqh7acaxvngcqwqsvvxwnkyl35qdq8d9h8vvsxqyjw5qcqp9rzjqdwjkyvjm7apxnssu4qgwhfkd67ghs6n6k48v6uqczgt88p6tky96qqq0vqqqqgqqyqqqqqpqqqqqzsqqc9qxpqysgq9ptnru6v58v8qd58xdqypr86utn6fhssx8rwegsspfp9d975h0t47xn0hea6qrmy2ucxt4l02nkxu7va7d5lqgy8nrqmhxqpm5qauegqjjqr02",
        "payment_hash": "14c1af4f9486708c27c59e24b025a192417f771d33268c01c08318674ec4fc68",
        "amount_msat": 2000,
        "status": "paid",
        "pay_index": 4,
        "amount_received_msat": 2000,
        "paid_at": 1722303723,
        "payment_preimage": "1bda6e78384905bc476c6f50b447cf7fbba13a2644d49d85d797a826e8b9a6a0",
        "description": "inv2",
        "expires_at": 1722908521,
        "created_index": 12,
        "updated_index": 4
      }
    },
    {
      "request": {
        "id": "example:waitinvoice#2",
        "method": "waitinvoice",
        "params": [
          "inv3"
        ]
      },
      "response": {
        "label": "inv3",
        "bolt11": "lnbcrt30n1pn2s38fsp5syqds2z0hgqgf3dcxt9kp5m2rtywxm4u4hr4xe90r885rr609vgqpp52y0xdhlzrua5clpuyw4wcfk9duxwwauzcjxrs9nj00258njmdjnsdq8d9h8vvcxqyjw5qcqp9rzjqdwjkyvjm7apxnssu4qgwhfkd67ghs6n6k48v6uqczgt88p6tky96qqq0vqqqqgqqyqqqqqpqqqqqzsqqc9qxpqysgqkkeex45p62vc7nfjywwfle8yhk9wemyktw2m7924cfmlthk37q6ptjd8vxyaevtejfj44yp55xllqlljxv5vz6wc3gc9jlfkwrkngscqtl0xs8",
        "payment_hash": "511e66dfe21f3b4c7c3c23aaec26c56f0ce77782c48c3816727bd543ce5b6ca7",
        "amount_msat": 3000,
        "status": "paid",
        "pay_index": 5,
        "amount_received_msat": 3000,
        "paid_at": 1722303725,
        "payment_preimage": "86e637cb70631a0db88cc8f6ef9a21457b1b85be30236efb769a611b356225cd",
        "description": "inv3",
        "expires_at": 1722908521,
        "created_index": 13,
        "updated_index": 5
      }
    }
  ]
}