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

# Sandbox Mode

> Test your integration with sandbox mode

## 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](https://dashboard.transaction.gg)
2. Navigate to **Settings** → **Sandbox Mode**
3. Toggle sandbox mode on/off

### Method 2: API Toggle

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

<Columns cols={2}>
  <Card title="Sandbox Mode" icon="flask">
    **Features:**

    * No real cryptocurrency transactions
    * Test payment flows
    * Simulated blockchain confirmations
    * Higher rate limits
    * Free testing
  </Card>

  <Card title="Production Mode" icon="rocket">
    **Features:**

    * Real cryptocurrency transactions
    * Live payment processing
    * Actual blockchain confirmations
    * Standard rate limits
    * Transaction fees apply
  </Card>
</Columns>

## Sandbox Testing Scenarios

### Payment Flow Testing

<Steps>
  <Step title="Create Test Payment">
    Use sandbox mode to create payments without real money.
  </Step>

  <Step title="Simulate Payment">
    Use our testing tools to simulate payment completion.
  </Step>

  <Step title="Test Webhooks">
    Verify your webhook handling with test events.
  </Step>

  <Step title="Validate Integration">
    Ensure your application handles all payment states correctly.
  </Step>
</Steps>

### Example Sandbox Payment

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

| Cryptocurrency | Test 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:

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

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

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

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

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

<Steps>
  <Step title="Test All Scenarios">
    Test successful payments, failures, and edge cases.
  </Step>

  <Step title="Verify Webhooks">
    Ensure your webhook handlers work correctly.
  </Step>

  <Step title="Test Error Handling">
    Verify your application handles errors gracefully.
  </Step>

  <Step title="Performance Testing">
    Test your application under load conditions.
  </Step>
</Steps>

## Moving to Production

### Pre-Production Checklist

<AccordionGroup>
  <Accordion title="Code Review">
    * Remove all sandbox-specific code
    * Verify production API keys are used
    * Test with production endpoints
  </Accordion>

  <Accordion title="Security Audit">
    * Ensure API keys are properly secured
    * Verify webhook signature validation
    * Check for hardcoded test values
  </Accordion>

  <Accordion title="Monitoring Setup">
    * Set up production monitoring
    * Configure alerts for failures
    * Test error notification systems
  </Accordion>
</AccordionGroup>

### Production Deployment

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

<Warning>
  **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
</Warning>

## Getting Help

<CardGroup cols={2}>
  <Card title="Documentation" icon="book" href="/api-reference/introduction">
    Review our comprehensive API documentation.
  </Card>

  <Card title="Support" icon="headset" href="mailto:support@transaction.gg">
    Contact our support team for assistance.
  </Card>
</CardGroup>