Developer Docs
Case Study Brief API Reference Architecture Case Studies Research / Planning

Payout to Bank

Developers trigger bank account payouts on behalf of players. DBZ handles banking rails, compliance screening, and settlement.

What this workstream is

Money flows from the studio to the player's bank account. When a player earns a reward — wins a ranked match, completes a challenge, finishes a tournament — the game server validates the event and calls DBZ's API to initiate a bank payout. The player never interacts with DBZ directly; they see "+$0.25 earned" in-game and can withdraw to their bank whenever they choose.

The studio controls when and why players get paid (business logic). DBZ handles how the money moves (banking rails, KYC screening, tax reporting, compliance). This separation is the core design principle.

Who triggers what

ActorResponsibilityExample
Game ServerValidates the game event that triggers a payoutPlayer wins match → server confirms score, checks anti-cheat
Studio BackendCalls POST /v1/payouts with amount, userId, reasonBackend sends payout request: $0.25 to user_abc123 for "ranked_win"
DBZKYC check, sanctions screening, fraud detection, ACH transferVerifies user is Tier 1+, screens against OFAC, initiates ACH
PlayerInitiates withdrawal (within game UI), completes KYC (once)Taps "Withdraw $14.75" in rewards menu → links bank account

Developer integration

The developer's actual integration is two steps. Player onboarding (registration, KYC, bank linking) is handled almost entirely by DBZ's hosted UIs.

What the developer codes

1

Create payout

Call POST /v1/payouts with userId, amount, and Idempotency-Key. DBZ returns the payout object with status: "pending". That's it — one API call.

2

Handle the webhook

DBZ sends payout.completed or payout.failed to your webhook endpoint. Verify the X-DBZ-Signature, update your records, and notify the player. If the failure is retryable, retry with the same idempotency key.

What DBZ handles automatically

The developer triggers these flows with a single API call each, but DBZ does all the heavy lifting through hosted UIs. The developer never builds verification screens or bank linking forms.

Player registration

Developer calls POST /v1/users with the player's game ID. DBZ returns a userId. One call, no PII.

Or use OAuth2 "Login with DBZ" to link an existing gamertag — zero backend work.

KYC verification

Developer calls POST /v1/users/{id}/verify. DBZ returns a URL. Player completes verification in DBZ's hosted UI. Developer receives a webhook when approved.

DBZ auto-determines the required tier based on payout volume. Developer never decides what to collect.

Bank account linking

Developer calls POST /v1/users/{id}/bank-accounts. DBZ returns a Plaid-hosted link URL. Player authenticates with their bank. Developer gets back a tokenized bankAccountId.

No routing numbers, no account numbers — just last4 and bankName.

KYC/AML flow

Tiered verification minimizes friction. Players earn freely with no limits — KYC only triggers when they want to withdraw real money. Each tier unlocks higher payout limits, aligned with federal regulations.

TierRequiresPayout LimitWho CollectsTriggerLegal Basis
Tier 0Email onlyUnlimited earning, no withdrawalNobodyAutomatic at registrationNo cash-out = no money transmission
Tier 1Email + phone (SMS)$300/month withdrawalDBZ hosted UIFirst withdrawal attemptAligned with Venmo/Cash App unverified limits; well below $3K Travel Rule
Tier 2Full name + DOB + address$2,999 cumulative withdrawalDBZ hosted UICumulative payouts approach $3,000Stays below FinCEN Travel Rule threshold (31 CFR 1010.410)
Tier 3SSN/TIN (W-9) + government ID$20,000/yearDBZ hosted UICumulative payouts exceed $2,999 or approach 1099 thresholdEnables 1099-MISC filing; satisfies Travel Rule ID verification
Tier 4Government photo ID + address proofUnlimitedDBZ hosted UIHigh-volume payouts or platform risk flagsFull KYC; satisfies all federal and state requirements

Key design decision: Tier 0 allows unlimited earning with no verification — just like Skillz and Mistplay. Players accumulate rewards freely and only hit KYC when they want to cash out. This removes the friction that kills adoption. The developer calls the same endpoint (POST /v1/users/{userId}/verify) regardless of tier — DBZ auto-determines the required verification based on payout volume.

