API Documentation
Pickup Delivery Vendor API — base URL https://us-central1-pharmaghana-913f6.cloudfunctions.net
Don't have an account yet? Sign up to get your own test keys, or sign in if you already have one.
Authentication
Every endpoint requires HTTP Basic authentication — your key as the username, your secret as the password. Your secret is stored hash-only on our end, never as plaintext, so we can never show it to you again after you generate it; losing it means regenerating, not recovering.
Authorization: Basic base64("pk_test_xxx:sk_test_xxx")A test_ key pair never creates a real delivery or pages a real rider. A live_ key requires identity verification to generate.
This is a plain REST API — no SDK, no language requirement. Anything that can make an HTTPS request and do HTTP Basic auth works: curl, Node.js, Python, PHP, Ruby, Java, Go, C#, whatever you already use on your own server. curl's -u, Python's requests, and most HTTP clients' basic-auth option build that header for you — you never need to base64-encode it by hand.
POST /apiVendorQuote
Get a price for a pickup → dropoff pair. Quotes expire after 5 minutes.
{
"pickupLat": 5.6037, "pickupLng": -0.1870,
"dropoffLat": 5.5900, "dropoffLng": -0.2000
}Response:
{
"quoteId": "a1b2c3…",
"price": 18.50,
"currency": "GHS",
"distanceKm": 3.2,
"durationSeconds": 540,
"expiresAt": 1699999999999
}curl -X POST https://us-central1-pharmaghana-913f6.cloudfunctions.net/apiVendorQuote \
-u "pk_test_xxx:sk_test_xxx" \
-H "Content-Type: application/json" \
-d '{"pickupLat":5.6037,"pickupLng":-0.1870,"dropoffLat":5.5900,"dropoffLng":-0.2000}'GET /apiVendorRidersAvailable
How many online riders are within your configured radius of your registered business location.
{ "availableRiders": 14, "radiusKm": 10 }curl -u "pk_test_xxx:sk_test_xxx" https://us-central1-pharmaghana-913f6.cloudfunctions.net/apiVendorRidersAvailable
POST /apiVendorCreateDelivery
Book a delivery against a quote. idempotencyKey should be unique per booking attempt — a retried call with the same key returns the existing delivery instead of creating a duplicate. Broadcast only: there's no way to choose a specific rider.
{
"quoteId": "a1b2c3…",
"idempotencyKey": "order-42-attempt-1",
"vendorOrderId": "order-42",
"pickup": { "address": "…", "lat": 5.6037, "lng": -0.1870, "contactName": "…", "contactPhone": "…" },
"dropoff": { "address": "…", "lat": 5.5900, "lng": -0.2000, "contactName": "…", "contactPhone": "…" },
"package": { "size": "medium", "weightRange": "1-5kg", "description": "…" }
}Response:
{
"deliveryId": "…", "trackingCode": "BIKESDROPXXXXXX",
"trackingUrl": "https://bikesdrop.com/track/BIKESDROPXXXXXX",
"status": "pending", "price": 18.50
}402 if your balance can't cover the quote — there's no postpaid option.
curl -X POST https://us-central1-pharmaghana-913f6.cloudfunctions.net/apiVendorCreateDelivery \
-u "pk_test_xxx:sk_test_xxx" \
-H "Content-Type: application/json" \
-d '{
"quoteId": "a1b2c3…",
"idempotencyKey": "order-42-attempt-1",
"vendorOrderId": "order-42",
"pickup": { "address": "…", "lat": 5.6037, "lng": -0.1870, "contactName": "Your Kitchen", "contactPhone": "0240000000" },
"dropoff": { "address": "…", "lat": 5.5900, "lng": -0.2000, "contactName": "Customer Name", "contactPhone": "0240000001" }
}'GET /apiVendorGetDelivery?id=…
Current status, scoped to your own deliveries only.
{
"deliveryId": "…", "vendorOrderId": "order-42",
"status": "picked", "trackingCode": "…", "trackingUrl": "…",
"price": 18.50,
"rider": { "name": "John A.", "phone": "0240000067" }
}rider is null before a rider accepts, and once the delivery is delivered or cancelled. The phone is the rider's real number, so you can call them directly if you need to — a wrong order, a redirect, a gate code they can't get past.
curl -u "pk_test_xxx:sk_test_xxx" "https://us-central1-pharmaghana-913f6.cloudfunctions.net/apiVendorGetDelivery?id=$DELIVERY_ID"
GET /apiVendorDeliveries
List your own recent deliveries, newest first — enough to build a deliveries table on your own dashboard without tracking every id yourself. Optional limit (default 20, max 100) and before (the previous page's nextBefore, for paging further back) query params. A test_ key only ever lists test bookings; a live_ key only ever lists real ones.
{
"deliveries": [
{ "deliveryId": "…", "vendorOrderId": "order-42", "status": "delivered",
"trackingCode": "…", "trackingUrl": "…", "price": 18.50, "createdAt": 1699999999999 },
…
],
"nextBefore": 1699999800000
}nextBefore is null once you've reached the last page.
curl -u "pk_test_xxx:sk_test_xxx" "https://us-central1-pharmaghana-913f6.cloudfunctions.net/apiVendorDeliveries?limit=20"
GET /apiVendorBalance
Your current prepaid balance — enough to show it on your own dashboard without logging into BikesDrop's.
{ "balance": 452.30, "currency": "GHS" }curl -u "pk_test_xxx:sk_test_xxx" https://us-central1-pharmaghana-913f6.cloudfunctions.net/apiVendorBalance
Funding the wallet itself still only happens from the BikesDrop dashboard — moving real money requires your account's own login session, not an API key, so it isn't part of this REST API.
POST /apiVendorCancelDelivery?id=…
Free before a rider accepts, free within the free window after acceptance, a fee after that — and a fee always applies once the rider has picked up (admin-configured; can be the full fare, since prepared food usually can't be meaningfully returned). The unused portion of the original charge is refunded to your balance automatically.
{ "cancelled": true, "feePercent": 20, "feeAmount": 3.70, "refundAmount": 14.80 }curl -X POST -u "pk_test_xxx:sk_test_xxx" "https://us-central1-pharmaghana-913f6.cloudfunctions.net/apiVendorCancelDelivery?id=$DELIVERY_ID"
GET /apiVendorCancellationPolicy
The live fee schedule above, as numbers — admin-configurable, so don't hardcode these in your own integration. Check this before cancelling to show your own customer the right number up front, rather than only finding out the fee after the fact from apiVendorCancelDelivery's own response.
{ "freeWindowMinutes": 5, "feePercentAfterFreeWindow": 20, "feePercentAfterPickup": 100 }curl -u "pk_test_xxx:sk_test_xxx" https://us-central1-pharmaghana-913f6.cloudfunctions.net/apiVendorCancellationPolicy
POST /apiVendorVerifyPickupPin?id=…
Before handing a package to the rider, ask them for the 6-digit pickup PIN BikesDrop sent them and submit it here — a correct match confirms this is really the assigned rider and returns their name, plate number, and photo. 5 attempts per code before it locks; each code is only live until that delivery's handover.
{ "pin": "482913" }Response:
{
"verified": true,
"rider": { "name": "John A.", "plateNumber": "GR-1234-24", "photoUrl": "https://…" }
}curl -X POST -u "pk_test_xxx:sk_test_xxx" "https://us-central1-pharmaghana-913f6.cloudfunctions.net/apiVendorVerifyPickupPin?id=$DELIVERY_ID" \
-H "Content-Type: application/json" \
-d '{"pin":"482913"}'Webhook
We POST a signed event to your registered URL on every status change. Verify it with HMAC-SHA256 over the string {timestamp}.{rawBody} using your webhook signing secret (shown once, at registration).
X-BikesDrop-Signature: t=1699999999999,v1=<hex hmac>
{
"type": "delivery.status_changed",
"deliveryId": "…", "vendorOrderId": "order-42",
"status": "picked", "trackingUrl": "…",
"rider": { "name": "John A.", "phone": "0240000067" }
}Retries on 5xx/timeout only: first retry ~10s later, then 30s, 3 attempts total. After that, reconcile via GET /apiVendorGetDelivery — we never retry forever, and a persistently failing webhook never pauses future events, so a fixed endpoint self-heals with nothing to re-enable.
Verifying a received event — use your framework's raw request body, not a re-serialized/parsed one, or the hash won't match:
const crypto = require('crypto');
function isValidSignature(rawBody, signatureHeader, signingSecret) {
const [tPart, vPart] = signatureHeader.split(',');
const timestamp = tPart.split('=')[1];
const signature = vPart.split('=')[1];
const expected = crypto
.createHmac('sha256', signingSecret)
.update(`${timestamp}.${rawBody}`)
.digest('hex');
return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}Rate limits
Per key, per minute: 60 quote, 60 riders-available, 20 book, 120 status, 20 cancel, 60 deliveries list, 120 balance, 30 pickup PIN verification, 120 cancellation policy. A 429 means slow down, not that anything is wrong.
