Receiving Lightning Payments

Creating a Charge

As explained in The Charge wiki page, in order to receive Lightning payments through the ZEBEDEE platform you need to first create a Charge. A Charge accepts the following attributes:

AttributeStatusDescription
amountStringThe Charge amount (in millisatoshis).
descriptionStringThe Charge description (also applied as the description to the associated BOLT11 Lightning invoice).
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 services 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 API (or leverage one of our SDKs) by passing the correct attributes:

// Using ZEBEDEE's NodeJS SDK
import { createCharge, initAPI } from 'zebedee-nodejs';
// Instantiate the API
const apiOptions = { apiKey: 'API_KEY_HERE' };
initAPI(apiOptions);
// Set the payload
const payload = {
expiresIn: 300,
amount: '50000',
description: 'My Custom Charde Description',
callbackUrl: 'https://yourapp.com/callback',
internalId: '11af01d092444a317cb33faa6b8304b8',
};
// Create Charge
try {
const response = await createCharge(payload);
} catch(error) {
console.log({ error });
}

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": "Description of the Charge",
"createdAt": "2019-12-23T03:58:17.993Z",
"callbackUrl": "http://localhost/callback",
"internalId": "11af01d092444a317cb33faa6b8304b8",
"amount": "2000",
"status": "pending",
"invoice": {
"expiresAt": "2019-12-23T04:08:18.038Z",
"request": "lnbc20n1p0qqw66pp5lhjn2sshvh03h2lsxyzg5eyfwt0760207q3hake25fs7l3psegtqdpgg3jhxcmjd9c8g6t0dcsx7e3qw35x2gzrdpshyem9cqzpgxqzjcfppjramjf8sxnvy3k8dq84kv56dy5gq9mlqs9qy9qsqsp5jvf69w282jdxkyt824dn0crxdentx8nvncfdt0ulqp75lvkjpagqqwpgcttpmfzaxc3akfn85jlu8cmtv5l2hu8q3yqttru8vlryg3vnewssy8w00yyfsghzqj03j45kj3uhhjek6q6e8djfu5u4gna6wjcqdsdhwe"
}
}
}

Receiving Funds

Now that you have created a Charge, you can allow Players/Users to pay this Lightning invoice. Depending on your use-case/implementation you may choose to display the invoice.request as a QR Code that others can scan. Any 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 Lightning 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 CreateCharge or GetChargeDetails API calls.

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

Please refer to the Entity Status portion of the wiki to learn more about the Charge status property.

To subscribe to updates on a specific Charge, 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 ZEBEDEE services will make a POST request to the URL provided in callbackUrl, passing the Charge updates as data in the request.