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","
}
{
"code": 0,
"error": true,
"message": "string"
}
NOTE: this error code is currently unused, but is planned to be used in the near future.
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
}
{
"code": 0,
"error": true,
"message": "string"
}
{
"amount": 1000,
"boostagram": null,
"comment": null,
"created_at": "2023-11-08T04:58:11.205Z",
"creation_date": 1699419491,
"currency": "btc",
"custom_records": null,
"description_hash": null,
"expires_at": "2023-11-09T04:58:11.000Z",
"expiry": 86400,
"fiat_currency": "USD",
"fiat_in_cents": 36,
"identifier": "6vaChhm17PqoJ5LJQi1THpUC",
"keysend_message": null,
"memo": null,
"payer_name": null,
"payer_email": null,
"payer_pubkey": null,
"payment_hash": "c169e73f4eb85de8bfa345d0b650b6ffb64054ebb57571e3d3a235b6ba616fe0",
"payment_request": "lnbc10u1pj5k9trpp5c957w06whpw730arghgtv59kl7myq48tk46hrc7n5g6mdwnpdlsqdp8xemxzsmgdpknzd6sw9h55d2vffgkjv25fpc92sccqzzsxqyz5vqsp52aauy758lcg0hkda65kcrffrlsgum97gt6ywu8r0fz6cacwy0x7q9qyyssqyafv2eamugl5e79wrcu7pzllwyq8kcn5fw8l6njjqtzsfthsd6452nwyjxmpmpek8jrt4j6vtm4wq8dkj34wewz0707yvdgqxqsuhyspxmsmld",
"r_hash_str": "c169e73f4eb85de8bfa345d0b650b6ffb64054ebb57571e3d3a235b6ba616fe0",
"settled": null,
"settled_at": null,
"state": "CREATED",
"type": "incoming",
"value": 1000,
"metadata": null,
"destination_alias": null,
"destination_pubkey": null,
"first_route_hint_pubkey": null,
"first_route_hint_alias": null,
"qr_code_png": "https://getalby.com/api/invoices/6vaChhm17PqoJ5LJQi1THpUC.png",
"qr_code_svg": "https://getalby.com/api/invoices/6vaChhm17PqoJ5LJQi1THpUC.svg"
}
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