Request Charge for ZBD User
ZBD API is migrating the terminology from ZBD Gamertags to ZBD Usernames. There are no breaking changes to you as a developer.
In general, if you used to search for ‘Gamertag’ inside zbd.dev documentation, now search for ‘Username’. Please do also note some ZBD API endpoints are still using gamertag
in the URL.
ZBD Username Charge API
While you can use the Send Bitcoin to ZBD Username endpoint to make a direct payment to a ZBD user, if you want to create a regular Lightning Network payment request / Charge QR code for that given user, you can do so using the Create Charge for ZBD Username endpoint.
In order to request Charges from a ZBD Username you just need to make a simple API call with a payload like the example below.
curl --location --request POST 'https://api.zebedee.io/v0/gamertag/charges' \
--header 'Content-Type: application/json' \
--header 'apikey: API_KEY_HERE' \
--data-raw '{
"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"
}
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.
Multiplayer Commerce through ZBD Username Charges
For App or Game Developers that wish to provide a more robust commerce experience for their users and gamers, requesting an invoice from ZBD Usernames 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 Username, you can ensure that the payment is made to the correct user, and that the payment has truly settled.
1. 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:
2. ZBD Username Charges
You can use the above endpoint to create a Charge from Bob’s ZBD Username, 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!
3. Project Wallet as Escrow
Alternatively you could rely on the Project’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.
Once payment is settled, you can use the Send Bitcoin to ZBD Username 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.
Was this page helpful?