> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpaylabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Test Crypto Payments on Testnet: XPayLabs Guide

> Test XPayLabs payment integration on blockchain testnets before going live. Configure testnet endpoints, get faucet tokens, and verify the collection-to-webhook flow.

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](https://shasta.tronscan.org/)              |
| Ethereum Sepolia | `ETH_SEPOLIA`    | [Sepolia Faucet](https://sepoliafaucet.com/)                    |
| BSC Testnet      | `BSC_TEST`       | [BSC Testnet Faucet](https://testnet.bnbchain.org/faucet-smart) |
| Polygon Amoy     | `POLYGON_AMOY`   | [Polygon Faucet](https://faucet.polygon.technology/)            |
| Avalanche Fuji   | `AVAX_FUJI_TEST` | [Avalanche Faucet](https://faucet.avax.network/)                |
| SUI Testnet      | `SUI_TEST`       | [SUI Faucet](https://faucet.sui.io/)                            |

## Configuration

Configure testnet RPC endpoints in your gateway configuration:

```yaml theme={null}
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

```bash theme={null}
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:

1. `ORDER_PENDING` — Order created
2. `ORDER_PENDING_CONFIRMATION` — Transaction detected (within seconds)
3. `ORDER_SUCCESS` — Payment confirmed

### 5. Test a Payout

```bash theme={null}
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:

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

<Tip>
  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.
</Tip>