Testing & Sandbox Environment

The IDeliver Sandbox is a fully isolated testing environment that allows you to safely build and verify your integration without using real money, dispatching real riders, or affecting your live production metrics.

When operating in the Sandbox, all objects are strictly separated from live data (is_test: true), commissions are bypassed, and SMS/Push notifications are muted. However, Webhooks will fire exactly as they do in production, allowing you to fully test your application’s state management.

Dashboard Test Mode (No-Code Testing)

You do not need to write code to use the Sandbox. You can simulate the entire order lifecycle directly from your Merchant Dashboard.

1. Log in to merchant.ideliver.ng .
2. Toggle the “Test Mode” switch in the top navigation bar.
3. Navigate to the Orders view. You will now only see test orders.
4. Click Create Test Order to generate a dummy delivery.
5. Use the Simulator Card next to the active order to manually click through the rider actions (Accept → Pickup → Deliver). This will instantly trigger the corresponding webhooks to your connected application.

The API Simulator (For Developers)

To automate testing within your CI/CD pipelines or local development environment, IDeliver provides dedicated Simulator endpoints.

Authentication

To interact with the Simulator API, you must authenticate using your Test Integration Key (which begins with ilv_test_...). Live keys will be rejected by the simulator endpoints.

Create a Test Order

Instead of using the live /v1/orders endpoint, use the simulator endpoint to create an order that is instantly flagged as a test.

curl -X POST https://api.ideliver.ng/v1/test/simulator/orders \
  -H "Authorization: Bearer ilv_test_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "external_order_id": "my-test-order-001",
    "pickup_address": "123 Pickup Street, Lagos",
    "dropoff_address": "456 Delivery Avenue, Lagos",
    "customer_name": "Test Customer",
    "customer_phone": "+2348000000000"
  }'

import Ideliver from "@ideliver/node";
 
const client = new Ideliver({ apiKey: "ilv_test_YOUR_KEY_HERE" });
 
const result = await client.simulator.createOrder({
  external_order_id: "my-test-order-001",
  pickup_address: "123 Pickup Street, Lagos",
  dropoff_address: "456 Delivery Avenue, Lagos",
  customer_name: "Test Customer",
  customer_phone: "+2348000000000",
});
 
console.log(result.order_id); // Use this for simulator actions

Effect: Creates an order in the isolated test environment and fires the order.created webhook.

Simulate Rider Actions

Because there are no real riders in the Sandbox, you must tell the simulator to progress the order state.

curl -X POST https://api.ideliver.ng/v1/test/simulator/rider-action \
  -H "Authorization: Bearer ilv_test_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "your_test_order_id",
    "action": "accept"
  }'

await client.simulator.riderAction({
  order_id: "your_test_order_id",
  action: "accept", // "accept" | "pickup" | "deliver"
});

Effect: The system assigns a well-known Mock Rider to the order and fires the corresponding webhooks. No real money movement occurs.

Full-Lifecycle Auto-Progress (Recommended)

Don’t want to call rider-action 3 times? Use the auto-progress endpoint — it creates the order AND automatically simulates the full delivery lifecycle with realistic delays:

curl -X POST https://api.ideliver.ng/v1/test/simulator/orders/auto \
  -H "Authorization: Bearer ilv_test_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "external_order_id": "auto-demo-001",
    "pickup_address": "12 Marina Road, Lagos Island",
    "dropoff_address": "45 Admiralty Way, Lekki Phase 1",
    "customer_name": "Jane Tester",
    "customer_phone": "+2348000000000",
    "step_delay_ms": 3000
  }'

const result = await fetch("https://api.ideliver.ng/v1/test/simulator/orders/auto", {
  method: "POST",
  headers: {
    Authorization: "Bearer ilv_test_YOUR_KEY_HERE",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    external_order_id: "auto-demo-001",
    pickup_address: "12 Marina Road, Lagos Island",
    dropoff_address: "45 Admiralty Way, Lekki Phase 1",
    customer_name: "Jane Tester",
    customer_phone: "+2348000000000",
    step_delay_ms: 3000,
  }),
});
const data = await result.json();
console.log(data.timeline); // Shows when each webhook fires

