Overview

High-level capabilities

What this API can do:

Catalog browsing
Product types, categories, and products to build your store UI.

Ordering
Create and track orders. direct_top_up products support a customer_account payload.

Balances & funding
Read current balances and inspect deposit history.

Health monitoring
Quick liveness probe for uptime checks via /health.

Key facts

INFO

Core conventions you must follow across all endpoints:

Auth: API key in the Authorization header (raw key, no Bearer).

Idempotency: send Idempotency-Key on order creation to safely retry.

Money:

DecimalAmount = major units as string (for example, "12.50"),

amount_minor = minor units (for example, cents).

IDs:

agent_id is a UUID,

product and order IDs follow the OpenAPI specification.

Integration flow (end-to-end)

1. Provision & authenticate

Obtain an API key per environment (sandbox / production).

Send it in the Authorization header for all protected endpoints.

2. Sync catalog

Call:

GET /product-types

GET /product-categories

GET /products

Use the response to build your store UI.

3. Show balances

Call GET /balance before checkout.

Display available amounts per currency to the user or operations team.

Block purchase if balance is insufficient.

4. Create order

POST /orders with Idempotency-Key.

For top-ups, include:

topup_request.customer_account

topup_request.amount

Persist:

order.id

external_ref

idempotency_key

5. Track order

Poll GET /orders or GET /orders/{orderId} until the order is completed or failed.

Deliver order_content (for example, voucher code) to the buyer when ready.

6. Reconcile deposits

Use GET /deposits to align funding events with your internal ledger.

Alert when balances approach defined thresholds.

7. Monitor health

Call GET /health and feed the result into your uptime monitoring.

Use failures to trigger alerts and backoff logic.

Endpoint map

Catalog

Orders

Balances & deposits

System

GET /agent/{agent_id}/product-types
GET /agent/{agent_id}/product-categories
GET /agent/{agent_id}/products
GET /agent/{agent_id}/products/{productId}

Critical patterns

Idempotent orders

Generate a unique Idempotency-Key per business order attempt:

Reuse the same key when retrying the same payload.

Safe to retry until you receive a definitive result.

Persist idempotency_key alongside your internal order identifier.

Balance protection

Always pre-check GET /balance before POST /orders.

If you receive 400 insufficient_balance, do not retry blindly:

wait for a new deposit to post,

then retry the same order with the same Idempotency-Key if appropriate.

Direct top-up payloads

For direct_top_up products:

Include a topup_request object with:

customer_account (vendor-specific fields),

amount.

Persist vendor identifiers contained in order_content (for example, vendor_order_id) for later reconciliation or support.

Reference payloads

Create order (direct top-up) request

Order response (pending)

Balance snapshot

Deposit record

Error model

{
  "product_id": 456,
  "external_ref": "INV-1001",
  "topup_request": {
    "amount": "10.00",
    "customer_account": {
      "steam_login": "player123",
      "email": "user@example.com"
    }
  },
  "quantity": 1,
  "test": false
}

Operational checklist

CHECK

Operational best practices before going live:

Always send Idempotency-Key on order creation; retry with the same payload and key.

Cache catalog data (product-types, product-categories, products) and refresh on a schedule or on change.

Set alerts on low balances; expose insufficient_balance errors to finance/ops teams.

Log and persist:

order.id

external_ref

order_content (for example, voucher codes, vendor IDs)
for delivery and support.

Monitor /health and implement backoff or circuit-breaking on repeated failures.

High-level capabilities#

Key facts#

Integration flow (end-to-end)#

Endpoint map#

Critical patterns#

Reference payloads#

Operational checklist#

High-level capabilities

Key facts

Integration flow (end-to-end)

Endpoint map

Critical patterns

Reference payloads

Operational checklist