POST
/
v0
/
gamertag
/
send-payment
curl --request POST \
  --url https://api.zebedee.io/v0/gamertag/send-payment \
  --header 'Content-Type: <content-type>' \
  --header 'apikey: <apikey>' \
  --data '{
  "amount": "<string>",
  "gamertag": "<string>",
  "description": "<string>"
}'
{
  "success": true,
  "data": {
    "id": "49cccd62-b686-4057-9f44-f492bd54ac39",
    "status": "settled",
    "transactionId": "78fb6474-d791-47a1-bda1-a4b9023898c0",
    "receiverId": "ec9b38d5-b126-4307-9d1e-8aa0dfab5d7e",
    "amount": "1000000",
    "comment": "Achievement unlocked! 🏆",
    "settledAt": "2024-03-19T21:42:54.993Z"
  },
  "message": "Payment done."
}

Send instant Bitcoin rewards to any ZBD user. Perfect for achievements, milestones, referrals, or any action you want to incentivize.

Synchronous API - Unlike other payment endpoints, rewards are delivered instantly. The API response confirms success or failure immediately - no callbacks needed.

​
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

Reward amount in millisatoshis (1 sat = 1000 msats)

Common amounts:

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

The recipient’s ZBD Gamertag (case-insensitive)

Examples: "player123", "bitcoingamer", "speedrunner42"

​
description
string

Message shown to the recipient (max 150 characters)

Best practices:

  • Be specific: “Level 10 achievement unlocked!”
  • Add emojis: “Great job! 🎯”
  • Include context: “Tournament prize - 3rd place”
{
  "success": true,
  "data": {
    "id": "49cccd62-b686-4057-9f44-f492bd54ac39",
    "status": "settled",
    "transactionId": "78fb6474-d791-47a1-bda1-a4b9023898c0",
    "receiverId": "ec9b38d5-b126-4307-9d1e-8aa0dfab5d7e",
    "amount": "1000000",
    "comment": "Achievement unlocked! 🏆",
    "settledAt": "2024-03-19T21:42:54.993Z"
  },
  "message": "Payment done."
}

​
Error Responses

{
  "success": false,
  "message": "User not found with provided gamertag"
}

​
Response Fields

FieldTypeDescription
idstringUnique payment ID
statusstringAlways “settled” for successful payments
transactionIdstringZBD transaction ID for tracking
receiverIdstringRecipient’s ZBD User ID
amountstringAmount sent in millisatoshis
commentstringYour description as seen by recipient
settledAtstringISO 8601 timestamp of delivery

​
Common Patterns

​
Reward with Limits

// Implement daily reward limits
async function sendDailyReward(gamertag, amount) {
  const dailyLimit = 10000; // 10k sats per day
  const userTotal = await getDailyTotal(gamertag);
  
  if (userTotal + amount > dailyLimit) {
    throw new Error(`Daily limit exceeded. ${dailyLimit - userTotal} sats remaining.`);
  }
  
  const result = await sendReward({
    gamertag,
    amount: amount * 1000,
    description: "Daily challenge complete!"
  });
  
  await updateDailyTotal(gamertag, userTotal + amount);
  return result;
}

​
Try It Out

Ready to send your first reward? Use our API playground on the right to test with your API key.

Instant Delivery - Rewards appear in the user’s ZBD App immediately. They’ll get a push notification if they have the app installed!