core-lightning/doc/schemas/lightning-waitinvoice.json

{
  "$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": "lnbcrt222n1pnt3005720bolt11wtinv01010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101",
        "payment_hash": "paymenthashwaitinv0101010101010101010101010101010101010101010101",
        "amount_msat": 2000,
        "status": "paid",
        "pay_index": 5,
        "amount_received_msat": 2000,
        "paid_at": 1738500000,
        "payment_preimage": "paymentpreimagewaitinv0010101010101010101010101010101010101010101",
        "description": "inv2",
        "expires_at": 1739000000,
        "created_index": 13,
        "updated_index": 5
      }
    },
    {
      "request": {
        "id": "example:waitinvoice#2",
        "method": "waitinvoice",
        "params": [
          "inv3"
        ]
      },
      "response": {
        "label": "inv3",
        "bolt11": "lnbcrt222n1pnt3005720bolt11wtinv02020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202",
        "payment_hash": "paymenthashwaitinv0202020202020202020202020202020202020202020202",
        "amount_msat": 3000,
        "status": "paid",
        "pay_index": 6,
        "amount_received_msat": 3000,
        "paid_at": 1738500000,
        "payment_preimage": "paymentpreimagewaitinv0020202020202020202020202020202020202020202",
        "description": "inv3",
        "expires_at": 1739000000,
        "created_index": 14,
        "updated_index": 6
      }
    }
  ]
}