Invoices

Generate invoices and read incoming transactions.

Create an invoice

Scope needed: invoices:create

Creates a new invoice to receive lightning payments.

POST https://api.getalby.com/invoices

Creates a new invoice

Request Body

{
  "expires_at": "2022-06-02T08:31:15Z",
  "payment_hash": "01ac4cfb2565d1221897a3bf7304c71fb47b1104fd591c8b91b903c878d16b84",
  "payment_request": "lnbcrt10u1p3fsa2jpp5qxkye7e9vhgjyxyh5wlhxpx8r768kygyl4v3ezu3hypus7x3dwzqhp5s6dz9ye889e8uyaxjzjlkh3vtwes50mhyvfraf3y6l3yk8t2mlgscqzpgxqyz5vqsp5zt95vajqwya7haely3p0ev2jg4v6lr84up4ujm5auk8u74xggtas9qyyssq7lmukwlctr2y4gcuw9324gfxefug45zrrywrp5l3fmn85zulk6z44pqx7vywp7zsks2r5rclang06akp6054tlgfad80ktzg9vwyatcqz6ssya","
}

Looking to create invoices for a lightning address without requiring scope? Try our Lightning Address details API which uses the LNURL protocol.

Get incoming invoice history

Scope needed: invoices:read

Lists all settled incoming invoices, including boostagram and LNURL metadata.

GET https://api.getalby.com/invoices/incoming

Lists all incoming invoices

Query Parameters

[
{
        "amount": 3,
        "boostagram": {
            "action": "stream",
            "app_name": "Fountain",
            "boost_link": "https://fountain.fm/episode/xxx",
            "episode": "Your episode",
            "feedID": 123456789,
            "itemID": 123456789,
            "message": null,
            "name": "Podcaster",
            "podcast": "Your podcast",
            "sender_id": "jack",
            "sender_name": "@jack",
            "time": "00:02:07",
            "ts": 127,
            "url": "https://media.rss.com/yourpodcast/feed.xml",
            "value_msat_total": 3000
        },
        "comment": null,
        "created_at": "2022-07-05T17:02:20.343Z",
        "creation_date": 1657040540,
        "currency": "btc",
        "custom_records": {
            "5482373484": "kW5TLmnj718m6+Z+DPW3xfvHa25mLrQyzgW0iKbQ5xM=",
            "696969": "TGx6bGpaS25NQVRKeEM2ejl0MTk=",
            "7629169": "eyJ2YWx1ZV9tc2F0X3RvdGFsIjozMDAwLCJuYW1lIjoiUG9kY2FzdGVyIiwicG9kY2FzdCI6IkFsYnkgcG9kY2FzdCIsImZlZWRJRCI6NDc4MTE5MiwidXJsIjoiaHR0cHM6Ly9tZWRpYS5yc3MuY29tL2ZsaXR6cG9kY2FzdC9mZWVkLnhtbCIsImFjdGlvbiI6InN0cmVhbSIsIm1lc3NhZ2UiOm51bGwsImFwcF9uYW1lIjoiRm91bnRhaW4iLCJzZW5kZXJfaWQiOiJVYkYwckRVeHJHeWpZcWVKUnhwdCIsInNlbmRlcl9uYW1lIjoiQGFkdWluMTgiLCJlcGlzb2RlIjoiVGVzdCBlcGlzb2RlIDEiLCJpdGVtSUQiOjgxNzY5MTEwMDYsInRzIjoxMjcsInRpbWUiOiIwMDowMjowNyIsImJvb3N0X2xpbmsiOiJodHRwczovL2ZvdW50YWluLmZtL2VwaXNvZGUvODE3NjkxMTAwNiJ9"
        },
        "description_hash": null,
        "expires_at": "2022-07-05T17:17:20.000Z",
        "expiry": 900,
        "identifier": "RGoRuWDG1bo9zMwNFFMXrKWA",
        "keysend_message": null,
        "memo": "",
        "payer_name": "@aduin18",
        "payer_pubkey": null,
        "preimage": "a8768f68cdb405d37b4409766333a266959a75bf64380324a6c2271bac6ec6fd",
        "payment_hash": "1c88e39b9247ade85f48a0f8b57ce1b12e9e220a4bc35edf93e98b2f3c1fc08b",
        "payment_request": "",
        "r_hash_str": "1c88e39b9247ade85f48a0f8b57ce1b12e9e220a4bc35edf93e98b2f3c1fc08b",
        "settled": true,
        "settled_at": "2022-07-05T17:02:20.000Z",
        "state": "SETTLED",
        "type": "incoming",
        "value": 3
    }

]

