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

Name	Type	Description
description_hash	String	Pass a hash of the description instead of the description (for private or long descriptions)
amount*	int64	amount, must be a whole number in sats (millisats are not supported).
description	String	Arbitrary text (included in the BOLT11 invoice)
currency	String	currency of the invoice. Default is "btc"
memo	String	same as "description" field.
comment	String	Arbitrary text to save alongside the invoice (not included in the BOLT11 invoice)
metadata	Object	Arbitrary data to save alongside the invoice (not included in the BOLT11 invoice)
payer_name	String	Name of payer (not included in the BOLT11 invoice)
payer_email	String	Email of payer (not included in the BOLT11 invoice)
payer_pubkey	String	Nostr or node pubkey of payer to store with the invoice (not included in the BOLT11 invoice)

200: OK

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

400: Bad Request Invalid request body or Invoice could not be created

{
  "code": 0,
  "error": true,
  "message": "string"
}

422: Unprocessable Entity Invoice could not be created

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

Name	Type	Description
q[created_at_gt]	Int	Filter invoices created after this Unix Timestamp in UTC (e.g. 1681992321)
q[created_at_lt]	Int	Filter invoices created before this Unix Timestamp in UTC (e.g. 1681992321)
q[since]	String	Filter invoices created after the given invoice identifier
page	Int	Page number (1 is the first page)
items	Int	Items per page (Default 25)
q[before]	String	Filter invoices created before the given invoice identifier

200: OK

[
{
        "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

Name	Type	Description
q[since]	String	Filter invoices created after the given invoice identifier
q[created_at_lt]	Int	Filter invoices created before this Unix Timestamp in UTC (e.g. 1681992321)
q[created_at_gt]	Int	Filter invoices created after this Unix Timestamp in UTC (e.g. 1681992321)
page	Int	Page number (1 is the first page)
items	Int	Items per page (Default 25)
q[before]	String	Filter invoices created before the given invoice identifier

200: OK

[
{
        "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

Name	Type	Description
q[since]	String	Filter invoices created after the given invoice identifier
q[created_at_lt]	Int	Filter invoices created before this Unix Timestamp in UTC (e.g. 1681992321)
q[created_at_gt]	Int	Filter invoices created after this Unix Timestamp in UTC (e.g. 1681992321)
page	Int	Page number (1 is the first page)
items	Int	Items per page (Default 25)
q[before]	String	Filter invoices created before the given invoice identifier

200: OK

[
{
        "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

Name	Type	Description
payment_hash*	String	The payment hash of the payment

200: OK Settled invoice

  {
        "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
    }

400: Bad Request

{
  "code": 0,
  "error": true,
  "message": "string"
}

200: OK Unsettled invoice

{
    "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

Name	Type	Description
bolt11_invoice*	String	Needs to be a valid bolt11

200: OK

{
  "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": []
}