Testing in Sandbox

The DollarPe sandbox environment provides a safe, isolated testing ground for validating your integration before deploying to production. No real funds are involved, and all three integration paths are supported.

Key benefits of sandbox testing: Test the full integration flow without real funds — validate against our API specs, simulate success and error scenarios, and gain confidence before going live.

Testing approaches

API Integration
Widget Integration
Client Dashboard

Use sandbox base URLs with your sandbox API credentials. The full flow — customer creation, KYC, bank linking, payin, and payout — works exactly as in production. Use the mock status endpoints to simulate transaction state changes without waiting for real blockchain confirmations.Sandbox base URL: https://sandbox.dollarpe.xyz

Call the Widget Initialize API using your sandbox credentials. The widget session will load against sandbox data, giving you the full KYC, payin, and payout UI to test end-to-end without any real funds.

<!-- Embed the session URL returned by the Widget Initialize API -->
<iframe
  src="{sandbox_widget_session_url}"
  width="100%"
  height="700"
  allow="camera; microphone"
></iframe>

Open the dashboard with your sandbox app_id to test all flows without writing any code:

https://app.dollarpe.xyz?app_id={your_sandbox_app_id}

All operations (onboarding, KYC, payin, payout) run against sandbox data.

Sandbox vs. production

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 (e.g., Sepolia)	Mainnet only
Processing Times	Accelerated	Actual processing times

Getting started with sandbox

Step 1: Obtain sandbox credentials

Sandbox credentials are different from production credentials and cannot be used interchangeably.

Contact our support team to request sandbox access. You’ll receive your sandbox API key and API secret.

Step 2: Configure your environment

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

Step 3: Set up authentication

Authentication works identically in sandbox and production. See the Authentication guide for how to generate the required headers.

Testing the KYC flow

Creating test customers

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();
};

Submitting test KYC data

In sandbox, use test document URLs for KYC submission. Verification is automatically approved for most test submissions.

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();
};

Adding test bank accounts

const addTestBankAccount = async (customerId) => {
  const requestBody = {
    customer_id: customerId,
    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();
};

Testing the payin flow

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();
};

Create a payin quotation

const createPayinQuotation = async (customerId, bankId, 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: "False",
      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();
};

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();
};

Testing the payout flow

Create a payout quotation

const createPayoutQuotation = async (customerId) => {
  const requestBody = {
    asset: "usdt",
    fiat: "inr",
    network: "sepolia",
    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();
};

Send test cryptocurrency

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.

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.

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,
    tx_hash: 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();
};

Testing webhook integration

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 ngrok to create a public HTTPS URL that forwards to your local webhook handler.

Sandbox testing checklist

Customer and KYC

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

Retrieve payin configurations
Fetch exchange rates
Generate and review quotations
Handle expired quotation scenarios
Initiate payin with transaction reference
Use mock status endpoint to change transaction status
Monitor status updates throughout the payin flow
Simulate and handle payin failure scenarios

Payout flow

Retrieve payout configurations
Fetch exchange rates
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
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
Test webhook retry and failure handling

Error handling

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

Transitioning to production

Once sandbox testing is complete:

Request production API credentials from our support team.
Update your configuration to use production URLs and credentials.
Remove or condition all sandbox-specific logic and test data.
Implement production logging and monitoring.
Set up alerts for critical error conditions.
Test with small amounts first before full deployment.

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

Status reference Error handling

Documentation Index

​Testing approaches

​Sandbox vs. production

​Getting started with sandbox

​Step 1: Obtain sandbox credentials

​Step 2: Configure your environment

​Step 3: Set up authentication

​Testing the KYC flow

​Creating test customers

​Submitting test KYC data

​Adding test bank accounts

​Testing the payin flow

​Fetch payin configuration

​Create a payin quotation

​Initiate a test payin

​Testing the payout flow

​Create a payout quotation

​Send test cryptocurrency

​Initiate a test payout

​Testing webhook integration

​Sandbox testing checklist

​Transitioning to production

Testing approaches

Sandbox vs. production

Getting started with sandbox

Step 1: Obtain sandbox credentials

Step 2: Configure your environment

Step 3: Set up authentication

Testing the KYC flow

Creating test customers

Submitting test KYC data

Adding test bank accounts

Testing the payin flow

Fetch payin configuration

Create a payin quotation

Initiate a test payin

Testing the payout flow

Create a payout quotation

Send test cryptocurrency

Initiate a test payout

Testing webhook integration

Sandbox testing checklist

Transitioning to production