Regulatory anchors

  • $3,000 Travel Rule (31 CFR 1010.410) — the key federal threshold. Above this, name + address + ID number are required.
  • 1099-MISC at $2,000 (starting 2026, per OBBBA) — triggers W-9/SSN collection for tax reporting on gaming prizes.
  • SAR filing at $2,000+ — suspicious activity reports required regardless of KYC tier.
  • MSBs are not subject to CIP — unlike banks, money transmitters don't have a Customer Identification Program requirement. KYC thresholds are risk-based, not prescribed.

PII and compliance boundary

Zero PII — Developer never handles sensitive data

What the developer sees

  • Tokenized IDs: userId, bankAccountId, payoutId
  • Masked bank info: last4: "6789", bankName: "Chase"
  • KYC tier + status: tier: 2, status: "approved"
  • Payout lifecycle: pending → in_transit → completed
  • Failure codes: insufficient_funds, account_closed
  • Aggregated metrics: total payouts, success rate

What DBZ handles (developer never sees)

  • Full bank account + routing numbers
  • SSN / government ID numbers
  • Identity documents (photos, selfies)
  • OFAC / sanctions screening results
  • AML transaction monitoring
  • IRS 1099-MISC tax reporting ($2K threshold starting 2026)
  • PCI compliance scope

This architecture means the developer is never a data processor for financial PII. DBZ acts as the data controller and processor. The developer's compliance burden is limited to: (1) validating that game events are legitimate before triggering payouts, and (2) storing the tokenized userId/bankAccountId mapping.

Error states and retry logic

Payout failures fall into two categories. The retryable flag tells the developer exactly what to do.

Failure CodeMeaningRetryableDeveloper Action
insufficient_fundsProject wallet balance too lowYesTop up project wallet, then retry
bank_timeoutReceiving bank didn't respondYesRetry with exponential backoff
kyc_requiredUser needs higher KYC tierYesPrompt player to complete verification, retry after
rate_limitedToo many payout requestsYesBack off and retry after Retry-After header
account_closedPlayer's bank account is closedNoAsk player to link a new bank account
invalid_accountBank account details are wrongNoAsk player to re-link bank account
sanctions_matchUser flagged by OFAC screeningNoDo not retry. Contact DBZ support.
fraud_detectedSuspicious payout patternNoDo not retry. Review flagged user.

Retry strategy

For retryable failures, use exponential backoff: 1 min → 5 min → 30 min → 2 hours. Stop after 4 attempts. Always reuse the same Idempotency-Key to prevent duplicate payouts.

Webhook delivery also uses exponential backoff (1 min → 5 min → 30 min → 2 hr → 24 hr). If your endpoint is down, DBZ retains events for 72 hours and replays them via POST /v1/webhooks/replay.

For the full API reference (endpoint schemas, request/response objects, status lifecycle diagrams, and code samples), see Payout to Bank API Reference.

Wallet Loading

Players buy virtual currency with real money. The wallet holds virtual currency, not USD — a critical regulatory design choice.

What this workstream is

Money flows from the player's bank account into virtual currency on DBZ's ledger. The player links their bank (via Plaid), purchases virtual currency (e.g., PokeCoins, Halo Credits), and uses it for in-game purchases, tournament buy-ins, or gifting. This is the "on-ramp" — converting real money into the game economy.

This also powers the web store checkout flow: players buy items directly from the studio's web store (bypassing platform fees at 3% vs 30%), paying with their linked bank account or existing virtual currency balance.

Why the wallet holds virtual currency, not USD

This is a deliberate regulatory design choice with major compliance implications:

ApproachRegulatory ClassificationCompliance Burden
Wallet holds USDMoney transmission + stored valueMTL in 47 states, Regulation E (consumer protection), FDIC considerations, full custodial liability
Wallet holds virtual currencyDigital goods purchase (in) + money transmission (out only)MTL only needed for the cash-out direction — which DBZ already holds

This is why V-Bucks, Robux, and every major game currency is structured as a one-way purchase — it avoids money transmission on the buy side. DBZ's innovation is adding the cash-out direction (Workstream 1), which requires the MTLs they already have. The buy side is just a normal digital goods transaction.

