Testing With Sandbox

Introduction to Sandbox Environment

The DollarPe Sandbox environment provides a safe, isolated testing ground for integrating with our onramp/offramp APIs before deploying to production. This guide covers everything you need to know about testing your integration thoroughly in the sandbox environment.

Key Benefits of Sandbox Testing: - Test the full integration flow without real funds - Validate your implementation against our API specifications - Simulate various success and error scenarios - Ensure your error handling works correctly - Gain confidence before going live

Sandbox vs. Production

Key Differences
Environment Comparison

Feature	Sandbox	Production
Base URL	`https://sandbox.dollarpe.xyz`	`https://production.dollarpe.xyz`
API Keys	Sandbox-specific	Production-specific
Funds	Test funds only	Real funds
Blockchain Networks	Includes test networks	Only mainnet networks
Processing Times	Accelerated for testing	Actual processing times
Rate Limits	Higher for testing	Standard production limits

Getting Started with Sandbox

Step 1: Obtain Sandbox Credentials

IMPORTANT: Sandbox credentials are different from production credentials. They cannot be used interchangeably.

To get started with the sandbox environment:

Contact our support team to request sandbox access
You’ll receive your sandbox API key and API secret
Store these credentials securely, following the same security practices you would for production

Step 2: Configure Your Environment

Update your application configuration to use the sandbox base URL and credentials:

// Sandbox configuration
const config = {
  baseUrl: "https://sandbox.dollarpe.xyz",
  apiKey: "YOUR_SANDBOX_API_KEY",
  apiSecret: "YOUR_SANDBOX_API_SECRET",
};

Step 3: Implement Authentication

Authentication works the same way in sandbox as it does in production. Use the same header generation logic with your sandbox credentials:

const crypto = require("crypto");

const generateHeaders = (apiKey, apiSecret, body = {}) => {
  // Get current timestamp
  const timestamp = Math.floor(Date.now() / 1000);

  // Sort and stringify the body
  const sortedBody = JSON.stringify(body, Object.keys(body).sort());

  // Create message string
  const message = `${apiKey}|${timestamp}|${sortedBody}`;

  // Generate signature
  const signature = crypto
    .createHmac("sha256", apiSecret)
    .update(message)
    .digest("base64");

  return {
    "Content-Type": "application/json",
    "X-API-KEY": apiKey,
    "X-TIMESTAMP": timestamp.toString(),
    "X-SIGNATURE": signature,
  };
};

Testing KYC Flow in Sandbox

The sandbox environment allows you to test the complete KYC flow without submitting real documents.

Creating Test Customers

Create test customers using the same API endpoint as production:

// Example: Create a test customer
const createTestCustomer = async () => {
  const requestBody = {
    full_name: "Test User",
    email: "testuser@example.com",
    phone: "9911002211",
    country: "IND",
    type: "individual",
  };

  const headers = generateHeaders(config.apiKey, config.apiSecret, requestBody);

  const response = await fetch(`${config.baseUrl}/cms/api/v1/customer/create`, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(requestBody),
  });

  return await response.json();
};

Simulating KYC Document Submission

In sandbox, you can use test document URLs for KYC submission:

// Example: Submit test KYC data
const submitTestKYC = async (customerId) => {
  const requestBody = {
    customer_id: customerId,
    full_name: "Test User",
    phone: "9911002211",
    full_address: "123 Test Street, Test City",
    dob: "01-01-1990",
    document_type: "AADHAAR",
    document_front_image_url:
      "https://sandbox.dollarpe.xyz/test-images/aadhaar-front.jpg",
    document_back_image_url:
      "https://sandbox.dollarpe.xyz/test-images/aadhaar-back.jpg",
    document_details: {
      document_number: "123456789012",
    },
  };

  const headers = generateHeaders(config.apiKey, config.apiSecret, requestBody);

  const response = await fetch(
    `${config.baseUrl}/cms/api/v1/kyc/add-kyc-data`,
    {
      method: "POST",
      headers: headers,
      body: JSON.stringify(requestBody),
    }
  );

  return await response.json();
};

In the sandbox environment, KYC verification is automatically approved for most test submissions. To test failure scenarios, use specific test values as described in the “Testing Error Scenarios” section.

