Cardzone B2B API
Merchant API for listing Cardzone digital products, looking up player profiles, creating wallet-funded orders, polling order status, checking wallet balance, and receiving webhooks.
For final fulfillment decisions, use the public API status returned by GET /api/b2b/v1/orders/{id} and by the b2b.order.status_changed webhook.
Order responses use a single 22-character Base58 order_id for polling, links, display, and support. Legacy full order UUIDs remain accepted as lookup inputs but are not returned. Store-scoped merchant_order_ref values also remain accepted by order lookup endpoints.
The endpoint paths and request shapes are the same for live and sandbox keys. Cardzone automatically adapts response behavior based on the key you send, so API consumers do not need a separate sandbox base URL.
Send your store API key as Authorization: Bearer <api_key> on every endpoint. See the Sandbox section for sandbox key behavior and scenario product IDs.
Live keys need an enabled postpaid wallet or a prepaid wallet balance of at least 100 SAR. Below that, live endpoints other than GET /balance, GET /orders/{id}, and POST /orders/{id}/cancel return 403 insufficient_store_wallet_balance with the minimum in error.details (POST /player_profiles keeps its own player_lookup_requirements_not_met code), and hosted checkout orders placed below it send no webhooks. Webhooks for orders already accepted are still sent. Sandbox keys are not affected.
Sandbox
Use a sandbox API key with the same `Authorization: Bearer <api_key>` header and the same endpoint paths as live. Cardzone automatically chooses live or sandbox behavior from the bearer key. Live keys use real catalog, wallet, orders, fulfillment jobs, and webhooks. Sandbox keys return static responses only. Sandbox is stateless: it does not create orders, debit wallets, enqueue fulfillment jobs, or send webhooks. Hosted checkout session creation is live-only; sandbox keys receive a forbidden response for checkout session creation. Order cancellation is live-only; sandbox keys receive a forbidden response because sandbox orders are stateless. To trigger hardcoded order responses, call `GET /api/b2b/v1/products` with a sandbox key and send one of these product IDs as `product_id` to `POST /api/b2b/v1/orders`: - `018f0000-0000-7000-8000-000000000001` (`sandbox-success-voucher`): Static sandbox product that returns a fulfilled voucher order. Poll it with order_id `1CAYVN8V9qVvrLwnnSZsPE`. - `018f0000-0000-7000-8000-000000000002` (`sandbox-wallet-topup-required`): Static sandbox product that returns an action-required wallet order. Poll it with order_id `1CAYVN8V9qVvrLwnnSZsPF`. - `018f0000-0000-7000-8000-000000000003` (`sandbox-merchant-attention-required`): Static sandbox product that returns a fulfillment action-required order. Poll it with order_id `1CAYVN8V9qVvrLwnnSZsPG`. - `018f0000-0000-7000-8000-000000000004` (`sandbox-manual-review-required`): Static sandbox product that returns a manual-review action-required order. Poll it with order_id `1CAYVN8V9qVvrLwnnSZsPH`. - `018f0000-0000-7000-8000-000000000005` (`sandbox-failed-order`): Static sandbox product that returns a failed fulfillment response. Poll it with order_id `1CAYVN8V9qVvrLwnnSZsPJ`.
Catalog
Category and product discovery
Orders
Order creation and status polling
Account
Wallet balance information
Webhooks
Polling is the source of truth for final order state. Polling alone is enough for correctness. Recommended integration: listen to webhooks for faster updates, then use polling as reconciliation and fallback. Return any 2xx status to acknowledge receipt. Use `event_id` to dedupe deliveries.