Callbacks

​

Payment Lifecycle

Although it may be that 99% of the time you use the ZBD API to send a payment it settles immediately, this is NOT a certainty. All payments are asynchronous so there’s still chances they will not succeed.

The Lightning Network is a decentralized organism / network and therefore there are many factors and circumstances that are outside of ZBD’s control. Whether it is another provider going offline, or improper management of Bitcoin liquidity on the network, payments in Lightning can fail and you as a developer must understand how to react to these failures.

​

Receiving Bitcoin

To receive payments, you normally create Charges (or Static Charges). These are created and remain in a pending status until someone successfully scans and pays the Charge, at which point it becomes completed. If enough time is elapsed, the Charge can also expire making it impossible to be paid.

​

Sending Bitcoin

On the other hand, to send Bitcoin you must use one of the many Payment APIs. Payments through the Lightning Network can always fail, due to a myriad of reasons (e.g. network connectivity, size of payment, destination or receipient, etc). Because of that, every payment starts in a processing state, and only when it’s settled or failed does it receive the completed or failed status’ respectively.

As you can understand now, it is important that you subscribe to updates on all your Charges and Payments when using the ZBD API.

​

Callback URL

In order to properly receive updates to any Payments, Charges, and Withdrawals created through the ZBD API, you should always pass along the callbackUrl property.

This callbackUrl should point to an HTTP server that you control/manage and should expose a POST HTTP call on this endpoint. It could look like this:

https://yourserver.com/api/v1/zbd/callback

Callback URLs MUST be HTTPS. HTTP calls are ignored. The server must be reachable to the public internet and not require any additional means of authentication.

​

Payloads

Below is a set of example payloads for the main APIs available:

​

Charges

{
    "amount":"1000",
    "callbackUrl":"<your_callback_url",
    "description":"Test charge",
    "id":"<id>",
    "internalId":null,
    "status":"expired",
    "unit":"msats"
}

​

Payments

{
    "amount":"10000",
    "confirmedAt":"2024-02-06T11:51:26.985Z",
    "description":"Test payment",
    "fee":"0",
    "id":"<payment_id>",
    "internalId":null,
    "invoice":"<your_invoice>",
    "preimage":"<preimage>",
    "processedAt":"2024-02-06T11:51:26.985Z",
    "status":"completed",
    "unit":"msats"
}

​

Withdrawals 

{
    "amount":"10000",
    "callbackUrl":"<your_callback_url>",
    "createdAt":"2024-02-06T12:02:08.166Z",
    "description":"Test withdrawal",
    "expiresAt":"2024-02-06T12:05:08.164Z",
    "fee":"0",
    "id":"<id>",
    "internalId":null,
    "invoice":
    {
        "fastRequest":"<fastRequest>",
        "fastUri":"<fastUri",
        "request":"<request>",
        "uri":"<uri>"
    },
    "status":"completed",
    "unit":"msats"
}

​

Lightning Address

{
    "amount":"1000",
    "callbackUrl":"<your_callback_url",
    "confirmedAt":"2024-02-06T12:11:08.308Z",
    "createdAt":"2024-02-06T12:11:07.700Z",
    "description":"ZEBEDEE Payment",
    "fee":"0",
    "id":"<id>",
    "internalId":null,
    "invoice":"<invoice>",
    "preimage":"<preimage",
    "status":"completed",
    "transactionId":"<transactionId>",
    "unit":"msats",
    "walletId":"<walletId>"
}

​

Security / Integrity

It is important that developers are able to validate the integrity of all API calls performed to their callbackUrl endpoints.

To ensure that calls are coming from trusted ZBD API servers, please use the ZBD IP Address API Endpoint.

By checking the originating IP address of the request received to your callback servers, with the approved IP address returned from this API endpoint, you are able to verify the authenticity of the requests.

​

Testing Locally

When developing with the ZBD API, it is imperative that developers can test full end-to-end functionality of payment flows, including the async updates received through the callbackUrls.

In order to receive updates locally, we recommend using a proxy server such as ngrok.

• Follow the installation steps
• Run command to start ngrok tunnel ngrok http 8000
• ngrok URL (e.g. https://84c5dfxx39d74.ngrok.io) is provided
  • This URL is accessible to the world —> expose an API endpoint here and use it as the callbackUrl (e.g. https://84c5dfxx39d74.ngrok.io/api/zbd-callback).

You will now be able to receive async updates about your ZBD API transactions directly to your local environment.