Adding Test Bank Accounts

Once KYC is verified, add test bank accounts:

// Example: Add a test bank account
const addTestBankAccount = async (customerId) => {
  const requestBody = {
    customer_id: "c2cf861b-342b-4318-a90e-85cd0312e82f",
    account_number: "7627389201",
    ifsc: "SBI0001829IU",
    vpa: "abc@okbank",
  };

  const headers = generateHeaders(config.apiKey, config.apiSecret, requestBody);

  const response = await fetch(
    `${config.baseUrl}/cms/api/v1/bank/add-account`,
    {
      method: "POST",
      headers: headers,
      body: JSON.stringify(requestBody),
    }
  );

  return await response.json();
};

In the sandbox environment, transaction processing is accelerated. Status changes that might take hours in production typically happen within minutes in sandbox.

Testing Payin Flow in Sandbox

Fetching Payin Configuration

Fetch payin configuration for supported assets, limits:

// Example: Fetch payin configuration
const fetchPayinConfiguration = async () => {
  const headers = generateHeaders(config.apiKey, config.apiSecret);

  const response = await fetch(
    `${config.baseUrl}/pis/api/v1/payin/configuration`,
    {
      method: "GET",
      headers: headers,
    }
  );

  return await response.json();
};

Fetching Test Rates

Fetch test exchange rates using the same API as production:

// Example: Fetch test exchange rate
const fetchTestRate = async () => {
  const requestBody = {
    asset: "USDT",
    fiat: "INR",
  };

  const headers = generateHeaders(config.apiKey, config.apiSecret, requestBody);

  const response = await fetch(
    `${config.baseUrl}/pis/api/v1/payin/fetch-rate`,
    {
      method: "POST",
      headers: headers,
      body: JSON.stringify(requestBody),
    }
  );

  return await response.json();
};

Creating Test Quotations

Create test quotations:

// Example: Create a test quotation
const createTestQuotation = async (customerId, bankId, selfieUrl, ipAddress, deviceId) => {
  const requestBody = {
    "asset": "USDC",
    "fiat": "INR",
    "sending_amount": "10000",
    "customer_id": customerId,
    "bank_id": bankId,
    "payment_method": "IMPS",
    "risk_parameters": {
        "ip_address": ipAddress,
        "device_id": deviceId
        "suspicious_activity_report": "True",
        "law_enforcement_agency_report": "False"
    }
}

  const headers = generateHeaders(config.apiKey, config.apiSecret, requestBody);

  const response = await fetch(`${config.baseUrl}/pis/api/v1/payin/quotation`, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(requestBody)
  });

  return await response.json();
};

Initiating Test Payin

Initiate test payin using the random utr:

// Example: Initiate a test payin
const initiateTestPayin = async (quotationId, customerId, utr) => {
  const requestBody = {
    quotation_id: quotationId,
    customer_id: customerId,
    client_reference_id: "test123",
    utr: utr,
  };

  const headers = generateHeaders(config.apiKey, config.apiSecret, requestBody);

  const response = await fetch(`${config.baseUrl}/pis/api/v1/payin/initiate`, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(requestBody),
  });

  return await response.json();
};

Monitoring Test Transaction Status

Monitor the status of your test payin:

// Example: Check test payin status
const checkTestPayinStatus = async (payinId) => {
  const headers = generateHeaders(config.apiKey, config.apiSecret);

  const response = await fetch(
    `${config.baseUrl}/pis/api/v1/payin/${payinId}`,
    {
      method: "GET",
      headers: headers,
    }
  );

  return await response.json();
};

Testing Payout Flow in Sandbox

Fetching Payout Configuration

Fetch payout configuration for supported assets, limits:

// Example: Fetch payout configuration
const fetchPayoutConfiguration = async () => {
  const headers = generateHeaders(config.apiKey, config.apiSecret);

  const response = await fetch(
    `${config.baseUrl}/pos/api/v1/payout/configuration`,
    {
      method: "GET",
      headers: headers,
    }
  );

  return await response.json();
};

Fetching Test Rates

Fetch test exchange rates using the same API as production:

