Sandbox & Testing

The sandbox lets you build and verify your integration against the real API — same endpoints, same validation, same response shapes — without dispatching real drivers, charging your wallet, or sending notifications.

Start now with your sandbox key: Log in to your merchant dashboard to find your pk_test_ key, then use it in any request.

How sandbox mode works

Authenticate with a pk_test_ key and Wasal automatically handles your requests in sandbox mode:

Behaviour	Production (pk_live_)	Sandbox (pk_test_)
Records created	Real	Isolated from production
Wallet deduction	Yes	Skipped
Insufficient-balance check	Enforced	Skipped
Delivery-partner / agent notifications	Sent	Skipped
Outbound webhooks	Fired	Skipped
Visible in ops dashboards	Yes	Hidden
Driver assignment	Real driver accepts	Simulated via API (see below)

Simulating the delivery lifecycle

In production, an order moves through its statuses as a real driver accepts and completes it. In the sandbox there is no real driver, so a dedicated endpoint lets you advance the status manually.

PUT /integration/merchant/sandbox/order/:orderId/advance-status

Sandbox only. Returns 403 SANDBOX_ONLY if called with a pk_live_ key.

Request body:

{ "status": "assigned" }

Valid statuses (in lifecycle order):

pending → assigned → on_way_to_merchant → picked_up → in_transit → delivered

Terminal alternatives: failed, returned, cancelled.

When you advance to assigned, the sandbox automatically attaches a test driver to the order, just as a real driver acceptance would. Subsequent statuses set the appropriate delivery timestamps and update the order's status history.

Response:

{
  "success": true,
  "data": {
    "orderId": "665f...",
    "orderNumber": "DEMO-000123",
    "status": "assigned"
  }
}

A full sandbox walkthrough

1. Create a customer with pk_test_.
2. Create an order — it starts in pending (or assigned if the order window is open).
3. Call advance-status with assigned, then picked_up, then delivered to walk the order through its lifecycle.
4. Poll GET /order/:orderId or the public GET /order/track/:orderNumber to confirm your integration reacts correctly to each transition.

Going live

When your integration works end-to-end in the sandbox, swap your pk_test_ key for the pk_live_ key. No code changes are required — the endpoints and payloads are identical. Just remember:

• Production orders do deduct your wallet — ensure it is funded.
• The sandbox advance-status endpoint does not exist in production; real drivers move the order.
• Double-check that you are no longer pointing at sandbox keys in any environment that creates real orders.