FastDriveBusiness API
Developer documentation · v1

Fast Drive Delivery API

Let your customers book Fast Drive delivery riders from inside your own app or website — see nearby riders with one price each, book one, follow it live, and confirm the drop-off with a QR scan.

Base URL
https://fastdriveng.tech/api/partner/v1
JSONBearer API keysAmounts in NGNISO 8601 timesSigned webhooks

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.

  1. Quote — riders near the pickup, each with a price and pickup ETA.
  2. Book — the price is held from your prepaid balance and the rider is asked.
  3. Track — webhooks on every status change, plus the rider's live location.
  4. Confirm — your customer scans the rider's QR; the delivery completes.

Authentication

Create keys in your dashboard and send one with every request:

HTTP header
Authorization: Bearer fd_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
KeyWhat it doesAvailable
fd_test_… sandboxTest riders, no real riders, no money. Move deliveries along by hand.As soon as you sign up
fd_live_… liveReal 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.

Shell
# 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

POST/quotesvalid 10 min

Riders who can take this delivery now, nearest first (up to 10), each with one total price. A quote can be booked once.

FieldTypeNotes
pickup.address .lat .lngstring, number, numberRequired
dropoff.address .lat .lngstring, number, numberRequired
package.descriptionstring ≤ 500Optional
Response · 201 Created
{
  "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

POST/deliveriesbook
FieldTypeNotes
quote_id, option_idstringRequired — the rider you chose
external_referencestring ≤ 100Your order id. Sending the same one again returns the first booking (safe retries).
recipient.name, recipient.phonestringOptional, shown to the rider at the drop-off
package.descriptionstring ≤ 500Optional

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.

Response · 201 Created
{
  "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 }
}
GET/deliveries/{id}
GET/deliveries?status=&external_reference=25 per page

Newest first: {"data": [...], "meta": {"current_page", "last_page", "total"}}.

POST/deliveries/{id}/cancel

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.

POST/sandbox/deliveries/{id}/advancesandbox only

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:

POST/deliveries/{id}/confirm30 / min
Request body — either one
{ "qr": "fastdrive:delivery:dlv_3kq9...:Xy7..." }   // the scanned text
{ "code": "4821" }                                // or the 4-digit code the rider reads out

Returns 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

GET/deliveries/{id}/location
Response
{ "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

GET/balance
Response
{ "currency": "NGN", "available": 25600, "held": 4400, "billing_mode": "prepaid", "credit_limit": 0 }
GET/balance/ledger

Every movement — topup, hold, charge, release, adjustment — with the balance after each.

POST/balance/topupslive keys

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.

GET/balance/topups/{reference}

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).

EventWhen
delivery.acceptedA rider accepted the delivery
delivery.arrived_at_pickupThe rider is at the pickup
delivery.picked_upThe rider has the package
delivery.deliveredYour customer confirmed the drop-off
delivery.cancelledCancelled — by you, the rider, or no answer
webhook.testThe dashboard's "Send test event" button
Example request
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.

Node.js
// 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));
}
PHP
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

StatusMeaning
pendingBooked; waiting for the rider to accept.
acceptedThe rider is on the way to the pickup.
arrived_at_pickupThe rider is at the pickup.
picked_upThe rider has the package. It can no longer be cancelled.
deliveredConfirmed by your customer's QR scan or code (or by Fast Drive support). Final.
cancelledSee cancel_reason. Final.

How money works

BookingThe price is held from your available balance.
DeliveredThe hold is charged. The rider receives their full fare; Fast Drive keeps the commission.
CancelledThe 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.
ExtrasNone. 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.

HTTPCodeWhat to do
401invalid_api_keyCheck the key — it may have been revoked.
402insufficient_balanceTop up your balance.
403partner_not_active partner_suspendedLive access needs approval; or contact Fast Drive.
404quote_not_found delivery_not_foundWrong id, or a key from the other mode.
409quote_already_used driver_unavailable not_cancellable not_confirmableQuote again, or check the status.
410quote_expiredQuote again — quotes last 10 minutes.
422option_not_found invalid_qr invalid_code proof_requiredFix the request.
429code_locked · too many requestsScan 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.