This page helps you place your first order in the sandbox. The sandbox is a test mode: it returns fixed answers and spends no money.
First you see each request and its real sandbox response: list products, place an order, and poll it until it reaches a final status. Polling means asking the API for the order again until its status changes. Then you send the same requests from your terminal with your own API key.
Before you start
- A Cardzone store. Sign in at
cardzone.ai/b2b. - A Sandbox API key. Create it on the Developers page in the dashboard. Sandbox API keys work right away. You don’t need business verification first.
Steps
List the catalog
The catalog is the list of products you can sell. Each product is one item at one fixed amount. To order a product, send its
idasproduct_id. With a sandbox API key, each productidgives a fixed test result, called a scenario.GET /productsRecorded sandbox response GETScenario:Request bodyResponseCreate an order
Send the product, a quantity, and your own
merchant_order_ref.merchant_order_refis your own ID for the order. It makes retries safe: if you send the samemerchant_order_refagain, you get409and no second order is created. Pick a scenario to see its response.POST /ordersRecorded sandbox response POSTScenario:Request bodyResponsePoll until the status is final
processingandaction_requiredare not final. Keep polling until the status isfulfilled,failed, orcanceled. In the example above, the Poll button switches to this request.GET /orders/{id}Recorded sandbox response GETScenario:Request bodyResponseCall it from your server
Save your sandbox API key in the
CARDZONE_API_KEYenvironment variable. Then copy any example request with Copy cURL, or start from these samples:# Replace this value with your own sandbox API key. export CARDZONE_API_KEY=cz_your_sandbox_key curl -X POST https://cardzone.ai/api/b2b/v1/orders \ -H "Authorization: Bearer $CARDZONE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"product_id":"018f0000-0000-7000-8000-000000000001","quantity":1,"merchant_order_ref":"shop-order-1001"}'const response = await fetch("https://cardzone.ai/api/b2b/v1/orders", { method: "POST", headers: { Authorization: `Bearer ${process.env.CARDZONE_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ product_id: "018f0000-0000-7000-8000-000000000001", quantity: 1, merchant_order_ref: "shop-order-1001", }), }); const order = await response.json(); console.log(response.status, order.order_id, order.status);import os import requests response = requests.post( "https://cardzone.ai/api/b2b/v1/orders", headers={"Authorization": f"Bearer {os.environ['CARDZONE_API_KEY']}"}, json={ "product_id": "018f0000-0000-7000-8000-000000000001", "quantity": 1, "merchant_order_ref": "shop-order-1001", }, timeout=30, ) order = response.json() print(response.status_code, order["order_id"], order["status"])require "net/http" require "json" uri = URI("https://cardzone.ai/api/b2b/v1/orders") request = Net::HTTP::Post.new(uri, "Authorization" => "Bearer #{ENV.fetch("CARDZONE_API_KEY")}", "Content-Type" => "application/json") request.body = {product_id: "018f0000-0000-7000-8000-000000000001", quantity: 1, merchant_order_ref: "shop-order-1001"}.to_json response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) } order = JSON.parse(response.body) puts response.code, order["order_id"], order["status"]
Check the result
You get a 201 Created response. Its status is fulfilled, and codes holds SANDBOX-CODE-123:
{
"order_id": "1CAYVN8V9qVvrLwnnSZsPE",
"merchant_order_ref": "shop-order-1001",
"product_code": "sandbox-success-voucher",
"status": "fulfilled",
"code": "SANDBOX-CODE-123",
"codes": ["SANDBOX-CODE-123"],
"actions": []
}Sandbox orders return their final status at once. A live order (a real order made with a live API key) can return processing first and reach its final status later. That is why you poll or listen for webhooks.
Next steps
- Order lifecycle: what each status means and what to do.
- Catalog and recipients: build the checkout form for top-ups.
- Webhooks: get updates sent to you, so you don’t poll on a timer.