Get outgoing invoice history

Scope needed: transactions:read

Lists all settled outgoing invoices, including boostagrams information.

GET https://api.getalby.com/invoices/outgoing

Lists all outgoing invoices

Query Parameters

[
{
        "amount": 300,
        "boostagram": null,
        "comment": null,
        "created_at": "2022-06-21T11:04:07.237Z",
        "creation_date": 1655809370,
        "currency": "btc",
        "custom_records": null,
        "description_hash": null,
        "expires_at": "2022-06-21T11:17:50.000Z",
        "expiry": 900,
        "identifier": "cdyv5AUpMZeEgEAfsJrbTSMc",
        "keysend_message": null,
        "memo": "Feed Chickens @ pollofeed.com",
        "payer_name": null,
        "payer_pubkey": null,
        "payment_hash": "987f8f9fb750873183a34716359c917d961b0b1a816e4b176a63624a89897678",
        "payment_request": "lnbc3u1p3trf2ksp54a202vea0n3cr9u6evh7rqt858e4jzlwzqvjc4q2la0df2n6qntspp5nplcl8ah2zrnrqargutrt8y30ktpkzc6s9hyk9m2vd3y4zvfweuqdp0gejk2epqgd5xjcmtv4h8xgzqypcx7mrvdanx2ety9e3k7mgxqz95cqpjrzjq2j39c6dx9ea09gkx000aumgv4m4ghu444x7pztl8gnpfka5amkazz60ysqq4dcqqvqqqqqqqqqqqvsq9q9qyysgq4me57k6m7xxsf3fhdq86jk6e29hdsl9h4vjqm5y47vp8cgcfwcfsd7f27t6t73sw87g8l09j4kjxz77dl0kht86qwmxqf9l0nrqwkuqp9yex3z",
        "preimage": "a8768f68cdb405d37b4409766333a266959a75bf64380324a6c2271bac6ec6fd",
        "r_hash_str": "987f8f9fb750873183a34716359c917d961b0b1a816e4b176a63624a89897678",
        "settled": true,
        "settled_at": "2022-06-21T11:04:05.000Z",
        "state": "SETTLED",
        "type": "outgoing",
        "value": 300
    },
]

Get all invoice history

Scope needed: invoices:read

Combination of incoming and outgoing invoice histories. Possible query parameters are the same as above.

GET https://api.getalby.com/invoices

Query Parameters

