Sandbox & Testing

Learn how to test your integration safely using Rach Payments' sandbox environment before going live.

Overview

The sandbox environment allows you to:

✅ Test all API endpoints without real money
✅ Use testnet blockchains (BSC Testnet, Sepolia, etc.)
✅ Receive test API keys instantly
✅ Simulate payment flows end-to-end
✅ Test webhook integrations

How the Sandbox Works

The key prefix is the environment selector — there is no separate toggle or base URL:

Prefix	Environment	Blockchains	Real funds
`test_sk_`	Sandbox	Testnets (BSC Testnet, Sepolia, Amoy, Shasta, Devnet…)	No
`live_sk_`	Production	Mainnets	Yes

Everything else is identical — same endpoints, same request format, same response shape.

Isolation guarantee

The mode is locked onto every resource at the moment of authentication. A checkout session or wallet operation created with test_sk_* will always use testnet addresses for its full lifetime, even if you change dashboard settings afterward. This prevents prod/test cross-contamination mid-flow.

Test request:

bash

curl -H "X-API-Key: test_sk_YOUR_TEST_KEY" \
  -H "Content-Type: application/json" \
  https://api.rachfinance.com/api/v1/checkout/create \
  -d '{"amount": 10, "currency": "USD", ...}'

Production request (same code, different key):

bash

curl -H "X-API-Key: live_sk_YOUR_PROD_KEY" \
  -H "Content-Type: application/json" \
  https://api.rachfinance.com/api/v1/checkout/create \
  -d '{"amount": 10, "currency": "USD", ...}'

Testnet Blockchains

When using test API keys, all operations use testnet blockchains:

Mainnet	Testnet	Get Test Tokens
BSC	BSC Testnet	BSC Faucet
Ethereum	Sepolia	Sepolia Faucet
Polygon	Mumbai	Mumbai Faucet
Tron	Shasta	Shasta Faucet
Solana	Devnet	Solana Faucet

Getting Test Tokens

Step 1: Get Native Tokens (for gas fees)

Use the faucets above to get native tokens (BNB, ETH, MATIC, etc.) for transaction fees.

Step 2: Get Test USDT/USDC

Most testnets have test stablecoin contracts:

BSC Testnet USDT:

Contract: 0x337610d27c682E347C9cD60BD4b3b107C9d34dDd

Sepolia USDT:

Contract: 0x7169D38820dfd117C3FA1f22a697dBA58d90BA06

Mumbai USDT:

Contract: 0x0FA8781a83E46826621b3BC094Ea2A0212e71B23

You can mint test tokens from these contracts using block explorers or web3 tools.

Testing Payment Flow

1. Create Test Checkout

bash

curl -X POST https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/checkout/crypto \
  -H "X-API-Key: test_sk_YOUR_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10.00,
    "currency": "USDT",
    "network": "BSC",
    "customer_email": "test@example.com",
    "reference": "TEST-001"
  }'

2. Send Test Tokens

Use MetaMask or another wallet to send test USDT to the deposit address.

3. Monitor Payment Status

bash

curl -X GET https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/checkout/CHECKOUT_ID \
  -H "X-API-Key: test_sk_YOUR_TEST_KEY"

4. Receive Webhook

If you've configured webhooks, you'll receive a notification when the payment is detected:

json

{
  "event": "payment.received",
  "checkout_id": "checkout_xyz789",
  "amount": "10.00",
  "currency": "USDT",
  "network": "BSC",
  "txn_hash": "0x123abc...",
  "confirmations": 12,
  "status": "confirmed"
}

Testing Wallet Service

Create Test Wallet

bash

curl -X POST https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/create \
  -H "X-API-Key: test_sk_YOUR_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "test_user_123",
    "networks": ["BSC"]
  }'

Send Test Tokens to Wallet

Send test USDT to one of the generated addresses.

Check Balance

bash

curl -X GET https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/WALLET_ID/balance?network=BSC \
  -H "X-API-Key: test_sk_YOUR_TEST_KEY"

Webhook Testing

Using ngrok for Local Testing

Install ngrok:
bash
```
npm install -g ngrok
```

Start your local server:

bash

node server.js
# Running on http://localhost:3000

Expose with ngrok:
bash
```
ngrok http 3000
```