Effect: Creates a test order, responds immediately with a timeline, then fires webhooks on schedule:

• T+0s → order.created
• T+3s → order.rider_assigned + order.accepted
• T+6s → order.picked_up + order.status_updated
• T+9s → order.delivered + order.status_updated

Set step_delay_ms: 0 for instant delivery (all events fire within ~100ms).

Try it live: Use the Simulator Playground to fire auto-progress requests directly from your browser.

Sandbox Test Driver Account

IDeliver provides a permanent, shared sandbox driver that is always available for testing. This account is not rate-limited and can be used by any integrator — no signup required.

Test Driver Credentials

These credentials work on both the Rider Mobile App and the API (via POST /v1/auth/rider/phone-otp/request + /verify).

Log In as the Test Driver (API)

# Step 1: Request OTP (SMS is skipped — OTP is always 000000)
curl -X POST https://api.ideliver.ng/v1/auth/rider/phone-otp/request \
  -H "Content-Type: application/json" \
  -H "X-IDeliver-Environment: test" \
  -d '{"phone": "08000000000"}'
 
# Step 2: Verify OTP → receive rider JWT
curl -X POST https://api.ideliver.ng/v1/auth/rider/phone-otp/verify \
  -H "Content-Type: application/json" \
  -H "X-IDeliver-Environment: test" \
  -d '{"phone": "08000000000", "code": "000000"}'

The verify response returns access_token and refresh_token JWTs with is_sandbox: true.

Log In via the Rider Mobile App

1. Open the IDeliver Rider App.
2. Enable Sandbox Mode (tap version number 5 times).
3. Enter phone: 08000000000.
4. Enter OTP: 000000.
5. You’re logged in as the Sandbox Test Rider.

How Test Orders Reach This Driver

When you use the Simulator (manual or auto-progress), all test orders are assigned to rider 00000000-0000-4000-8000-000000000001 — the Sandbox Test Rider. This means:

• Webhook payloads include rider_id: "00000000-0000-4000-8000-000000000001"
• If you’re logged into the Rider App as the test driver, you’ll see these orders appear in real-time
• The full loop works: create order → rider sees it → webhooks fire → your backend processes them

Shared account notice: This is a public sandbox account. Multiple developers may be logged in simultaneously. Test orders are isolated by merchant, so you will only see orders created by your own sandbox key.

Rider App Sandbox Mode (For Fleet Managers)

If you are managing an internal fleet and want your staff to practice using the IDeliver Rider App without triggering real commissions or requiring actual GPS movement, you can unlock the hidden Developer Sandbox on the mobile app.

1. Open the IDeliver Rider App.
2. On the Login/Welcome screen, locate the App Version number at the bottom.
3. Quickly tap the version number 5 times.
4. A yellow warning banner will appear indicating “SANDBOX MODE ACTIVE”.

While in mobile Sandbox Mode:

• Strict GPS validations are bypassed (Mock GPS locations are accepted).
• Mandatory SMS verifications (like POD OTPs) are bypassed.
• No live commission accrual takes place.

To exit Sandbox Mode, simply tap the version number 5 times again to return to the Live environment.

Key Differences: Sandbox vs. Production

Best Practices

• Always use test keys for development. Never hardcode your live ilv_live_... key in testing scripts.
• Verify your webhook handler by testing all state transitions (accept → pickup → deliver) in sequence.
• Test edge cases like cancelled orders or re-assignment by using the Admin API with test orders.
• Keep test data clean — test orders are fully isolated and do not appear in production reports or billing.

What’s next?

• Simulator Playground — Fire test requests from your browser with the interactive playground
• Quick Start — Make your first API call in 3 minutes
• Webhooks & Events — Configure webhook endpoints and handle events
• Authentication — API key scopes, sandbox vs production, and security