[
{
        "amount": 300,
        "boostagram": null,
        "comment": null,
        "created_at": "2022-06-21T11:04:07.237Z",
        "creation_date": 1655809370,
        "currency": "btc",
        "custom_records": null,
        "description_hash": null,
        "expires_at": "2022-06-21T11:17:50.000Z",
        "expiry": 900,
        "identifier": "cdyv5AUpMZeEgEAfsJrbTSMc",
        "keysend_message": null,
        "memo": "Feed Chickens @ pollofeed.com",
        "payer_name": null,
        "payer_pubkey": null,
        "payment_hash": "987f8f9fb750873183a34716359c917d961b0b1a816e4b176a63624a89897678",
        "payment_request": "lnbc3u1p3trf2ksp54a202vea0n3cr9u6evh7rqt858e4jzlwzqvjc4q2la0df2n6qntspp5nplcl8ah2zrnrqargutrt8y30ktpkzc6s9hyk9m2vd3y4zvfweuqdp0gejk2epqgd5xjcmtv4h8xgzqypcx7mrvdanx2ety9e3k7mgxqz95cqpjrzjq2j39c6dx9ea09gkx000aumgv4m4ghu444x7pztl8gnpfka5amkazz60ysqq4dcqqvqqqqqqqqqqqvsq9q9qyysgq4me57k6m7xxsf3fhdq86jk6e29hdsl9h4vjqm5y47vp8cgcfwcfsd7f27t6t73sw87g8l09j4kjxz77dl0kht86qwmxqf9l0nrqwkuqp9yex3z",
        "preimage": "a8768f68cdb405d37b4409766333a266959a75bf64380324a6c2271bac6ec6fd",
        "r_hash_str": "987f8f9fb750873183a34716359c917d961b0b1a816e4b176a63624a89897678",
        "settled": true,
        "settled_at": "2022-06-21T11:04:05.000Z",
        "state": "SETTLED",
        "type": "outgoing",
        "value": 300
    },
    {
        "amount": 3,
        "boostagram": {
            "action": "stream",
            "app_name": "Fountain",
            "boost_link": "https://fountain.fm/episode/xxx",
            "episode": "Your episode",
            "feedID": 123456789,
            "itemID": 123456789,
            "message": null,
            "name": "Podcaster",
            "podcast": "Your podcast",
            "sender_id": "jack",
            "sender_name": "@jack",
            "time": "00:02:07",
            "ts": 127,
            "url": "https://media.rss.com/yourpodcast/feed.xml",
            "value_msat_total": 3000
        },
        "comment": null,
        "created_at": "2022-07-05T17:02:20.343Z",
        "creation_date": 1657040540,
        "currency": "btc",
        "custom_records": {
            "5482373484": "kW5TLmnj718m6+Z+DPW3xfvHa25mLrQyzgW0iKbQ5xM=",
            "696969": "TGx6bGpaS25NQVRKeEM2ejl0MTk=",
            "7629169": "eyJ2YWx1ZV9tc2F0X3RvdGFsIjozMDAwLCJuYW1lIjoiUG9kY2FzdGVyIiwicG9kY2FzdCI6IkFsYnkgcG9kY2FzdCIsImZlZWRJRCI6NDc4MTE5MiwidXJsIjoiaHR0cHM6Ly9tZWRpYS5yc3MuY29tL2ZsaXR6cG9kY2FzdC9mZWVkLnhtbCIsImFjdGlvbiI6InN0cmVhbSIsIm1lc3NhZ2UiOm51bGwsImFwcF9uYW1lIjoiRm91bnRhaW4iLCJzZW5kZXJfaWQiOiJVYkYwckRVeHJHeWpZcWVKUnhwdCIsInNlbmRlcl9uYW1lIjoiQGFkdWluMTgiLCJlcGlzb2RlIjoiVGVzdCBlcGlzb2RlIDEiLCJpdGVtSUQiOjgxNzY5MTEwMDYsInRzIjoxMjcsInRpbWUiOiIwMDowMjowNyIsImJvb3N0X2xpbmsiOiJodHRwczovL2ZvdW50YWluLmZtL2VwaXNvZGUvODE3NjkxMTAwNiJ9"
        },
        "description_hash": null,
        "expires_at": "2022-07-05T17:17:20.000Z",
        "expiry": 900,
        "identifier": "RGoRuWDG1bo9zMwNFFMXrKWA",
        "keysend_message": null,
        "memo": "",
        "payer_name": "@aduin18",
        "payer_pubkey": null,
        "payment_hash": "1c88e39b9247ade85f48a0f8b57ce1b12e9e220a4bc35edf93e98b2f3c1fc08b",
        "payment_request": "",
        "preimage": "a8768f68cdb405d37b4409766333a266959a75bf64380324a6c2271bac6ec6fd",
        "r_hash_str": "1c88e39b9247ade85f48a0f8b57ce1b12e9e220a4bc35edf93e98b2f3c1fc08b",
        "settled": true,
        "settled_at": "2022-07-05T17:02:20.000Z",
        "state": "SETTLED",
        "type": "incoming",
        "value": 3
    }
]

Get a specific invoice

Scope needed: invoices:read

Get details about specific invoice. Can be both incoming or outgoing.

