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)

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

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

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

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

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

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

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

Name

Type

Description

bolt11_invoice*

String

Needs to be a valid bolt11

{
  "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 1 year ago