Essentials

Testing & Sandbox

Test your DVPay integration safely without processing real transactions

DVPay provides a sandbox environment for testing your integration without processing real transactions or moving actual funds. This guide covers how to access test credentials, simulate payment scenarios, and validate your implementation.

Sandbox Environment

The sandbox environment mirrors production functionality but uses test data:

Sandbox API Base URL

https://sandbox-merchant.dv.vai247.pro/api/v1

Production API Base URL

https://merchant.dv.vai247.pro/api/v1

Never use production credentials in sandbox or sandbox credentials in production.

Getting Test Credentials

Step 1: Access Sandbox Mode

In the DVPay mobile app:

Open Merchant Dashboard

Navigate to your merchant account settings

Enable Sandbox Mode

Toggle Developer Mode → Sandbox Environment

Generate Test Credentials

Tap API Settings → Generate Sandbox Keys

Copy Credentials

Save your test X-App-Id and X-Api-Key

Sandbox credentials are prefixed with test_ to prevent accidental use in production.

Example Test Credentials

# Sandbox credentials (example)
X-App-Id: test_app_123abc
X-Api-Key: test_key_xyz789

Testing Payment Flows

Create Test Order

Use sandbox credentials to create test payment orders:

curl -X POST https://sandbox-merchant.dv.vai247.pro/api/v1/payment-gateway/order/create \
  -H "X-App-Id: test_app_123abc" \
  -H "X-Api-Key: test_key_xyz789" \
  -H "X-Timestamp: $(date +%s)" \
  -H "Content-Type: application/json" \
  -d '{
    "store_id": "test_store_001",
    "amount": 100.00,
    "currency": "USD"
  }'

Test Payment Methods

Simulate different payment scenarios using test QR codes:

Testing Refunds

Test refund functionality with completed test orders:

# First, create and complete a test order
ORDER_ID="test_ord_123"

# Then request a refund
curl -X POST https://sandbox-merchant.dv.vai247.pro/api/v1/payment-gateway/refund \
  -H "X-App-Id: test_app_123abc" \
  -H "X-Api-Key: test_key_xyz789" \
  -H "X-Timestamp: $(date +%s)" \
  -H "Content-Type: application/json" \
  -d "{
    \"order_id\": \"$ORDER_ID\",
    \"amount\": 100.00,
    \"reason\": \"Customer requested refund\"
  }"
Refunds in sandbox are processed instantly. In production, they may take 1-3 business days.

Testing Webhooks

Local Webhook Testing

Use ngrok or similar tools to test webhooks locally:

Start Your Local Server

node server.js
# Server running on http://localhost:8080

Expose with ngrok

ngrok http 8080
# Forwarding: https://abc123.ngrok.io → http://localhost:8080

Configure Webhook in Sandbox

In DVPay app (Sandbox mode):

  • Go to API Settings → Webhooks
  • Enter: https://abc123.ngrok.io/webhooks/dvpay
  • Save configuration

Trigger Test Events

Create a test payment to receive webhook notifications

Manual Webhook Testing

Test your webhook endpoint manually:

curl -X POST http://localhost:8080/webhooks/dvpay \
  -H "Content-Type: application/json" \
  -H "X-DVPay-Signature: test_signature_123" \
  -d '{
    "event": "payment.success",
    "order_id": "test_ord_123",
    "amount": 100.00,
    "currency": "USD",
    "status": "completed",
    "timestamp": 1696435200,
    "metadata": {
      "store_id": "test_store_001"
    }
  }'

Test Cards & Accounts

Test QR Code Behaviors

Scan test QR codes with the DVPay sandbox mobile app:

ScenarioActionExpected Result
Instant SuccessScan any test QR normallyPayment succeeds immediately
Instant FailureCreate order with amount 666.66Payment fails instantly
Delayed SuccessCreate order with amount 777.77Pending → Success after 5 min
Insufficient FundsSet test wallet balance to $0Payment fails with error

Test Merchant Balances

Sandbox merchants start with test balances:

{
  "balances": {
    "USD": 10000.00,
    "KHR": 40000000.00
  }
}

Reset your test balance anytime in sandbox settings.

Testing Error Scenarios

Authentication Errors

