Skip to main content

​
Base URL

Paths are the same in both environments. Keys are issued per environment, so a sandbox key only works on the sandbox host and a production key only works in production. To go live, change the base URL and the key.

​
Authentication

Send your API key in the x-api-key header. The key identifies your organization, so there’s no publisher or organization ID in any path. Call these endpoints from your server only, so the key never reaches a browser or game client. Where an endpoint is scoped to a project, pass an optional project_id: in the body for writes, and in the query for reads.

​
Endpoints

The credit, debit, earnings, and transaction endpoints are only for programs where ZBD tracks earnings. See How Payouts Work.

​
Idempotency

Every call that moves value takes an Idempotency-Key header with a UUID you generate. Retrying with the same key returns the original result instead of acting twice. Use a new key for each new operation, and the same key when retrying one.

​
Responses

Every response uses the same wrapper:
On failure, data is null and error is { code, message, details? }. code is a stable string you can branch on, and the HTTP status matches it. Nothing is debited on any 4xx.

​
Errors

These codes are shared by every endpoint. A feature that isn’t enabled always returns 403 feature_not_enabled, never 404.

​
Conventions

  • Amounts are always whole numbers in the currency’s smallest unit. Each currency has a precision that says how many decimal places to show: 2 for USD, so 100 is $1.00, and 0 for a currency like JPY, so 100 is ¥100.
  • user_id is the ZBD user ID returned by Create a User.
  • Tracing. Send an X-Request-Id header on any call to make it easier to trace with support.