Skip to main content

Receiving Lightning Payments

Receiving Lightning Payments

Receiving Lightning Payments

In order to receive Bitcoin through the Lightning Network using the ZEBEDEE API, you must first create a Charge. A Charge accepts the following attributes:

PropertyStatusDescription
amountStringThe Charge amount (in millisatoshis).
descriptionStringThe Charge description (also applied as the description to the associated BOLT11 Lightning payment request).
internalIdStringAn optional free-use attribute. Usually used by setting the Player/User ID of your Game/Application in order to link specific Charges to specific Players.
callbackUrlStringThe URL ZEBEDEE API will make a POST HTTP request to with information about the Charges's status updates.
expiresInNumberThe desired expiration time for this Charge (in seconds).

To create a Charge, use the /charges API (or leverage one of our SDKs) by passing the correct attributes:

curl --location --request POST 'https://api.zebedee.io/v0/charges' \
--header 'Content-Type: application/json' \
--header 'apikey: API_KEY_HERE' \
--data-raw '{
"expiresIn": 300,
"amount": "50000",
"internalId": "118304b8",
"description": "My Charge Description",
"callbackUrl": "https://your-app.com/zbd-callback"
}'

If the submitted request suceeds, you can expect a JSON API response that resembles the following:

{
"message": "Successfully created Charge.",
"data": {
"id": "c121356b-9671-4fbd-a751-987fb4b3d0b3",
"description": "My Charge Description",
"createdAt": "2022-12-23T03:58:17.993Z",
"callbackUrl": "https://your-app.com/zbd-callback",
"internalId": "118304b8",
"amount": "50000",
"status": "pending",
"invoice": {
"expiresAt": "2019-12-23T04:08:18.038Z",
"request": "lnbc20n1p0qqw66pp5lhjn2sshvh03h2lsxyzg5eyfwt0760207q3hake25fs7l3psegtqdpgg3jhxcmjd9c8g6t0dcsx7e3qw35x2gzrdpshyem9cqzpgxqzjcfppjramjf8sxnvy3k8dq84kv56dy5gq9mlqs9qy9qsqsp5jvf69w282jdxkyt824dn0crxdentx8nvncfdt0ulqp75lvkjpagqqwpgcttpmfzaxc3akfn85jlu8cmtv5l2hu8q3yqttru8vlryg3vnewssy8w00yyfsghzqj03j45kj3uhhjek6q6e8djfu5u4gna6wjcqdsdhwe"
}
}
}

Receiving Funds

Now that you have created a Charge, you can allow anyone to pay this Bitcoin Lightning Network Payment Request. Depending on your use-case you may choose to display the invoice.request property as a QR Code that others can scan with their mobile apps, or you can put it under a button click. Any Bitcoin Lightning-capable wallets can read, decode, and effect payments against these Charges.

Charge Updates

All Charges will either complete or expire. If no payment is effected until the Charge's expiration time, the Charge (and underlying Lightning Network Invoice) will expire and will therefore no longer be payable. To know the status of your specific Charge, check the status attribute returned from the /charges/create or /charges/get API calls.

{
...
"status": "pending" // pending | completed | expired | error
...
}

To subscribe to updates on any given Charge object, the recommended approach is to provide a callbackUrl property when creating that Charge. Whenever there are updates to the Charge (a payment was made, or Charge expires) the ZBD API will make a POST request to the URL provided in callbackUrl, passing the Charge updates as data in the request.