Research & Deep Dives

Shared Infrastructure

Authentication, response formats, webhooks, and conventions shared across all endpoints

Authentication & Security

All requests are scoped to a project and authenticated via the apikey header.

curl -H "apikey: your_project_api_key" \
     https://api.dbzpay.com/v1/project/balance

Base URL

https://api.dbzpay.com/v1

Response Envelope

All responses use a standard envelope:

{
  "success": true,
  "message": "Human-readable status",
  "data": { ... }
}

Error Format

{
  "success": false,
  "message": "Human-readable error description",
  "error": {
    "code": "kyc_required",
    "type": "invalid_request",
    "param": "userId",
    "retryable": false
  }
}

Rate Limiting

All responses include rate limit headers. Default: 1,000 requests/minute per API key.

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 997
X-RateLimit-Reset: 1679529600

Sandbox vs. Production

Project Management

Webhook Management

This is an upgrade from DBZ's current per-request callbackUrl pattern to global webhook subscriptions (Stripe-style). The callbackUrl pattern is still supported for backwards compatibility.

Webhook Delivery Guarantees

Multi-Currency Support

All monetary amounts use the smallest unit of the specified currency (cents for USD, centimes for EUR). The currency field accepts ISO 4217 codes. Supported at launch: usd, eur.

• Wallet balances are per-currency (a user can hold both USD and EUR)
• Cross-currency payouts supported: DBZ handles FX conversion, disclosed via fxRate and fxFee fields
• Tournament entry fees and prizes must be in a single currency per tournament

Code Samples

Node.js SDK examples for common integration patterns

Create a Payout

import DBZ from '@dbz/node';

const client = new DBZ('your_api_key');

// Create a payout (idempotency key goes in the options, sent as header)
const payout = await client.payouts.create({
  userId: 'usr_a1b2c3d4',
  bankAccountId: 'ba_x9y8z7',
  amount: 5000,
  currency: 'usd',
  description: 'Tournament winnings',
  internalId: 'match_789',
  metadata: { gameId: 'battle-royale-2' }
}, {
  idempotencyKey: 'payout_unique_abc123'
});

console.log(payout.data.id);     // "po_m4n5o6p7"
console.log(payout.data.status); // "pending"

Webhook Handler

import express from 'express';
import DBZ from '@dbz/node';

const app = express();
const client = new DBZ('your_api_key');

// IMPORTANT: Use express.raw() to get the raw body for signature verification
app.post('/webhooks/zbd', express.raw({ type: 'application/json' }), async (req, res) => {
  const signature = req.headers['x-dbz-signature'];

  // req.body is a raw Buffer here — required for HMAC verification
  if (!client.webhooks.verify(req.body, signature)) {
    return res.status(401).send('Invalid signature');
  }

  const { event, data } = JSON.parse(req.body);

  switch (event) {
    case 'payout.completed':
      await markPayoutComplete(data.internalId, data.amount);
      break;
    case 'payout.failed':
      await handlePayoutFailure(data.internalId, data.failureCode);
      break;
    case 'payout.returned':
      // Bank returned funds — re-credit player's in-game balance
      await reverseGamePayout(data.internalId, data.amount);
      break;
  }

  res.status(200).send('OK');
});

Error Codes Reference

Comprehensive error and failure codes across all API endpoints

Payout to Bank — Failure Codes

Wallet Loading — Error Codes

Virtual Currency — Error Codes

Tournaments — Error Codes

Webhook Events Reference

All webhook event types across the platform

Users & Identity

Payout to Bank

Wallet Loading

Checkout

Virtual Currency

Tournaments

Regulatory Landscape

Legal framework for paying players real money

Why This Is Not Gambling

US gambling law requires three elements: Prize + Chance + Consideration. Remove any one element and the activity is not gambling. In the studio-funded rewards model (studio pays players from its own budget, no buy-in from players), there is no consideration — the player pays nothing to participate. This means it fails the gambling test in most jurisdictions.

The model is legally classified as a promotional reward / marketing incentive — similar to a loyalty program. It is not a sweepstakes (rewards are deterministic, not chance-based) and not employment income (though the IRS still taxes it).

Risk Matrix

Tournament Buy-Ins: Different Rules Apply

When players pay to enter a tournament, consideration IS present. The gambling test then hinges on whether outcomes are predominantly skill-based or chance-based:

DBZ's tournament API is designed for skill-based competitions only. The skillCertification field on tournament creation requires studios to attest that game outcomes are predominantly skill-determined. DBZ geo-fences tournaments with buy-ins out of the ~9 restricted states automatically.

Industry Precedent

Why this strengthens DBZ's value proposition: Compliance is the hardest part of paying players. A studio like 343 Industries doesn't want to deal with 1099s, age-gating, state-by-state geo-fencing, and COPPA audits. DBZ handles all of it behind the API — the studio calls POST /v1/payouts and DBZ manages the regulatory complexity. That's the moat.

Compliance Deep Dive

PII edge cases, payout compliance flow, and developer communication strategy

Payout Compliance Flow

PII Edge Cases & Mitigations

How We Communicate Compliance to Developers

Execution Risks

Key risks to the 6-month phased roadmap and mitigation strategies

Success Metrics

Measuring DX quality, integration adoption, and commercial outcomes

DX Quality

Integration Adoption

Commercial Outcomes