// Example: Fetch test exchange rate
const fetchTestRate = async () => {
  const requestBody = {
    asset: "USDT",
    network: "BSC",
    fiat: "INR",
  };

  const headers = generateHeaders(config.apiKey, config.apiSecret, requestBody);

  const response = await fetch(
    `${config.baseUrl}/pos/api/v1/payout/fetch-rate`,
    {
      method: "POST",
      headers: headers,
      body: JSON.stringify(requestBody),
    }
  );

  return await response.json();
};

Creating Test Quotations

Create test quotations to receive wallet addresses for sending test funds:

// Example: Create a test quotation
const createTestQuotation = async (customerId) => {
  const requestBody = {
    asset: "usdt",
    fiat: "inr",
    network: "sepolia", // Note: Use sepolia for sandbox testing
    sending_amount: "10",
    customer_id: customerId,
  };

  const headers = generateHeaders(config.apiKey, config.apiSecret, requestBody);

  const response = await fetch(
    `${config.baseUrl}/pos/api/v1/payout/quotation`,
    {
      method: "POST",
      headers: headers,
      body: JSON.stringify(requestBody),
    }
  );

  return await response.json();
};

Sending Test Cryptocurrency

In the sandbox environment, you can use test networks like Sepolia for Ethereum-based testing:

IMPORTANT: Even in sandbox, you must send funds to the exact wallet address provided in the quotation response. Use test networks like Sepolia instead of mainnet networks.

Get test tokens from a Sepolia faucet
Send the exact amount of test USDT/USDC to the wallet address from the quotation
Obtain the transaction hash for the next step

Initiating Test Payouts

Initiate test payouts using the transaction hash from your test network transaction:

// Example: Initiate a test payout
const initiateTestPayout = async (quotationId, customerId, bankId, txHash) => {
  const requestBody = {
    quotation_id: quotationId,
    customer_id: customerId,
    client_reference_id: "test123",
    bank_id: bankId,
    quotation_id: txHash,
  };

  const headers = generateHeaders(config.apiKey, config.apiSecret, requestBody);

  const response = await fetch(`${config.baseUrl}/pos/api/v1/payout/initiate`, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(requestBody),
  });

  return await response.json();
};

Monitoring Test Transaction Status

Monitor the status of your test payout:

// Example: Check test payout status
const checkTestPayoutStatus = async (payoutId) => {
  const headers = generateHeaders(config.apiKey, config.apiSecret);

  const response = await fetch(
    `${config.baseUrl}/pos/api/v1/payout/${payoutId}`,
    {
      method: "GET",
      headers: headers,
    }
  );

  return await response.json();
};

Testing Webhook Integration

Configure your webhook endpoint to receive test notifications:

// Example: Configure webhook URL
const configureWebhook = async () => {
  const requestBody = {
    url: "https://your-test-server.com/webhook/dollarpe",
  };

  const headers = generateHeaders(config.apiKey, config.apiSecret, requestBody);

  const response = await fetch(
    `${config.baseUrl}/org/api/v1/organizations/api-webhooks`,
    {
      method: "POST",
      headers: headers,
      body: JSON.stringify(requestBody),
    }
  );

  return await response.json();
};

For local development, use tools like ngrok to create a public URL that forwards to your local webhook handler.

Sandbox Testing Checklist

Use this checklist to verify that your integration is fully tested and production-ready:

Customer and KYC Testing

Create a test customer profile - [ ] Submit KYC details for verification
Confirm successful KYC approval flow - [ ] Simulate KYC rejection and error responses - [ ] Update and resubmit failed KYC information - [ ] Add and verify bank account details

Payin Flow Testing

Retrieve payin configurations - [ ] Fetch exchange rates for payin - [ ] Generate and review quotations - [ ] Handle expired quotation scenarios - [ ] Simulate fiat transfer using provided bank details - [ ] Initiate payin with transaction reference - [ ] Use mock status endpoint to change transaction status - [ ] Monitor status updates throughout the payin flow - [ ] Confirm successful payin completion - [ ] Simulate and handle payin failure scenarios

Payout Flow Testing

Retrieve payout configurations - [ ] Fetch exchange rates for payout - [ ] Generate and review quotations - [ ] Handle expired quotation scenarios - [ ] Simulate crypto transfer using testnet - [ ] Initiate payout with transaction reference - [ ] Use mock status endpoint to change transaction status - [ ] Monitor status updates throughout the payout flow - [ ] Confirm successful payout completion - [ ] Simulate and handle payout failure scenarios

