POST
/
v0
/
gamertag
/
charges
curl --request POST \
  --url https://api.zebedee.io/v0/gamertag/charges \
  --header 'Content-Type: <content-type>' \
  --header 'apikey: <apikey>' \
  --data '{
  "amount": "<string>",
  "gamertag": "<string>",
  "description": "<string>",
  "expiresIn": 123,
  "internalId": "<string>",
  "callbackUrl": "<string>"
}'
{
  "success": true,
  "data": {
    "id": "chrg_2n4f8gu3nf",
    "unit": "msats",
    "status": "CHARGE_PENDING",
    "amount": "1000000",
    "createdAt": "2024-03-14T19:40:13.880Z",
    "internalId": "deposit_1710441613880",
    "callbackUrl": "https://yourapp.com/webhooks/charge",
    "description": "Add funds to wallet",
    "invoiceRequest": "lnbc10u1pjp8wlxpp5xm2la0q5kqw8w85u4kkz8vnwed8kuhn8d5e2qc8xu3j3jk3vy36sdps2fjhzat9wd6xjmn8yppksctjvajjqmr0wfjjqen0wgsywatvdssyyctdv4e8gct8cqzpgxqzjcsp5e7defq66t8svrpqr37weqpxv6fhskmm4h69hx5qhngrmqxzr0qrq9qyyssqtkxkpqd8hll3fmn7v6mfs7u3pxh5j4mtxp8p8tnrch4nqjm8jt0xm9td9klvlshxkkahnvc2yvrt9l8438u8xz2qc6qzlf9kr46y7cp6lvh0t",
    "invoiceExpiresAt": "2024-03-14T19:50:13.859Z",
    "invoiceDescriptionHash": null
  }
}

Create Lightning payment requests (invoices) that users can pay to add funds or make purchases. Perfect for user-initiated transactions like deposits, premium upgrades, or marketplace purchases.

Lightning Invoices - This creates a standard Lightning Network invoice that can be paid from any Lightning wallet, not just ZBD.

​
Use Cases

Marketplace

User-to-user transactions between ZBD users

Tournament Entry

Collect entry fees with payment proof

​
Configuration

​
Header Parameters

​
apikey
string
required

Your ZBD Project API Key

​
Content-Type
string
required

Content Type (must be application/json)

​
Body Parameters

​
amount
string
required

Amount to charge in millisatoshis

Common amounts:

  • "10000" = 10 sats (~$0.005)
  • "100000" = 100 sats (~$0.05)
  • "1000000" = 1,000 sats (~$0.50)
  • "10000000" = 10,000 sats (~$5.00)
​
gamertag
string
required

The user’s gamertag who will receive credit when paid

Note: The invoice can be paid by anyone, but this gamertag gets credited

​
description
string

Description shown in Lightning wallets (max 150 chars)

Examples:

  • “Deposit to GameApp wallet”
  • “Premium upgrade - 30 days”
  • “Tournament entry fee”
​
expiresIn
number

Invoice expiration time in seconds (default: 600 = 10 minutes)

Range: 60 to 3600 (1 minute to 1 hour)

​
internalId
string

Your internal reference ID for tracking

Use for linking to your database records

​
callbackUrl
string

Webhook URL for payment notifications

ZBD will POST to this URL when invoice is paid

​
Response

{
  "success": true,
  "data": {
    "id": "chrg_2n4f8gu3nf",
    "unit": "msats",
    "status": "CHARGE_PENDING",
    "amount": "1000000",
    "createdAt": "2024-03-14T19:40:13.880Z",
    "internalId": "deposit_1710441613880",
    "callbackUrl": "https://yourapp.com/webhooks/charge",
    "description": "Add funds to wallet",
    "invoiceRequest": "lnbc10u1pjp8wlxpp5xm2la0q5kqw8w85u4kkz8vnwed8kuhn8d5e2qc8xu3j3jk3vy36sdps2fjhzat9wd6xjmn8yppksctjvajjqmr0wfjjqen0wgsywatvdssyyctdv4e8gct8cqzpgxqzjcsp5e7defq66t8svrpqr37weqpxv6fhskmm4h69hx5qhngrmqxzr0qrq9qyyssqtkxkpqd8hll3fmn7v6mfs7u3pxh5j4mtxp8p8tnrch4nqjm8jt0xm9td9klvlshxkkahnvc2yvrt9l8438u8xz2qc6qzlf9kr46y7cp6lvh0t",
    "invoiceExpiresAt": "2024-03-14T19:50:13.859Z",
    "invoiceDescriptionHash": null
  }
}

​
Response Fields

FieldTypeDescription
idstringUnique charge identifier
statusstringAlways “CHARGE_PENDING” initially
amountstringAmount in millisatoshis
invoiceRequeststringLightning invoice (payment request)
invoiceExpiresAtstringWhen invoice expires (ISO 8601)
createdAtstringCreation timestamp
internalIdstringYour reference ID
callbackUrlstringYour webhook URL

Universal Compatibility - These invoices work with any Lightning wallet, not just ZBD. Users can pay from Cash App, Strike, Phoenix, or any other Lightning-enabled service.