Sandbox and faucets

Run a full payment cycle on test networks without spending real money. A test payment behaves exactly like a real one - same checkout page, same statuses, same signed webhook - but the buyer pays in testnet coins, no fee is charged, and it never enters your statistics.

There is no separate sandbox host or sandbox key. The sandbox is a flag on the payment: is_test: true at creation, on the same API with the same credentials. Every SDK exposes it as a client-level switch so you never set it by hand.

1. Attach a testnet wallet

A test payment can only be paid into a testnet wallet, so this step comes first - without it the checkout page shows an empty currency list.

On your merchant's Wallets tab in the cabinet, expand a currency labeled Test network - TRX or USDT on Tron Nile, ETH on Ethereum Sepolia, BNB on BSC Testnet - paste an address you control on that network and press Add (Getting Started shows it in a picture). Any ordinary wallet (TronLink, MetaMask) switched to the test network works.

2. Get testnet coins

Faucets hand out test coins for free. Start with Tron Nile: it is the one that asks for nothing - no account, no mainnet balance.

NetworkFaucetWhat it asks for
Tron Nilenileex.io/join/getJoinPageAn address. Sends TRX and test USDT.
Ethereum Sepoliacloud.google.com/application/web3/faucet/ethereum/sepoliaA Google account.
BSC Testnetbnbchain.org/en/testnet-faucetA small BNB balance on mainnet, by the faucet's own anti-abuse rule.

Links checked 2026-09-29: every page loads and shows its request form. Faucets change their rules without notice - if one refuses you, try the next network; the payment flow is identical on all three.

3. Create a test payment

Pass is_test: true, or build the SDK client with the sandbox switch. It defaults to false and cannot be changed after creation.

curl -X POST https://api.cryptunnel.io/v1/payments/widget \
  -H 'content-type: application/json' \
  -H 'x-merchant-id: <merchant id>' \
  -H 'x-api-key: <api key>' \
  -d '{ "amount": 5, "currency": "USD", "external_id": "test-1", "is_test": true }'
from cryptunnel import CryptunnelSync

cryptunnel = CryptunnelSync("<merchant id>", "<api key>", sandbox=True)
payment = cryptunnel.create_widget_payment(5, "USD", "test-1")
print(payment["url"])
import { Cryptunnel } from 'cryptunnel'

const cryptunnel = new Cryptunnel({ merchantId: '<merchant id>', apiKey: '<api key>', sandbox: true })
const payment = await cryptunnel.createWidgetPayment({ amount: 5, currency: 'USD', externalId: 'test-1' })
console.log(payment.url)
use Cryptunnel\Cryptunnel;

$cryptunnel = new Cryptunnel('<merchant id>', '<api key>', sandbox: true);
$payment = $cryptunnel->createWidgetPayment(5, 'USD', 'test-1');
echo $payment['url'];

With sandbox on, the client also makes list_currencies / listCurrencies return the testnet family - the codes a test h2h payment accepts as target_currency. The no-code path has the same switch: the Test payment toggle on the create-payment form and the Test link toggle on the create-link form in the cabinet. An MCP-connected agent creates test payments by default.

4. Pay it

Open the checkout URL. A test payment offers only your test-network currencies - a real payment never shows them, and a test payment never shows mainnet ones. Pick one, send the exact displayed amount from your testnet wallet before the countdown ends, and watch the payment reach confirmed: the same on-chain detection as production.

5. Check the webhook

Your callback_url receives the same signed webhook as a real payment - the body does not say whether the payment was a test one, so keep that on your side from the is_test you got at creation, or read it back with GET /v1/payments/{id}. This is the moment to run your signature check and order handling end to end - see Webhooks.

What test payments never do

  • They never touch your balance - the fee is computed for display and never charged.
  • They never appear in your dashboard numbers, payment summary, CSV export or analytics. They stay visible as rows in the payments list with a Test badge.
  • They never mix network families: the currency list on the checkout page follows is_test, so a buyer cannot pay a test invoice with real coins or a real invoice with test ones.

Every payment response carries is_test, so your own system can keep them apart too. When you are done, switch the SDK client to sandbox=False (or drop is_test) - nothing else changes.


Did this page help you?