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
| Sandbox | Live | |
|---|---|---|
Dashboard | https://sandbox.bytix.ai | https://app.bytix.ai |
Base URL | https://sandbox-api.bytix.ai | https://api.bytix.ai |
API key | pk_test_... | pk_... |
Sign-in | Google, workspace ready at once | Application and approval, authenticator required |
Checkout | SANDBOX banner, Simulate buttons, no QR | Real payment address and QR |
Money | Test funds; add more from Wallet | Your 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:
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.
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:
| Button | Pays | Resulting status |
|---|---|---|
Simulate payment | The rest of the quoted amount | paid |
Simulate underpay | Half of what is still owed | paid_partial (or paid within your deposit deduction) |
Simulate overpay | The rest plus 20% of the quote | paid_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
- Bytix POSTs the event to your URL with the headers
X-Bytix-EventandX-Bytix-Signature. - Verify the signature with your webhook secret (HMAC-SHA256 of the raw body; see Webhooks).
- Mark the order paid once per
cid, then answer HTTP 200 with the plain text bodysuccess.
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:
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:
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
- 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.
- Create the withdrawal with
POST /v1/payouts(see Withdrawals). - Approve it under Withdrawals (no passkey in the sandbox). It moves to
submittedandcompletedwithin seconds, with a webhook for each step.
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:
| Code | How to cause it | What your CRM should do |
|---|---|---|
40001 | Withdraw more than the asset's available balance | Report that funds are short; do not retry blindly |
40002 | Withdraw on Ethereum or BNB Smart Chain while the network coin (ETH, BNB) is too low for the fee | Report it: the main wallet needs the network coin |
40000 | Send an invalid body, for example a negative amount | Fix the request |
40100 | Use a wrong or revoked key, or a live key on the sandbox | Check configuration |
Webhook retry | Answer your webhook with anything other than success | Process 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
- Apply for your live workspace at https://app.bytix.ai and wait for approval.
- Create a live key, set your live webhook URL and copy the live webhook secret.
- Switch
BYTIX_API_URL,BYTIX_API_KEYandBYTIX_WEBHOOK_SECRETto the live values. Nothing else changes. - Make one small real payment and one small withdrawal before opening it to customers.