Request Lightning Charge for ZBD Gamertag

Request Lightning Charge for ZBD Gamertag

While you can use the Send Bitcoin to ZBD Gamertag endpoint to make a direct payment to a ZBD user, if you want to create a regular Lightning Network Invoice / Charge QR code for that given user, you can do so using the /gamertag/charges endpoint.

In order to request Charges from a user's Gamertag you just need to make a simple API call with a payload like the example below.

Property	Status	Description
Endpoint	/gamertag/create-charge	ZEBEDEE API endpoint to use.
HTTP Method	POST	The type of HTTP request to invoke.
Authentication	apikey	How the API request is authenticated by ZBD Platform.

For the data portion of the POST request, you can use the following payload as an example:

  {
    "gamertag": "andre",
    "amount": "15000",
    "internalId": "12347ahk1n",
    "description": "ZBD so fast!",
    "callbackUrl": "https://your-app.com/zbd-callback",
}

In order to receive updates about the status of this request, make sure to include a callbackUrl in the data portion of the request.

The response payload will include a invoiceRequest which is the contents of the payment request QR code.

  {
    "success": true,
    "data": {
        "status": "CHARGE_PENDING",
        "amount": "15000",
        "internalId": "12347ahk1n",
        "description": "ZBD so fast!",
        "invoiceRequest": "lnbc100n1pskq45xpp5q5rtpfzydndqk4fu2y4h64fdc284y6av0fn8gz4dmkq89xuxd28sdpvw3jhxarfdenjqctxw3jhygrjv4kk7anfdenjqmnpd4jscqzpgxqzjcsp59g6vgrss790zkwjqc3adndzt5tcq2ltaxynfstggjl6rre3kk6js9qyyssqfyan62pzsjsm62l6zq57jv9pmlpmycvqu649ccfjn7mar77awgykz2gft3fcgl9x5m4mz78nyng920uf6zwft5qnt2qjtqgpl7c72dgq4z7mgv",
        "invoiceExpiresAt": "2021-10-08T14:42:38.759Z",
        "unit": "msats",
        "createdAt": "2022-02-08T14:32:38.793Z"
    },
    "message": "Successfully created charge request for gamertag"
}

note

Charges / Payment Requests have defined expiration times. After a Charge expires it cannot be paid, but you can simply create another one.

Once a payment is made and the Charge settles, the ZBD User will receive a Push Notification alerting them they've been sent some Bitcoin.

In-Game Multiplayer Commerce through ZBD Gamertags

For Developers that wish to provide a more robust commerce experience for their gamers, requesting an invoice from ZBD Gamertags can be one of the ways. Think of yourself, the Developer, as the Orchestrator of payments. By leveraging Lightning Network invoices tied to specific ZBD Gamertags, you can ensure that the payment is made to the correct user, and that the payment has truly settled.

Two-Step Payment Orchestration

Let's say Alice wants to buy a sword from Bob inside of the game. Well that's easy, and there's two ways:

ZBD Gamertag Charges

You can use the above endpoint to create a Charge from Bob's ZBD Gamertag, and display it for Alice to pay. Pass a callbackUrl on the ZBD API request and when the payment settles, you will be alerted of it and can then transfer the sword asset inside the game.

Yes, it's really that simple!

Game Wallet as Escrow

Alternatively you could rely on the Game's own Wallet as a form of escrow. You can create a Charge using the /charges endpoint passing a callbackUrl to receive settlement updates, and have Alice pay it.

note

Alice will effectively be paying the Game Wallet in this scenario.

Once payment is settled, you can use the Send Bitcoin to ZBD Gamertag endpoint and send the same amount to Bob. When this second payment settles you can then transfer the sword asset inside the game.

While this technically involves two transactions, it provides a bit more control to the Developer that wishes to manage the transfer of assets/in-game items a bit more closely and with more checks and balances in place. Both approaches are recommended.