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.
| Network | Faucet | What it asks for |
|---|---|---|
| Tron Nile | nileex.io/join/getJoinPage | An address. Sends TRX and test USDT. |
| Ethereum Sepolia | cloud.google.com/application/web3/faucet/ethereum/sepolia | A Google account. |
| BSC Testnet | bnbchain.org/en/testnet-faucet | A 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.
Updated 6 days ago