How the three workstreams form a loop

USD → Wallet Loading → Virtual Currency → Gameplay → Virtual Currency → Payout → USD
  • Workstream 2 (this one): USD → Virtual Currency (buying credits)
  • Workstream 3: Virtual Currency ledger (earning, spending, transferring)
  • Workstream 1: Virtual Currency → USD (cashing out to bank)

What the SDK handles vs. what the developer handles

The developer never touches payment processing. DBZ's hosted UI handles all sensitive flows.

DBZ handles

  • Bank account linking (Plaid hosted UI)
  • ACH debit initiation and settlement
  • PCI-compliant card capture
  • Checkout widget rendering
  • USD → virtual currency conversion
  • Fraud scoring and velocity checks

Developer handles

  • Showing "Buy Credits" button in game UI
  • Creating a checkout session with amount/items
  • Handling checkout.completed webhook
  • Displaying updated virtual currency balance

What's returned to the developer

After a purchase completes, the developer receives the updated virtual currency balance — no financial PII:

{
  "userId": "usr_abc123",
  "currency": "pokecoin",
  "balance": 1500,
  "lastTransaction": {
    "type": "purchase",
    "amountCredited": 1000,
    "amountChargedCents": 1000,
    "fundingSource": {
      "type": "bank_account",
      "bankAccountId": "ba_x7y8z9",
      "last4": "6789",
      "bankName": "Chase"
    },
    "status": "completed"
  }
}

The developer sees the virtual currency balance (1,500 PokeCoins), the amount credited (1,000), and a masked funding source. No routing numbers, no account numbers, no PII.

How sensitive bank data stays inside DBZ's perimeter

Zero PII — Developer never touches bank credentials

Bank linking: Developer calls the API → DBZ returns a linkUrl → player authenticates directly with their bank via Plaid's hosted UI → bank credentials never transit through the developer's servers → DBZ stores the tokenized access and returns a bankAccountId.

Purchases: Developer creates a checkout session → DBZ renders a hosted payment widget → player pays from linked bank or card → DBZ converts USD to virtual currency on the ledger → developer receives a webhook with the credited amount. Card numbers and bank details never reach the developer.

Web store: Players buy items (skins, battle passes) directly from the studio's web store. Same hosted checkout flow. Studio pays ~3% processing fee vs. 30% platform fee through Xbox/PlayStation/Steam. The player can pay with USD or spend existing virtual currency balance.

Purchase failure handling

FailureWhat HappensDeveloper Action
nsfPlayer's bank account has insufficient fundsShow "Payment failed" — player retries or uses a different funding source
bank_connection_expiredPlaid token expired (typically after 90 days)Prompt player to re-link bank account
card_declinedPlayer's card was declinedShow "Card declined" — player retries with different card
velocity_limitPlayer exceeded purchase limits (fraud protection)Show "Try again later" — limits reset after cooling period

All purchase failures are non-destructive — no virtual currency is credited until the payment fully settles. The developer simply shows the error and lets the player retry.

For the full API reference, see Wallet Loading API Reference and Checkout API Reference.

Virtual Currency

The in-game ledger that tracks earning, spending, and cashing out. Includes skill-based tournaments with real-money stakes.

What this workstream is

Once a player has virtual currency (from Wallet Loading or gameplay rewards), this workstream manages what they do with it: earn more through gameplay, spend on in-game items, transfer to other players, enter tournaments, and cash out to real money.

The key differentiator from V-Bucks or Robux: this currency is convertible. Value flows both ways. When a player cashes out, POST /v1/ledger/convert internally triggers the Payout to Bank flow — the same KYC tiers and compliance apply.

How virtual currency moves

Four operations after the player has credits (buying credits is handled by Wallet Loading):

DirectionHow it worksExampleEndpoint
EarnStudio credits player via API after game eventWin match → +50 PokeCoinsPOST /v1/ledger/credit
SpendPlayer buys in-game item, debited from ledger500 PokeCoins → fighter skinPOST /v1/ledger/debit
TransferMove credits between playersGift 100 PokeCoins to a friendPOST /v1/ledger/transfer
Cash outConvert VC to USD, triggers payout flow1,000 PokeCoins → $8.50 (after 15% fee)POST /v1/ledger/convert

