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#
| Test | Live | |
|---|---|---|
| Validates the request | Yes | Yes |
| Prices with your real configuration | Yes | Yes |
| Creates a delivery row | Yes, flagged is_test | Yes |
| Returns a tracking code | Yes | Yes |
| Records the first timeline event | Yes | Yes |
| Payment checkout | Flutterwave test mode: test cards only, no real money | Real charge |
| Pages a rider | No | Yes |
| Writes a settlement / payout row | No | Yes |
| Sends confirmation email | No | Yes |
| Appears in live dashboards and reports | No | Yes |
| Daily limit | 50 bookings per company per 24 hours | Your monthly allowance |
Online payments in test mode
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
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.
{
"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": "…"
}{
"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
unprocessablerather 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