Unsettled invoices can only be retrieved if they were created through the Alby API or Nostr Wallet Connect (using https://nwc.getalby.com/). Unsettled Invoices created directly using the Lndhub API will return a 404.

GET https://api.getalby.com/invoices/{payment_hash}

Get details about specific invoice. Can be both incoming or outgoing

Path Parameters

  {
        "amount": 3,
        "boostagram": {
            "action": "stream",
            "app_name": "Fountain",
            "boost_link": "https://fountain.fm/episode/xxx",
            "episode": "Your episode",
            "feedID": 123456789,
            "itemID": 123456789,
            "message": null,
            "name": "Podcaster",
            "podcast": "Your podcast",
            "sender_id": "jack",
            "sender_name": "@jack",
            "time": "00:02:07",
            "ts": 127,
            "url": "https://media.rss.com/yourpodcast/feed.xml",
            "value_msat_total": 3000
        },
        "comment": null,
        "created_at": "2022-07-05T17:02:20.343Z",
        "creation_date": 1657040540,
        "currency": "btc",
        "custom_records": {
            "5482373484": "kW5TLmnj718m6+Z+DPW3xfvHa25mLrQyzgW0iKbQ5xM=",
            "696969": "TGx6bGpaS25NQVRKeEM2ejl0MTk=",
            "7629169": "eyJ2YWx1ZV9tc2F0X3RvdGFsIjozMDAwLCJuYW1lIjoiUG9kY2FzdGVyIiwicG9kY2FzdCI6IkFsYnkgcG9kY2FzdCIsImZlZWRJRCI6NDc4MTE5MiwidXJsIjoiaHR0cHM6Ly9tZWRpYS5yc3MuY29tL2ZsaXR6cG9kY2FzdC9mZWVkLnhtbCIsImFjdGlvbiI6InN0cmVhbSIsIm1lc3NhZ2UiOm51bGwsImFwcF9uYW1lIjoiRm91bnRhaW4iLCJzZW5kZXJfaWQiOiJVYkYwckRVeHJHeWpZcWVKUnhwdCIsInNlbmRlcl9uYW1lIjoiQGFkdWluMTgiLCJlcGlzb2RlIjoiVGVzdCBlcGlzb2RlIDEiLCJpdGVtSUQiOjgxNzY5MTEwMDYsInRzIjoxMjcsInRpbWUiOiIwMDowMjowNyIsImJvb3N0X2xpbmsiOiJodHRwczovL2ZvdW50YWluLmZtL2VwaXNvZGUvODE3NjkxMTAwNiJ9"
        },
        "description_hash": null,
        "expires_at": "2022-07-05T17:17:20.000Z",
        "expiry": 900,
        "identifier": "RGoRuWDG1bo9zMwNFFMXrKWA",
        "keysend_message": null,
        "memo": "",
        "payer_name": "@aduin18",
        "payer_pubkey": null,
        "payment_hash": "1c88e39b9247ade85f48a0f8b57ce1b12e9e220a4bc35edf93e98b2f3c1fc08b",
        "payment_request": "",
        "r_hash_str": "1c88e39b9247ade85f48a0f8b57ce1b12e9e220a4bc35edf93e98b2f3c1fc08b",
        "settled": true,
        "settled_at": "2022-07-05T17:02:20.000Z",
        "state": "SETTLED",
        "type": "incoming",
        "value": 3
    }

Decode an invoice

Decode an invoice. Will also add the alias of the receiving node & route hints (LSP's).

Decode an invoice

GET https://api.getalby.com/decode/bolt11/{bolt11_invoice}

Will also add the alias of the receiving node & route hints (LSP's).

Path Parameters

{
  "currency": "bc",
  "created_at": 1693210330,
  "expiry": 86400,
  "payee": "030a58b8653d32b99200a2334cfe913e51dc7d155aa0116c176657a4f1722677a3",
  "msatoshi": 23000,
  "description": "Alby invoice",
  "payment_hash": "184d3946b916dfba520b242b30254c53dd9c538158cac37df2a54fad7ed99b16",
  "min_final_cltv_expiry": 80,
  "amount": 23,
  "payee_alias": "getalby.com",
  "route_hint_aliases": []
}

Last updated

Logo

Your bitcoin & nostr companion / from 🐝 with 🧡