Platform Overview

The full-stack payment platform purpose-built for gaming

ZBD is a bi-directional payment platform for game studios. It handles everything from paying players real money for in-game achievements to processing purchases and managing virtual currency — all while keeping studios completely out of PII and PCI scope. Built on regulatory licenses (US Money Transmitter Licenses + EU MiCAR/EMI) and micropayment economics that make sub-cent transactions viable, ZBD enables product categories that are structurally impossible on traditional payment rails.

Three Workstreams

Competitive Landscape

The Compound Moat

"Three things that compound together: (1) Regulatory licenses that took years and millions — competitors need 2+ years just to get started. (2) The only bi-directional payment platform purpose-built for gaming — Xsolla does pay-in, Tipalti does pay-out, ZBD does both. (3) Micropayment economics that enable use cases structurally impossible on traditional rails — you can't reward a player $0.02 through Stripe. No single piece is unassailable, but together they create a 3+ year head start."

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.zbdpay.com/v1/project/balance

Base URL

https://api.zbdpay.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 ZBD'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: ZBD handles FX conversion, disclosed via fxRate and fxFee fields
• Tournament entry fees and prizes must be in a single currency per tournament

Users & Identity

Registration, KYC verification, and user management

Endpoints

KYC Tiers

Tiered verification minimizes friction and maximizes conversion. Players earn first, verify only at cash-out.

User Object

{
  "id": "usr_a1b2c3d4",
  "externalId": "player_12345",
  "email": "player@example.com",
  "country": "US",
  "kycStatus": "approved",
  "kycTier": 2,
  "createdAt": "2026-03-20T10:00:00Z",
  "metadata": {}
}

Webhooks

Payout to Bank

Trigger bank account payouts on behalf of players

Bank Account Linking

Before a payout can be created, the player must link a bank account through ZBD's hosted Plaid flow.

Bank Account Object (tokenized)

{
  "id": "ba_x9y8z7",
  "userId": "usr_a1b2c3d4",
  "institutionName": "Chase",
  "accountType": "checking",
  "last4": "6789",
  "status": "verified",
  "createdAt": "2026-03-20T12:00:00Z"
}

Developer never sees: full account number, routing number, holder name, or any PII.

Payout Endpoints

Create Payout Request

POST /v1/payouts
{
  "userId": "usr_a1b2c3d4",
  "bankAccountId": "ba_x9y8z7",
  "amount": 5000,
  "currency": "usd",
  "description": "Tournament winnings - March 2026",
  "internalId": "game_match_789",
  "metadata": {
    "gameId": "battle-royale-2",
    "matchId": "match_789",
    "reason": "tournament_prize"
  }
}

Payout Object

{
  "id": "po_m4n5o6p7",
  "userId": "usr_a1b2c3d4",
  "bankAccountId": "ba_x9y8z7",
  "amount": 5000,
  "currency": "usd",
  "status": "processing",
  "description": "Tournament winnings - March 2026",
  "internalId": "game_match_789",
  "method": "ach",
  "estimatedArrival": "2026-03-22T00:00:00Z",
  "failureCode": null,
  "failureMessage": null,
  "createdAt": "2026-03-20T14:00:00Z",
  "completedAt": null,
  "metadata": {
    "gameId": "battle-royale-2",
    "matchId": "match_789",
    "reason": "tournament_prize"
  }
}

Payout Status Lifecycle

Failure Codes

Webhooks

Code Samples — Node.js

Create a Payout

import ZBD from '@zbd/node';

const client = new ZBD('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 ZBD from '@zbd/node';

const app = express();
const client = new ZBD('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-zbd-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');
});

Wallet Loading

Allow players to fund a ZBD wallet from a linked bank account

Endpoints

Wallet Object

{
  "userId": "usr_a1b2c3d4",
  "balance": 15000,
  "currency": "usd",
  "status": "active",
  "dailyLoadLimit": 50000,
  "dailyLoadRemaining": 35000,
  "updatedAt": "2026-03-20T15:00:00Z"
}

Create Wallet Load Request

POST /v1/users/{userId}/wallet/load
{
  "bankAccountId": "ba_x9y8z7",
  "amount": 2500,
  "currency": "usd",
  "internalId": "load_session_456"
}

Wallet Load Object

{
  "id": "wl_q1r2s3t4",
  "userId": "usr_a1b2c3d4",
  "bankAccountId": "ba_x9y8z7",
  "amount": 2500,
  "currency": "usd",
  "status": "pending",
  "internalId": "load_session_456",
  "createdAt": "2026-03-20T15:30:00Z",
  "completedAt": null
}

Load Status Lifecycle

SDK vs. Developer Responsibility

Webhooks

Error Codes

Checkout (Web Store)

Hosted checkout widget for direct-to-consumer purchases, bypassing app store fees

Endpoints

Create Checkout Session

POST /v1/checkout/sessions
{
  "userId": "usr_a1b2c3d4",
  "lineItems": [
    {
      "name": "1000 Gold Coins",
      "description": "In-game currency pack",
      "amount": 999,
      "currency": "usd",
      "quantity": 1,
      "metadata": { "sku": "gc_1000", "type": "virtual_currency" }
    }
  ],
  "successUrl": "https://yourgame.com/purchase/success?session={SESSION_ID}",
  "cancelUrl": "https://yourgame.com/purchase/cancel",
  "internalId": "purchase_abc123",
  "metadata": { "gameId": "battle-royale-2" }
}

Checkout Session Object

{
  "id": "cs_v1w2x3",
  "userId": "usr_a1b2c3d4",
  "status": "completed",
  "paymentMethod": "card",
  "amountTotal": 999,
  "currency": "usd",
  "lineItems": [ ... ],
  "internalId": "purchase_abc123",
  "createdAt": "2026-03-20T17:00:00Z",
  "completedAt": "2026-03-20T17:01:30Z"
}

