BxBytix

Sandbox

Build and test your whole integration against a separate Bytix with simulated payments and test money.

The sandbox is a complete, separate Bytix: its own dashboard, API, checkout and data. Endpoints, request bodies, responses, statuses and webhooks (with their HMAC signature) are the same as live. Payments are simulated and the money is test money; nothing you do in the sandbox reaches your live account.

Sandbox and live

SandboxLive
Dashboardhttps://sandbox.bytix.aihttps://app.bytix.ai
Base URLhttps://sandbox-api.bytix.aihttps://api.bytix.ai
API keypk_test_...pk_...
Sign-inGoogle, workspace ready at onceApplication and approval, authenticator required
CheckoutSANDBOX banner, Simulate buttons, no QRReal payment address and QR
MoneyTest funds; add more from WalletYour real funds

1. Open a workspace

Sign in to the sandbox dashboard with Google. Your workspace is ready at once: no application, no approval. Its main wallet already holds test funds (USDT, plus TRX, ETH and BNB for network fees).

2. Create a sandbox key

In the sandbox dashboard open Settings → Developer and create a key. It starts with pk_test_ and is shown once: store it in your server's environment, never in a browser or app.

3. Set your webhook

Open Settings → Notifications, enter the URL on your server that receives Bytix events, and copy the webhook secret. The sandbox must be able to reach that URL from the internet; for a server on your laptop, use a tunnel such as ngrok or Cloudflare Tunnel.

4. Configure your CRM

Keep these three values in configuration, so going live is a change of values, not of code:

.env (sandbox)
BYTIX_API_URL=https://sandbox-api.bytix.ai
BYTIX_API_KEY=pk_test_...
BYTIX_WEBHOOK_SECRET=...

5. Create an order

From your server, create an order exactly as in the Quickstart, with the sandbox Base URL and key.

bash
curl -X POST "https://sandbox-api.bytix.ai/v1/orders" \
  -H "Authorization: Bearer pk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "ord_test_001",
    "order_amount": "50.00",
    "order_currency": "USD",
    "payer_id": "user_1001"
  }'

The answer is HTTP 201 with cid and checkout_url, which already points at the sandbox checkout.

6. Simulate the payment

Open checkout_url in the 400×720 popup (see Checkout popup). After the payer picks a currency, the popup shows a sandbox address instead of a QR, and three buttons:

ButtonPaysResulting status
Simulate paymentThe rest of the quoted amountpaid
Simulate underpayHalf of what is still owedpaid_partial (or paid within your deposit deduction)
Simulate overpayThe rest plus 20% of the quotepaid_over (or paid within your tolerance)

Try each one with a new order_id, and leave one order unpaid until it expires to see expired.

7. Settle from the webhook

  1. Bytix POSTs the event to your URL with the headers X-Bytix-Event and X-Bytix-Signature.
  2. Verify the signature with your webhook secret (HMAC-SHA256 of the raw body; see Webhooks).
  3. Mark the order paid once per cid, then answer HTTP 200 with the plain text body success.

Any other answer is retried with backoff. The dashboard lists each delivery and can resend it. You can also confirm with POST /v1/orders/info:

bash
curl -X POST "https://sandbox-api.bytix.ai/v1/orders/info" \
  -H "Authorization: Bearer pk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "cid": "..." }'

8. Collect and check balance

A payment first waits in its payment address. In the dashboard open Wallet and click Collect on the asset; a few minutes later it is Available in your main wallet. Read both from the API:

bash
curl "https://sandbox-api.bytix.ai/v1/balance" -H "Authorization: Bearer pk_test_..."

available is what withdrawals can use; collectible is received but not collected yet. On the Wallet page, Add test funds tops up any asset at once.

9. Send a withdrawal

  1. Register the customer's wallet with POST /v1/payout-wallets, then approve it in the dashboard under Withdrawals → Customer wallets. Any address in the network's format works in the sandbox.
  2. Create the withdrawal with POST /v1/payouts (see Withdrawals).
  3. Approve it under Withdrawals (no passkey in the sandbox). It moves to submitted and completed within seconds, with a webhook for each step.
bash
curl -X POST "https://sandbox-api.bytix.ai/v1/payout-wallets" \
  -H "Authorization: Bearer pk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "payer_id": "user_1001",
    "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "asset": "USDT",
    "network": "Tron"
  }'

10. Test the error paths

Make sure your CRM handles these before you go live. Each is easy to cause in the sandbox:

CodeHow to cause itWhat your CRM should do
40001Withdraw more than the asset's available balanceReport that funds are short; do not retry blindly
40002Withdraw on Ethereum or BNB Smart Chain while the network coin (ETH, BNB) is too low for the feeReport it: the main wallet needs the network coin
40000Send an invalid body, for example a negative amountFix the request
40100Use a wrong or revoked key, or a live key on the sandboxCheck configuration
Webhook retryAnswer your webhook with anything other than successProcess the redelivery once per cid or payout_id

Repeat a create with the same order_id or payout_id: you get the stored row (HTTP 200), never a second payment. See Errors for every code.

Sample CRM

The sample CRM is a small trading-desk CRM wired to the sandbox. Paste your sandbox key to connect it, and set your webhook URL to https://sandbox-crm.bytix.ai/webhooks/bytix to watch deposits, withdrawals and webhooks end to end. The key stays in your browser.

Go live

  1. Apply for your live workspace at https://app.bytix.ai and wait for approval.
  2. Create a live key, set your live webhook URL and copy the live webhook secret.
  3. Switch BYTIX_API_URL, BYTIX_API_KEY and BYTIX_WEBHOOK_SECRET to the live values. Nothing else changes.
  4. Make one small real payment and one small withdrawal before opening it to customers.