Sandbox Environment

Test your integration safely in sandbox mode

Sandbox Environment

The Zentra sandbox environment allows you to test your integration without using real money or affecting production data.

Overview

The sandbox environment is a complete replica of the live environment, allowing you to:

• Test all API endpoints
• Simulate transactions
• Test webhook events
• Verify error handling
• Load test your integration

Sandbox and live environments are completely separate. Data does not sync between them.

Examples here focus on reviewed transfer, webhook, and optional rail flows. Identity examples are reviewed but tenant-gated; customer and wallet examples should still be treated as compatibility or draft unless your environment explicitly exposes them.

Getting Started

1. Get Sandbox API Keys

1. Go to the Developer Console
2. Open API Keys
3. Generate sandbox keys (prefixed with sk_sandbox_)

2. Configure Your Client

JavaScript

const client = new Zentra.Client({
  apiKey: 'sk_sandbox_your_key_here',
  environment: 'sandbox' // Important!
});

3. Make API Calls

All reviewed API endpoints work the same way in sandbox:

// List banks
const banks = await client.transfers.getBanks();
console.log(banks[0]);

Sandbox vs Live

Feature	Sandbox	Live
API Keys	sk_sandbox_*	sk_live_*
Base URL	https://sandbox.api.usezentra.com	https://api.usezentra.com
Real Money	No	Yes
Real Bank Accounts	No	Yes
Rate Limits	100 req/min	Based on plan
Webhooks	Yes	Yes
Test Data	Required	Not allowed

Test Data

Use these test values in sandbox:

Test BVNs

BVN	Behavior
22222222222	Valid - Verification succeeds
11111111111	Invalid - Verification fails
33333333333	Pending - Stays pending for testing

Test NIDs

NIN	Behavior
12345678901	Valid
00000000000	Invalid

Test Cards

Card Number	Brand	Behavior
5060990580000217499	Verve	Successful
4084080000000409	Visa	Successful
5399830000000062	Mastercard	Successful
4000000000000002	Visa	Declined
4000000000000127	Visa	Insufficient funds

Default CVV: 123
Default Expiry: Any future date (e.g., 12/26)
Default PIN: 1234

Test Bank Accounts

Account Number	Bank	Behavior
0123456789	GTBank	Valid account
9876543210	Zenith	Valid account
0000000000	Any	Invalid account

Test OTP

For 2FA and verification:

Scenario	OTP
Success	123456
Failure	000000

Simulating Scenarios

Successful Transfer

const transfer = await client.transfers.create({
  amountMinor: 50000,
  destinationAccountNumber: '0123456789', // Test account
  destinationBankCode: '058',
  narration: 'Test transfer'
});
// Status will be 'completed' within seconds

Failed Transfer

const transfer = await client.transfers.create({
  amountMinor: 50000,
  destinationAccountNumber: '0000000000', // Invalid
  destinationBankCode: '058',
  narration: 'Test failed transfer'
});
// Will fail with 'invalid_account' error

Insufficient Balance

// Create a transfer larger than your balance
const transfer = await client.transfers.create({
  amountMinor: 999999999, // Very large amount
  destinationAccountNumber: '0123456789',
  destinationBankCode: '058',
  narration: 'Test'
});
// Will fail with 'insufficient_balance' error

Testing Webhooks

Local Development

Use ngrok to expose your local server:

# Install ngrok
npm install -g ngrok

# Start your server
node server.js

# In another terminal, expose it
ngrok http 3000

Use the ngrok URL in your webhook settings:

https://abc123.ngrok.com/webhooks/zentra

Trigger Test Webhooks

Use your sandbox tenant and the developer tooling available for your environment to trigger or replay webhook events. Prefer replay-safe test tooling over undocumented direct trigger endpoints.

Sandbox Limitations

Keep these limitations in mind when testing in sandbox:

• No Real Money: Transactions don’t involve real money
• Simplified Processing: Transfers complete instantly (no banking delays)
• Limited Banks: Only major banks are simulated
• No Physical Cards: Can’t test physical card delivery
• Rate Limits: Lower than production (100 req/min)

Best Practices

Test All Scenarios

Test both success and failure cases to ensure your error handling works.

Use Test Data

Always use test data provided above. Don’t use real customer information.

Test Webhooks

Ensure your webhook handlers work correctly before going live.

Simulate Edge Cases

Test rate limiting, timeouts, and other edge cases.

Keep Separate Keys

Never mix sandbox and live API keys in your code.

Switching to Live

When you’re ready to go live:

1. Test Everything: Ensure all features work in sandbox
2. Get Live Keys: Generate production API keys
3. Update Environment: Change environment to 'live'
4. Update Webhooks: Point webhooks to production server
5. Monitor: Watch for errors and issues

// Before (Sandbox)
const client = new Zentra.Client({
  apiKey: process.env.ZENTRA_SANDBOX_KEY,
  environment: 'sandbox'
});

// After (Live)
const client = new Zentra.Client({
  apiKey: process.env.ZENTRA_LIVE_KEY,
  environment: 'live'
});

Monitoring Sandbox Usage

View your sandbox activity in the Dashboard:

1. Go to Dashboard → Sandbox
2. View API calls, transactions, and webhooks
3. Check for errors and warnings

Resetting Sandbox Data

Need a fresh start?

1. Go to Dashboard → Sandbox → Reset
2. Click Reset All Data
3. Confirm the action

This will delete sandbox test records, including any draft customer records, virtual accounts, and transactions. This cannot be undone.

Getting Help

Questions about sandbox testing?

• 📚 Test Data Reference
• 📬 Contact Support
• 📈 Status Page

Next Steps

Test Data

Complete test data reference

Going Live

Production checklist

Webhooks Guide

Test webhook handling

API Reference

API documentation