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. A user belongs to your organization, so the same user and balances work across every one of your games. 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

Users cash out in the widget, and each cash out creates a payout you can read and reconcile. Projects and currencies are set up in the Publisher Portal, and the API reads them. Projects, users, sessions, disclosures, balances, transactions, payouts, and webhooks are the same endpoints in Embedded Payouts, so one integration covers both.

​
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 moves 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. For your own currency, the precision is whatever you set. See Get a Currency.
  • currency is the field name for a currency code everywhere, for both fiat and your own currencies.
  • 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.