# Test invalid API key
curl -X POST https://sandbox-merchant.dv.vai247.pro/api/v1/payment-gateway/order/create \
  -H "X-App-Id: test_app_123abc" \
  -H "X-Api-Key: invalid_key_xxx" \
  -H "X-Timestamp: $(date +%s)" \
  -d '{"store_id":"test_store_001","amount":100,"currency":"USD"}'

# Expected: 401 Unauthorized

Validation Errors

# Test invalid amount (too low)
curl -X POST https://sandbox-merchant.dv.vai247.pro/api/v1/payment-gateway/order/create \
  -H "X-App-Id: test_app_123abc" \
  -H "X-Api-Key: test_key_xyz789" \
  -H "X-Timestamp: $(date +%s)" \
  -d '{"store_id":"test_store_001","amount":0.01,"currency":"USD"}'

# Expected: 422 Unprocessable Entity - invalid_amount

Rate Limiting

# Test rate limits (100 requests/minute)
for i in {1..150}; do
  curl -X GET https://sandbox-merchant.dv.vai247.pro/api/v1/payment-gateway/order/test_$i \
    -H "X-App-Id: test_app_123abc" \
    -H "X-Api-Key: test_key_xyz789" \
    -H "X-Timestamp: $(date +%s)"
done

# Expected: First 100 succeed, then 429 Too Many Requests

Environment Configuration

Manage environment-specific configuration:

package config

import "os"

type Config struct {
    BaseURL string
    AppID   string
    APIKey  string
}

func Load() *Config {
    env := os.Getenv("ENV") // "sandbox" or "production"

    if env == "production" {
        return &Config{
            BaseURL: "https://merchant.dv.vai247.pro/api/v1",
            AppID:   os.Getenv("DVPAY_APP_ID"),
            APIKey:  os.Getenv("DVPAY_API_KEY"),
        }
    }

    // Default to sandbox
    return &Config{
        BaseURL: "https://sandbox-merchant.dv.vai247.pro/api/v1",
        AppID:   os.Getenv("DVPAY_TEST_APP_ID"),
        APIKey:  os.Getenv("DVPAY_TEST_API_KEY"),
    }
}

Testing Checklist

Before going live, verify:

Payment Creation

  • Successfully create orders in sandbox
  • Receive correct QR codes
  • Handle validation errors properly

Payment Processing

  • Process successful payments
  • Handle failed payments gracefully
  • Manage pending states correctly

Webhooks

  • Receive webhook notifications
  • Validate webhook signatures
  • Handle idempotent webhook processing

Refunds & Cancellations

  • Process full refunds
  • Process partial refunds
  • Cancel unpaid orders

Error Handling

  • Handle authentication errors
  • Implement retry logic for transient errors
  • Log errors with request IDs

Security

  • Store credentials securely (environment variables)
  • Use HTTPS for all requests
  • Validate API responses

Going Live

When ready to switch to production:

Generate Production Credentials

  • Disable sandbox mode in DVPay app
  • Generate production API keys
  • Store credentials securely

Update Configuration

# Update environment variables
NODE_ENV=production
DVPAY_APP_ID=prod_app_456def
DVPAY_API_KEY=prod_key_789ghi

Update Base URL

const baseURL = 'https://merchant.dv.vai247.pro/api/v1';

Test Production

  • Make a small real transaction
  • Verify webhooks work correctly
  • Confirm funds are received

Monitor

  • Set up error alerting
  • Track transaction success rates
  • Monitor webhook delivery
Always test thoroughly in sandbox before switching to production. Real transactions cannot be easily reversed.

Sandbox Limitations

Be aware of sandbox environment differences:

FeatureSandboxProduction
Transaction LimitsUnlimitedBased on merchant tier
Processing SpeedInstant/SimulatedReal-time (2-5 seconds)
Refund ProcessingInstant1-3 business days
Webhook RetriesDisabledEnabled (4 retries)
Rate LimitingEnforcedEnforced
Data Retention30 daysUnlimited

Next Steps

Security Best Practices

Secure your integration before going live

Currencies & Conversion

Learn about multi-currency support

Error Handling

Handle API errors gracefully and implement proper error recovery

Security Best Practices

Secure your DVPay API integration and protect sensitive data