Checkout Flow

Platform ToS Strategy

Webhooks

Virtual Currency

Convertible virtual currency ledger for in-game economies, backed by ZBD as system of record

Currency Configuration

Currency Object

{
  "id": "cur_g1h2i3",
  "name": "Gold Coins",
  "symbol": "GC",
  "conversionRate": 100,
  "conversionUnit": "usd_cents",
  "conversionDirection": "to_fiat",
  "minConversion": 1000,
  "maxConversionPerDay": 50000,
  "status": "active",
  "createdAt": "2026-03-01T00:00:00Z"
}

conversionRate: 100 means 100 Gold Coins = $1.00 USD. Developer defines earn rate in-game; ZBD defines the cash-out rate.

Ledger Endpoints

Credit Request (player earns coins)

POST /v1/ledger/credit
{
  "userId": "usr_a1b2c3d4",
  "currencyId": "cur_g1h2i3",
  "amount": 500,
  "reason": "match_victory",
  "internalId": "match_789_reward",
  "metadata": {
    "matchId": "match_789",
    "placement": 1
  }
}

Ledger Transaction Object

{
  "id": "txn_k5l6m7",
  "type": "credit",
  "userId": "usr_a1b2c3d4",
  "currencyId": "cur_g1h2i3",
  "amount": 500,
  "balanceAfter": 3200,
  "reason": "match_victory",
  "internalId": "match_789_reward",
  "createdAt": "2026-03-20T16:00:00Z",
  "metadata": {
    "matchId": "match_789",
    "placement": 1
  }
}

Conversion Request (player cashes out)

POST /v1/conversions
{
  "userId": "usr_a1b2c3d4",
  "currencyId": "cur_g1h2i3",
  "amount": 2000,
  "destination": "wallet"
}

Converts 2000 Gold Coins to $20.00 USD, credited to user's ZBD wallet. From there, the player can use the Payout to Bank API to withdraw.

Key Design Decisions

Webhooks

Error Codes

Tournaments

Skill-based tournaments with buy-in escrow, automated prize distribution, and geo-fencing

Endpoints

Create Tournament

POST /v1/tournaments
{
  "name": "Friday Night Showdown",
  "gameId": "battle-royale-2",
  "entryFee": 500,
  "currency": "usd",
  "maxPlayers": 100,
  "minPlayers": 10,
  "prizeStructure": [
    { "rank": 1, "percentage": 50, "label": "1st Place" },
    { "rank": 2, "percentage": 30, "label": "2nd Place" },
    { "rank": 3, "percentage": 20, "label": "3rd Place" }
  ],
  "platformFeePercent": 10,
  "prizeSource": "entry_fees",
  "startsAt": "2026-03-21T20:00:00Z",
  "endsAt": "2026-03-21T22:00:00Z",
  "eligibleRegions": ["US_SKILL_GAMING"],
  "metadata": { "season": "3", "week": "12" }
}

Tournament Object

{
  "id": "trn_d4e5f6",
  "name": "Friday Night Showdown",
  "status": "active",
  "entryFee": 500,
  "currency": "usd",
  "currentPlayers": 47,
  "maxPlayers": 100,
  "minPlayers": 10,
  "prizePool": 21150,
  "prizeStructure": [ ... ],
  "prizeSource": "entry_fees",
  "startsAt": "2026-03-21T20:00:00Z",
  "endsAt": "2026-03-21T22:00:00Z",
  "eligibleRegions": ["US_SKILL_GAMING"],
  "createdAt": "2026-03-20T10:00:00Z",
  "metadata": { "season": "3", "week": "12" }
}

Tournament Status Lifecycle

Enter Tournament Flow

POST /v1/tournaments/{tournamentId}/enter
{
  "userId": "usr_a1b2c3d4",
  "internalId": "entry_player123_trn_d4e5f6"
}

Submit Results Flow

POST /v1/tournaments/{tournamentId}/results
{
  "rankings": [
    { "userId": "usr_a1b2c3d4", "rank": 1, "score": 9850 },
    { "userId": "usr_e5f6g7h8", "rank": 2, "score": 9200 },
    { "userId": "usr_i9j0k1l2", "rank": 3, "score": 8700 }
  ]
}

Prize Source Options

Escrow Model

Virtual Currency Tournaments

Geo-Fencing & Legal Framework

Webhooks

Error Codes

How Tournaments Use All Three Workstreams

Compliance Architecture

Data boundaries, KYC flows, and regulatory framework

Data Boundary Architecture

KYC Verification Sequence

Payout Compliance Flow

Sweepstakes Distinction (AB 831)

California AB 831 (effective Jan 1, 2026) bans sweepstakes casinos that use dual-currency models. Connecticut, New Jersey, Nevada, and Montana have passed similar laws.

API-level protection: The ledger API enforces that virtual currency can only be credited via POST /v1/ledger/credit (called by the developer's server, not purchased by the player). There is no endpoint for players to directly buy virtual currency with cash and then convert it back — that would be a sweepstakes model.

PII Edge Cases & Mitigations

How We Communicate Compliance to Developers

Player Journeys

The same platform from the player's perspective

Journey 1: Casual Player Earns a Reward

Journey 2: Competitive Player Enters a Tournament

Journey 3: Player Buys Items via Web Store

Why the Player Perspective Matters for API Design

Roadmap

6-month phased rollout, each phase building on the infrastructure of the last

Phase Gates

Execution Risks

Success Metrics

Measuring DX quality, integration adoption, and commercial outcomes

DX Quality

Integration Adoption

Commercial Outcomes