Nile Pay Docs

Overview

Sandbox mode simulates live payment flows without processing real money. Use it to develop, debug, and verify your integration.

Configuration

Initialize the SDK with sandbox environment:

import { createNilePay } from '@nilepay/sdk';

const nilePay = createNilePay({
  environment: 'sandbox',
  apiKey: 'npk_sandbox_your_sandbox_key',
  apiSecret: 'nps_sandbox_your_sandbox_secret',
});

Sandbox Credentials

Obtain sandbox API keys from the merchant dashboard under Settings > API Keys > Sandbox.

Public key prefix: npk_sandbox_
Secret key prefix: nps_sandbox_

Sandbox credentials are separate from live credentials. Do not use live keys in sandbox mode or vice versa.

Mock Payment Provider

The sandbox uses a mock provider that simulates payment flows. It supports:

Simulated Outcomes

Scenario	Behavior
Success	Payment completes immediately
Failure	Payment fails with provider error
Timeout	Payment hangs, then fails after 30s
Pending	Payment stays pending indefinitely

Triggering Scenarios

Pass metadata to control mock behavior:

const collection = await nilePay.createCollection({
  amount: 50000,
  reference: 'TEST-001',
  customer: { phone: '+256700000000' },
  metadata: {
    // Simulate failure
    _mockResult: 'failure',
    _mockFailureReason: 'insufficient_funds',
    
    // Or simulate timeout
    // _mockResult: 'timeout',
  },
});

Available Mock Failure Reasons

insufficient_funds
invalid_phone
provider_error
network_error
user_cancelled

Testing Scenarios

Test Case: Successful Payment

const result = await nilePay.createCollection({
  amount: 10000,
  reference: 'TEST-SUCCESS-001',
  customer: { phone: '+256700000000' },
});

console.log(result.status);
// 'processing' -> 'successful'

Test Case: Failed Payment

const result = await nilePay.createCollection({
  amount: 10000,
  reference: 'TEST-FAIL-001',
  customer: { phone: '+256700000000' },
  metadata: { _mockResult: 'failure' },
});

console.log(result.status);
// 'processing' -> 'failed'

Test Case: Webhook Delivery

Verify your webhook handler receives correct payloads:

// In your webhook handler
app.post('/webhooks', (req, res) => {
  console.log(req.body);
  // {
  //   event: 'success',
  //   transactionId: 'txn_...',
  //   reference: 'TEST-SUCCESS-001',
  //   status: 'successful',
  //   amount: 10000,
  //   currency: 'UGX',
  //   ...
  // }
  res.send('OK');
});

Test Case: Duplicate Handling

Send the same request twice to verify idempotency:

// First request
const result1 = await nilePay.createCollection({
  amount: 10000,
  reference: 'TEST-DUPE-001',
  customer: { phone: '+256700000000' },
});

// Second request with same reference
const result2 = await nilePay.createCollection({
  amount: 10000,
  reference: 'TEST-DUPE-001',
  customer: { phone: '+256700000000' },
});

// Verify second request returns same transaction
console.log(result1.transactionId === result2.transactionId);
// true

Going Live Checklist

Before switching to production:

Replace sandbox credentials with live credentials
Change environment from 'sandbox' to 'live'
Update webhook URL if using separate endpoints
Remove all _mockResult metadata from requests
Test at least one successful payment in sandbox
Verify webhook handler processes all event types
Review error handling for production scenarios
Confirm settlement account details are correct

Limitations

Sandbox mode has these differences from live:

No real SMS messages sent to phone numbers
No actual fund transfers or settlements
Mock provider response times may differ from production
Rate limits are more relaxed

Testing

On this page