Cash-out triggers the Payout to Bank flow

When a player calls POST /v1/ledger/convert, DBZ internally: (1) debits the VC from the player's ledger, (2) applies the studio's conversion fee, (3) checks the player's KYC tier, (4) initiates a bank payout via Workstream 1. The developer doesn't need to orchestrate this — one API call handles the full conversion-to-payout chain.

If the player hasn't completed KYC yet, the response includes a verificationUrl — same hosted flow as Workstream 1.

Why a conversion fee?

The cash-out fee (set by the studio, typically 10-20%) serves two purposes: (1) it discourages players from immediately converting earned credits to cash, keeping currency circulating in the game economy, and (2) it creates a revenue stream for the studio on conversions. Players know the fee upfront — transparency builds trust.

Tournaments

Skill-based competitive events where players stake virtual currency (or real money) for a prize pool. DBZ holds funds in escrow and auto-distributes prizes.

How tournaments work

1

Studio creates tournament — sets buy-in (e.g., 500 PokeCoins), prize structure (50%/30%/15%/5% platform fee), max players, and schedule.

2

Players enter — buy-in is debited from their VC balance and held in DBZ escrow. If paying with USD, it converts to VC first (Workstream 2).

3

Tournament plays out — the game runs matches. DBZ has no involvement in gameplay.

4

Studio submits results — calls POST /v1/tournaments/{id}/results with rankings. DBZ auto-distributes prizes to winner VC balances. Winners can cash out via Workstream 1.

Two funding models

  • Player-funded: Prize pool comes from player buy-ins. Studio pays nothing. (e.g., 50 players x 500 PokeCoins = 25,000 PokeCoin pool)
  • Studio-funded: Studio adds bonus prizes from their project wallet. Used for promotional events and player acquisition.

Legal framework

  • Skill-based, not gambling: Outcomes determined by player skill (trivia answers, match performance), not chance.
  • Geo-fenced: DBZ restricts tournaments to states where skill-based gaming is legal. Uses is-supported-region check.
  • Tax reporting: Prize winnings reported via 1099-MISC at $2K+ threshold (2026).

Anti-abuse protections

Convertible currency creates incentives for abuse. DBZ includes built-in protections:

ThreatProtection
Multi-accountingDevice fingerprinting + phone verification. Linked accounts flagged and frozen.
Bot farmingDBZ Shield: behavioral analysis detects non-human play patterns. Flagged accounts cannot cash out.
Collusion (tournament)Win-rate anomaly detection. Players who consistently lose to the same opponent are flagged.
Money launderingTransaction monitoring + SAR filing at $2K+. Velocity limits on conversions.
Refund abuseVC credited only after payment fully settles. ACH returns auto-claw back credited VC.

Why DBZ owns the ledger

DBZ owns and operates

  • The ledger database (double-entry bookkeeping)
  • Balance integrity and concurrency control
  • Conversion rate engine and fee calculation
  • Tournament escrow and prize distribution
  • Anti-abuse detection (DBZ Shield)
  • Compliance: convertible VC = money transmission
  • Tax reporting on conversions (1099-MISC at $2K+)

Developer controls

  • Currency name and display (e.g., "PokeCoins")
  • Buy rate (how many credits per dollar)
  • Cash-out fee percentage (0-25%)
  • When to credit/debit (game event logic)
  • Tournament structure (buy-in, prizes, schedule)
  • Whether to enable player-to-player transfers

Why this matters: Because the currency is convertible to real money, operating the ledger constitutes money transmission. This requires FinCEN MSB registration and state money transmitter licenses in 47+ US states — a $1-5M, 2-year process. By owning the ledger, DBZ absorbs this compliance burden. The studio gets a clean API without any licensing requirements.

For the full API reference (currency configuration, ledger schemas, tournament endpoints, and conversion flow details), see Virtual Currency API Reference and Tournaments API Reference.