Getting started

Test and live

Two environments, one base URL, one code path. The key decides which world a call lands in — there is no separate sandbox host to point at and forget to change back.

The same code, priced the same way#

A test booking runs the identical route, validation and pricing as a live one. It reads your real vehicles, your real per-kilometre rates, your real promos and your real operating rules, and it returns the price a live booking would be charged. The only thing that differs is what happens after the row is written.

What a test key does and does not do#

TestLive
Validates the requestYesYes
Prices with your real configurationYesYes
Creates a delivery rowYes, flagged is_testYes
Returns a tracking codeYesYes
Records the first timeline eventYesYes
Payment checkoutFlutterwave test mode: test cards only, no real moneyReal charge
Pages a riderNoYes
Writes a settlement / payout rowNoYes
Sends confirmation emailNoYes
Appears in live dashboards and reportsNoYes
Daily limit50 bookings per company per 24 hoursYour monthly allowance

Online payments in test mode

A test booking with payment_method: "online" returns payment.test: true, a tx_ref and a checkout_url on Flutterwave's test mode: pay it with Flutterwave's test cards and no real money moves (real cards are refused there). Retrieving the delivery afterwards shows payment_status: "paid", and still no rider is sent. Test mode is exempt from the payout-account requirement, so you can build the whole integration before your company connects a bank account.

Test mode can't run real deliveries

Test bookings never reach a rider and never take real money, and each company is limited to 50 a day (429 test_limit_reached). Real deliveries need a live key on Dispatch Pro.

Environments cannot see each other#

Every read is scoped to the key's environment. A test key listing deliveries sees only test deliveries; a test key asking for a live tracking code gets 404, not a redacted record. That is a privacy property, not a tidiness one: a sandbox integration — often the one with the loosest logging — must never be able to surface a real customer's address and phone number.

The same holds for idempotency keys: they are scoped per company and environment, so reusing the string order-4821 in test does not swallow the live booking that follows it.

Telling them apart in your own logs

Every response carries both environment and livemode. Log one of them next to your own order id; the question "did that book for real?" then has an answer in your logs rather than in ours.

test
{
  "id": "6a2f…",
  "tracking_code": "DCAB12CD34",
  "environment": "test",
  "livemode": false,
  "status": "pending",
  "currency": "NGN",
  "delivery_fee": 1800,
  "platform_fee": 200,
  "rider_payout": 1400,
  "distance_km": 4.62,
  "eta_minutes": 26,
  "company_name": "Swift Wheels Logistics",
  "payment": { "method": "cod", "test": true },
  "request_id": "…"
}
live
{
  "id": "6a2f…",
  "tracking_code": "DCAB12CD34",
  "environment": "live",
  "livemode": true,
  "status": "pending",
  "payment": { "method": "cod" },
  "request_id": "…"
}

Going live#

Work through this before you swap the key, not after.

  • Dispatch Pro plan. Test keys are free; live keys are not. A company on the free plan cannot create a live key, and a live key whose company is not on Pro is refused on every call with 402 plan_required. Upgrade from Subscription in your dashboard.
  • Payout account connected. Live online bookings settle into your Flutterwave subaccount. Without one, a live online booking is refused with unprocessable rather than taking money we cannot pay out to you.
  • Cash on delivery switched on, if you intend to use it. Otherwise payment_method: "cod" is refused.
  • Bookings enabled for the company, and the company approved and active.
  • Idempotency keys on every booking. In test, a duplicate is an untidy row. In live, it is a second rider and a second charge.
  • Error handling that branches on error.code, not on message text.
  • The live key in a secret store, held only by your server.
  • Sensible polling. Every 30–60 seconds for a delivery in flight; far less for one that has finished.

Keep the test key

Going live is not a migration. Most teams keep the test key wired to their staging environment permanently — it is the only way to exercise a booking path without spending somebody's fuel.