Webhook Testing

Set up and configure your webhook endpoint - [ ] Confirm webhook receives KYC status events - [ ] Confirm webhook receives transaction status events - [ ] Implement and test webhook retry or failure handling

Error Handling Testing

Simulate invalid or expired API credentials - [ ] Submit invalid or incomplete request payloads - [ ] Test rate limiting and throttling responses
Simulate network timeouts and delayed responses - [ ] Ensure user-facing error messages are clear and actionable

Transitioning to Production

Once you’ve completed thorough testing in the sandbox environment, follow these steps to transition to production:

Request production API credentials from our support team
Update your application configuration to use production URLs and credentials
Ensure all test code and sandbox-specific logic is removed or properly conditioned
Implement proper logging and monitoring for production transactions
Set up alerts for critical error conditions
Conduct a final review of security measures and error handling
Deploy your application with production settings

IMPORTANT: Before going live, ensure you have proper error handling, logging, and monitoring in place. Real funds will be at stake in the production environment.

Getting Help

If you encounter any issues during sandbox testing:

Check our API documentation for detailed endpoint information
Review error messages and response codes for troubleshooting clues
Contact our support team with specific error details and transaction IDs

Our support team is available to help with sandbox testing issues. When reporting problems, please include your relevant customer IDs, transaction IDs, and detailed error messages to expedite troubleshooting.

Getting Started

How KYC Works?

Development & Testing

We Support

Resources

Testing With Sandbox

Introduction to Sandbox Environment

Sandbox vs. Production

Getting Started with Sandbox

Step 1: Obtain Sandbox Credentials

Step 2: Configure Your Environment

Step 3: Implement Authentication

Testing KYC Flow in Sandbox

Creating Test Customers

Simulating KYC Document Submission

Adding Test Bank Accounts

Testing Payin Flow in Sandbox

Fetching Payin Configuration

Fetching Test Rates

Creating Test Quotations

Initiating Test Payin

Monitoring Test Transaction Status

Testing Payout Flow in Sandbox

Fetching Payout Configuration

Fetching Test Rates

Creating Test Quotations

Sending Test Cryptocurrency

Initiating Test Payouts

Monitoring Test Transaction Status

Testing Webhook Integration

Sandbox Testing Checklist

Transitioning to Production

Getting Help

Getting Started

How KYC Works?

Development & Testing

We Support

Resources

​Introduction to Sandbox Environment

​Sandbox vs. Production

​Getting Started with Sandbox

​Step 1: Obtain Sandbox Credentials

​Step 2: Configure Your Environment

​Step 3: Implement Authentication

​Testing KYC Flow in Sandbox

​Creating Test Customers

​Simulating KYC Document Submission

​Adding Test Bank Accounts

​Testing Payin Flow in Sandbox

​Fetching Payin Configuration

​Fetching Test Rates

​Creating Test Quotations

​Initiating Test Payin

​Monitoring Test Transaction Status

​Testing Payout Flow in Sandbox

​Fetching Payout Configuration

​Fetching Test Rates

​Creating Test Quotations

​Sending Test Cryptocurrency

​Initiating Test Payouts

​Monitoring Test Transaction Status

​Testing Webhook Integration

​Sandbox Testing Checklist

​Transitioning to Production

​Getting Help

Introduction to Sandbox Environment

Sandbox vs. Production

Getting Started with Sandbox

Step 1: Obtain Sandbox Credentials

Step 2: Configure Your Environment

Step 3: Implement Authentication

Testing KYC Flow in Sandbox

Creating Test Customers

Simulating KYC Document Submission

Adding Test Bank Accounts

Testing Payin Flow in Sandbox

Fetching Payin Configuration

Fetching Test Rates

Creating Test Quotations

Initiating Test Payin

Monitoring Test Transaction Status

Testing Payout Flow in Sandbox

Fetching Payout Configuration

Fetching Test Rates

Creating Test Quotations

Sending Test Cryptocurrency

Initiating Test Payouts

Monitoring Test Transaction Status

Testing Webhook Integration

Sandbox Testing Checklist

Transitioning to Production

Getting Help