Skip to main content

​
Overview

Sandbox mode allows you to test your Transaction API integration without processing real payments. This is essential for development, testing, and debugging your payment flows.

​
Enabling Sandbox Mode

​
Method 1: Dashboard Toggle

  1. Log in to your dashboard
  2. Navigate to Settings → Sandbox Mode
  3. Toggle sandbox mode on/off

​
Method 2: API Toggle

curl -X POST https://api.transaction.gg/merchant/sandbox \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "sandboxMode": true
  }'

​
Sandbox vs Production

Sandbox Mode

Features:
  • No real cryptocurrency transactions
  • Test payment flows
  • Simulated blockchain confirmations
  • Higher rate limits
  • Free testing

Production Mode

Features:
  • Real cryptocurrency transactions
  • Live payment processing
  • Actual blockchain confirmations
  • Standard rate limits
  • Transaction fees apply

​
Sandbox Testing Scenarios

​
Payment Flow Testing

1

Create Test Payment

Use sandbox mode to create payments without real money.
2

Simulate Payment

Use our testing tools to simulate payment completion.
3

Test Webhooks

Verify your webhook handling with test events.
4

Validate Integration

Ensure your application handles all payment states correctly.

​
Example Sandbox Payment

# Create sandbox payment
curl -X POST https://api.transaction.gg/payment/create \
  -H "Authorization: Bearer pk_sandbox_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "29.99",
    "currency": "USD",
    "customerId": "cus_test_customer",
    "orderId": "test_order_123"
  }'

​
Sandbox-Specific Features

​
Test Cryptocurrency Addresses

Sandbox mode provides special test addresses for each cryptocurrency:
CryptocurrencyTest Address Format
Bitcoin (BTC)tb1... (Testnet)
Ethereum (ETH)0x... (Testnet)
Litecoin (LTC)tltc1... (Testnet)
Solana (SOL)... (Devnet)

​
Simulated Confirmations

In sandbox mode, payments are automatically confirmed after a short delay to simulate blockchain confirmations.

​
Test Data

Use these test values for consistent testing: 
{
  "testCustomers": [
    "cus_test_customer_1",
    "cus_test_customer_2"
  ],
  "testProducts": [
    "prod_test_product_1",
    "prod_test_product_2"
  ],
  "testPayments": [
    "pay_test_payment_1",
    "pay_test_payment_2"
  ]
}

​
Testing Different Scenarios

​
Successful Payment

// Test successful payment flow
async function testSuccessfulPayment() {
  // 1. Create payment
  const payment = await createPayment({
    amount: "10.00",
    currency: "USD",
    customerId: "cus_test_customer"
  });
  
  // 2. Select crypto (simulated)
  await selectCrypto(payment.id, "BTC");
  
  // 3. Simulate payment completion
  await simulatePaymentCompletion(payment.id);
  
  // 4. Verify webhook received
  // Your webhook handler should receive payment.completed event
}

​
Expired Payment

// Test expired payment flow
async function testExpiredPayment() {
  // 1. Create payment with short expiry
  const payment = await createPayment({
    amount: "10.00",
    currency: "USD",
    customerId: "cus_test_customer",
    expiresIn: 60 // 1 minute
  });
  
  // 2. Wait for expiration
  await new Promise(resolve => setTimeout(resolve, 65000));
  
  // 3. Verify webhook received
  // Your webhook handler should receive payment.expired event
}

​
Failed Payment

// Test failed payment flow
async function testFailedPayment() {
  // 1. Create payment
  const payment = await createPayment({
    amount: "10.00",
    currency: "USD",
    customerId: "cus_test_customer"
  });
  
  // 2. Simulate insufficient funds
  await simulatePaymentFailure(payment.id, "INSUFFICIENT_FUNDS");
  
  // 3. Verify error handling
  // Your application should handle the failure gracefully
}

​
Sandbox Webhooks

Sandbox mode includes special webhook events for testing:

​
Test Webhook Events

{
  "event": "payment.test_completed",
  "payment": {
    "id": "pay_test_123",
    "status": "completed",
    "testMode": true
  },
  "timestamp": "2024-01-01T00:00:00Z"
}

​
Webhook Testing Tools

Use our webhook testing tools to verify your webhook handling:
  1. Webhook Tester: Test your webhook endpoint
  2. Event Simulator: Simulate different payment events
  3. Delivery Logs: Monitor webhook delivery status

​
Best Practices for Sandbox Testing

1

Test All Scenarios

Test successful payments, failures, and edge cases.
2

Verify Webhooks

Ensure your webhook handlers work correctly.
3

Test Error Handling

Verify your application handles errors gracefully.
4

Performance Testing

Test your application under load conditions.

​
Moving to Production

​
Pre-Production Checklist

  • Remove all sandbox-specific code
  • Verify production API keys are used
  • Test with production endpoints
  • Ensure API keys are properly secured
  • Verify webhook signature validation
  • Check for hardcoded test values
  • Set up production monitoring
  • Configure alerts for failures
  • Test error notification systems

​
Production Deployment

// Environment-based configuration
const config = {
  apiUrl: process.env.NODE_ENV === 'production' 
    ? 'https://api.transaction.gg'
    : 'https://api-sandbox.transaction.gg',
    
  apiKey: process.env.NODE_ENV === 'production'
    ? process.env.PROD_API_KEY
    : process.env.SANDBOX_API_KEY,
    
  webhookSecret: process.env.NODE_ENV === 'production'
    ? process.env.PROD_WEBHOOK_SECRET
    : process.env.SANDBOX_WEBHOOK_SECRET
};

​
Sandbox Limitations

Important: Sandbox mode has some limitations compared to production:
  • No real cryptocurrency transactions
  • Simulated blockchain confirmations
  • Limited to test networks
  • Some advanced features may not be available

​
Getting Help

Documentation

Review our comprehensive API documentation.

Support

Contact our support team for assistance.