Overview
You send a pickup and a drop-off; we return the nearby riders who take business deliveries, each with one total price. You book one, and the rider gets the job in the Fast Drive app. At the drop-off your customer scans the rider's QR code in your app — that confirms the delivery and pays the rider.
- Quote — riders near the pickup, each with a price and pickup ETA.
- Book — the price is held from your prepaid balance and the rider is asked.
- Track — webhooks on every status change, plus the rider's live location.
- Confirm — your customer scans the rider's QR; the delivery completes.
Authentication
Create keys in your dashboard and send one with every request:
Authorization: Bearer fd_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
| Key | What it does | Available |
|---|---|---|
fd_test_… sandbox | Test riders, no real riders, no money. Move deliveries along by hand. | As soon as you sign up |
fd_live_… live | Real riders, paid from your prepaid balance. | Once Fast Drive approves your business |
Data never crosses modes — a sandbox key never sees live deliveries.
Keep keys on your server; never put them in a mobile app or browser code. GET /me checks a key and returns your business, mode and rate.
Quick start
A full sandbox delivery in four calls.
# your sandbox key, from the dashboard KEY=fd_test_... API=https://fastdriveng.tech/api/partner/v1 # 1. Quote: nearby riders + prices curl -X POST $API/quotes -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{ "pickup": {"address": "12 Admiralty Way, Lekki", "lat": 6.4474, "lng": 3.4723}, "dropoff": {"address": "5 Adeola Odeku, Victoria Island", "lat": 6.4281, "lng": 3.4219}, "package": {"description": "Small parcel"} }' # 2. Book one rider from the quote curl -X POST $API/deliveries -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{ "quote_id": "qt_...", "option_id": "opt_1", "external_reference": "ORDER-1001", "recipient": {"name": "Ada Obi", "phone": "08031234567"} }' # 3. Sandbox only: move it along as a rider would curl -X POST $API/sandbox/deliveries/dlv_.../advance -H "Authorization: Bearer $KEY" # 4. Confirm the drop-off with the QR content (sandbox responses include it) curl -X POST $API/deliveries/dlv_.../confirm -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \ -d '{"qr": "fastdrive:delivery:dlv_...:..."}'
Quotes
Riders who can take this delivery now, nearest first (up to 10), each with one total price. A quote can be booked once.
| Field | Type | Notes |
|---|---|---|
pickup.address .lat .lng | string, number, number | Required |
dropoff.address .lat .lng | string, number, number | Required |
package.description | string ≤ 500 | Optional |
{
"id": "qt_8w2k...", "mode": "live", "currency": "NGN",
"distance_km": 7.8, "duration_min": 21, "expires_at": "2026-10-27T10:20:00+01:00",
"drivers": [
{ "option_id": "opt_1", "pickup_eta_min": 4, "price": 4400,
"driver": { "first_name": "Musa", "rating": 4.8, "vehicle": "Red Bajaj Boxer" } }
]
}price is what you pay: the rider's own fare plus Fast Drive's commission
(default 10%, minimum ₦300). Any markup you add for your customers is yours.
An empty drivers list means no rider is free nearby — try again shortly.
Deliveries
| Field | Type | Notes |
|---|---|---|
quote_id, option_id | string | Required — the rider you chose |
external_reference | string ≤ 100 | Your order id. Sending the same one again returns the first booking (safe retries). |
recipient.name, recipient.phone | string | Optional, shown to the rider at the drop-off |
package.description | string ≤ 500 | Optional |
Live: the price is held from your balance (402 insufficient_balance if it doesn't cover it) and the rider gets the request.
If they decline or don't answer within a few minutes, the delivery becomes cancelled with cancel_reason
driver_declined or no_driver_response, and the hold comes back in full — quote again to pick another rider.
{
"id": "dlv_3kq9...", "mode": "live", "status": "pending", "external_reference": "ORDER-1001",
"currency": "NGN", "price": 4400, "distance_km": 7.8,
"pickup": {...}, "dropoff": {...}, "package": {...}, "recipient": {...},
"driver": { "first_name": "Musa", "rating": 4.8, "vehicle": "Red Bajaj Boxer" },
"cancel_reason": null, "confirmed_via": null,
"timeline": { "created_at": "...", "accepted_at": null, "arrived_at_pickup_at": null,
"picked_up_at": null, "delivered_at": null, "cancelled_at": null }
}Newest first: {"data": [...], "meta": {"current_page", "last_page", "total"}}.
Optional reason. Allowed until the rider picks the package up. Free before the rider accepts and in the first minutes after;
later, a late-cancellation fee is kept — most of it goes to the rider for their trip.
Moves a test delivery to its next status.
Drop-off confirmation
The rider can't mark a business delivery as delivered. At the drop-off their app shows a QR code (and a 4-digit backup code). Your customer scans it in your app and your server sends it to us — that completes the delivery and pays the rider.
The QR contains text in this form: fastdrive:delivery:{delivery id}:{token}. Check that the delivery id matches the order your customer is receiving, then:
{ "qr": "fastdrive:delivery:dlv_3kq9...:Xy7..." } // the scanned text
{ "code": "4821" } // or the 4-digit code the rider reads outReturns the delivery with status: "delivered". Wrong codes get 422 invalid_code; after 5 wrong codes the code
stops working (429 code_locked) but the QR still works. Confirming twice is harmless.
In sandbox, delivery responses include sandbox.qr_payload and
sandbox.confirm_code, so you can test your scanner flow end to end.
Tracking
{ "status": "picked_up", "location": { "lat": 6.43, "lng": 3.44, "updated_at": "..." } }The rider's live position from acceptance until the delivery ends (null otherwise). Poll at most every 10 seconds, and use webhooks for status changes.
Balance & top-ups
{ "currency": "NGN", "available": 25600, "held": 4400, "billing_mode": "prepaid", "credit_limit": 0 }Every movement — topup, hold, charge, release, adjustment — with the balance after each.
Send {"amount": 50000, "callback_url": "https://..."} and get {"reference": "PTOP-...", "authorization_url": "https://checkout.paystack.com/..."}.
Send the payer to authorization_url; the balance is credited once Paystack confirms. You can also top up from your dashboard.
Checks with Paystack and returns status: pending, completed or failed.
Webhooks
Set your URL on the Webhooks page. We POST each change; answer with a 2xx within 15 seconds, or we retry (6 attempts over about 2 hours).
| Event | When |
|---|---|
delivery.accepted | A rider accepted the delivery |
delivery.arrived_at_pickup | The rider is at the pickup |
delivery.picked_up | The rider has the package |
delivery.delivered | Your customer confirmed the drop-off |
delivery.cancelled | Cancelled — by you, the rider, or no answer |
webhook.test | The dashboard's "Send test event" button |
POST https://your-server.com/hooks/fastdrive
X-FastDrive-Event: delivery.delivered
X-FastDrive-Signature: t=1761559200,v1=5f2b...
{ "id": "evt_...", "event": "delivery.delivered", "created_at": "...", "data": { ...the delivery, as GET /deliveries/{id}... } }Verify the signature
v1 is HMAC-SHA256 of "{t}.{raw body}" keyed with your signing secret. Compare in constant time and reject old timestamps (over 5 minutes).
Events can arrive more than once or out of order — rely on the delivery's status and timeline, keyed by data.id.
// Express: use express.raw({ type: 'application/json' }) for this route
const crypto = require('crypto');
function verify(rawBody, header, secret) {
const { t, v1 } = Object.fromEntries(header.split(',').map(p => p.split('=')));
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}function verify(string $rawBody, string $header, string $secret): bool
{
parse_str(str_replace(',', '&', $header), $p);
if (abs(time() - (int) ($p['t'] ?? 0)) > 300) return false;
return hash_equals(hash_hmac('sha256', $p['t'] . '.' . $rawBody, $secret), (string) ($p['v1'] ?? ''));
}Statuses
| Status | Meaning |
|---|---|
| pending | Booked; waiting for the rider to accept. |
| accepted | The rider is on the way to the pickup. |
| arrived_at_pickup | The rider is at the pickup. |
| picked_up | The rider has the package. It can no longer be cancelled. |
| delivered | Confirmed by your customer's QR scan or code (or by Fast Drive support). Final. |
| cancelled | See cancel_reason. Final. |
How money works
| Booking | The price is held from your available balance. |
| Delivered | The hold is charged. The rider receives their full fare; Fast Drive keeps the commission. |
| Cancelled | The hold comes back in full — unless you cancel late after the rider accepted, when a late-cancellation fee is kept (mostly paid to the rider). Rider declines and no-answers are always free. |
| Extras | None. No waiting or overtime charges — the quoted price is the price. |
Errors & limits
Errors look like {"error": {"code": "quote_expired", "message": "..."}}; validation errors are HTTP 422 with an errors object. Branch on code, not the message.
| HTTP | Code | What to do |
|---|---|---|
| 401 | invalid_api_key | Check the key — it may have been revoked. |
| 402 | insufficient_balance | Top up your balance. |
| 403 | partner_not_active partner_suspended | Live access needs approval; or contact Fast Drive. |
| 404 | quote_not_found delivery_not_found | Wrong id, or a key from the other mode. |
| 409 | quote_already_used driver_unavailable not_cancellable not_confirmable | Quote again, or check the status. |
| 410 | quote_expired | Quote again — quotes last 10 minutes. |
| 422 | option_not_found invalid_qr invalid_code proof_required | Fix the request. |
| 429 | code_locked · too many requests | Scan the QR instead · slow down and retry. |
Rate limit: 120 requests per minute per business, across all your keys. Over it you get HTTP 429 — wait and retry.