Test Crypto Payments on Testnet: XPayLabs Guide

Test your XPayLabs integration on blockchain testnets before processing mainnet transactions. Testnet networks simulate the real blockchain environment without using real funds — get test USDT from faucets and verify the complete collection-to-webhook flow risk-free.

What testnets does XPayLabs support?

Testnet	Chain Value	Faucet
TRON Shasta	`TRON_TEST`	TRON Shasta Faucet
Ethereum Sepolia	`ETH_SEPOLIA`	Sepolia Faucet
BSC Testnet	`BSC_TEST`	BSC Testnet Faucet
Polygon Amoy	`POLYGON_AMOY`	Polygon Faucet
Avalanche Fuji	`AVAX_FUJI_TEST`	Avalanche Faucet
SUI Testnet	`SUI_TEST`	SUI Faucet

Configuration

Configure testnet RPC endpoints in your gateway configuration:

xpay:
  blockchain:
    tron:
      mainnet:
        rpc-url: "https://api.trongrid.io"
      testnet:
        rpc-url: "https://api.shasta.trongrid.io"
    ethereum:
      sepolia:
        rpc-url: "https://rpc.sepolia.org"
    bsc:
      testnet:
        rpc-url: "https://data-seed-prebsc-1-s1.binance.org:8545"

How to test the full payment flow

1. Get Test Tokens

Visit the faucet for your chosen testnet and request test USDT or native tokens (TRX, ETH, BNB). You’ll need:

Native gas tokens (TRX, ETH, BNB) to pay blockchain fees
Test USDT to simulate customer payments

2. Create a Test Collection

curl -X POST http://your-gateway:180/v1/order/createCollection \
  -H "Content-Type: application/json" \
  -d '{
    "sign": "<computed_sign>",
    "timestamp": 1717000000,
    "nonce": "test_nonce_001",
    "data": {
      "amount": "10.00",
      "symbol": "USDT",
      "chain": "TRON_TEST",
      "orderId": "test_order_001"
    }
  }'

3. Send Test USDT

Send the exact amount of test USDT to the deposit address returned in the response. For TRON Shasta:

Use a test wallet (e.g., TronLink on Shasta network)
Send test USDT from a faucet or another test wallet

4. Verify the Webhook

Your configured webhook endpoint should receive events:

ORDER_PENDING — Order created
ORDER_PENDING_CONFIRMATION — Transaction detected (within seconds)
ORDER_SUCCESS — Payment confirmed

5. Test a Payout

curl -X POST http://your-gateway:180/v1/order/createPayout \
  -H "Content-Type: application/json" \
  -d '{
    "sign": "<computed_sign>",
    "timestamp": 1717000000,
    "nonce": "test_nonce_002",
    "data": {
      "amount": "5.00",
      "symbol": "USDT",
      "chain": "TRON_TEST",
      "receiveAddress": "<your_test_wallet_address>",
      "orderId": "test_payout_001"
    }
  }'

How to test edge cases

Scenario	How to Test
Expired order	Create a collection and wait for the expiry time
Wrong amount	Send a different amount than requested (less than or more than)
Wrong token	Send a different token to the deposit address
Invalid payout address	Use an address from a different chain
Insufficient balance	Try to create a payout larger than your wallet balance
Duplicate nonce	Send the same request twice with the same nonce

Going Live

When your integration is working correctly on testnet:

Configure mainnet RPC endpoints in the gateway configuration.
Switch chain values from testnet (e.g., TRON_TEST) to mainnet (e.g., TRON).
Fund your gateway hot wallet with real tokens and gas.
Test with a small real transaction before scaling up.

Testnet USDT and gas tokens have no real value. You can be as liberal as you like with test transactions. Use this to thoroughly verify your webhook handling, order status polling, and error handling logic.

Get Started

Core Concepts

Guides

x402 Protocol

Support

Test Crypto Payments on Testnet: XPayLabs Guide

What testnets does XPayLabs support?

Configuration

How to test the full payment flow

1. Get Test Tokens

2. Create a Test Collection

3. Send Test USDT

4. Verify the Webhook

5. Test a Payout

How to test edge cases

Going Live

​What testnets does XPayLabs support?

​Configuration

​How to test the full payment flow

​1. Get Test Tokens

​2. Create a Test Collection

​3. Send Test USDT

​4. Verify the Webhook

​5. Test a Payout

​How to test edge cases

​Going Live

What testnets does XPayLabs support?

Configuration

How to test the full payment flow

1. Get Test Tokens

2. Create a Test Collection

3. Send Test USDT

4. Verify the Webhook

5. Test a Payout

How to test edge cases

Going Live