Configure webhook URL: Use the ngrok URL when creating checkouts:

json

{
  "amount": 100,
  "currency": "USDT",
  "network": "BSC",
  "callback_url": "https://abc123.ngrok.io/webhooks/payment"
}

Webhook Verification in Test Mode

Even in test mode, verify webhook signatures to ensure your verification code works:

javascript

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(JSON.stringify(payload));
  const computed = hmac.digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(computed)
  );
}

Common Test Scenarios

Scenario 1: Successful Payment

Create checkout
Send exact amount to deposit address
Wait for confirmations
Verify webhook received
Check merchant balance credited

Scenario 2: Underpayment

Create checkout for 100 USDT
Send only 50 USDT
Payment status should remain "pending"
Send remaining 50 USDT
Payment completes

Scenario 3: Overpayment

Create checkout for 100 USDT
Send 150 USDT
Payment completes for 100 USDT
Extra 50 USDT goes to merchant balance

Scenario 4: Expired Checkout

Create checkout (expires in 30 minutes by default)
Wait for expiration
Try to pay - should not credit merchant

Best Practices

Testing Checklist

✅ Test all supported networks (BSC, ETH, POL, TRX, SOL)
✅ Test both USDT and USDC where supported
✅ Test webhook signature verification
✅ Test error handling (network failures, invalid addresses)
✅ Test concurrent payments
✅ Test wallet balance tracking
✅ Performance test with multiple API calls

Differences from Production

Feature	Test Mode	Production Mode
Blockchain	Testnets	Mainnets
Currency	Test tokens	Real crypto
Confirmations	Same as mainnet	Same as mainnet
API Response Time	Similar	Similar
Webhooks	Fully functional	Fully functional
Rate Limits	More lenient	Standard limits

Transitioning to Production

When ready to go live:

Swap the key — nothing else changes:

javascript

// Store both keys in env vars, use the right one per environment
const apiKey = process.env.NODE_ENV === 'production'
  ? process.env.RACH_LIVE_KEY   // live_sk_...
  : process.env.RACH_TEST_KEY;  // test_sk_...

Your code, endpoints, and request format stay the same.

Update webhook endpoints to production URLs (or use the same URL and check is_test in the payload)
Test with small real amounts first
Monitor closely for the first few transactions
Set up monitoring and alerts

Rotate keys safely

Use POST /api/v1/api-keys/rotate/production to generate a new live_sk_* key. The old key is invalidated immediately, so update your environment variable before rotating.

Need Help?

If you encounter issues during testing:

Check API Reference for endpoint details
Review Crypto Gateway Integration
Review Wallet Service Integration
Email support@rach.finance

Sandbox & Testing ​

Overview ​

How the Sandbox Works ​

Testnet Blockchains ​

Getting Test Tokens ​

Step 1: Get Native Tokens (for gas fees) ​

Step 2: Get Test USDT/USDC ​

Testing Payment Flow ​

1. Create Test Checkout ​

2. Send Test Tokens ​

3. Monitor Payment Status ​

4. Receive Webhook ​

Testing Wallet Service ​

Create Test Wallet ​

Send Test Tokens to Wallet ​

Check Balance ​

Webhook Testing ​

Using ngrok for Local Testing ​

Webhook Verification in Test Mode ​

Common Test Scenarios ​

Scenario 1: Successful Payment ​

Scenario 2: Underpayment ​

Scenario 3: Overpayment ​

Scenario 4: Expired Checkout ​

Best Practices ​

Differences from Production ​

Transitioning to Production ​

Need Help? ​

Sandbox & Testing

Overview

How the Sandbox Works

Testnet Blockchains

Getting Test Tokens

Step 1: Get Native Tokens (for gas fees)

Step 2: Get Test USDT/USDC

Testing Payment Flow

1. Create Test Checkout

2. Send Test Tokens

3. Monitor Payment Status

4. Receive Webhook

Testing Wallet Service

Create Test Wallet

Send Test Tokens to Wallet

Check Balance

Webhook Testing

Using ngrok for Local Testing

Webhook Verification in Test Mode

Common Test Scenarios

Scenario 1: Successful Payment

Scenario 2: Underpayment

Scenario 3: Overpayment

Scenario 4: Expired Checkout

Best Practices

Differences from Production

Transitioning to Production

Need Help?