For provider engineering teams
Logistics Provider Standard
Four calls on your API, one key you issue us, and signed status events you POST to the per-job URL we hand you. Same contract for every provider.
/rates, /jobs…) show the shape of the standard. If your API names things differently, our adapter maps them. Cancel windows may tighten while the standard is in draft.Credentials come from you
You issue a sandbox key and a production key. They're separate and never interchangeable. We attach your key to every call, in the header you name at onboarding.
We ping first. A 200 means everything below will work.
Status callbacks go the other way (you → MedsGH) to the per-job callback_url in every job packet. That URL is our endpoint and already carries an unguessable tok query parameter. Each callback is also signed with HMAC-SHA256 using the signing secret we agree at onboarding.
// you issue these; we plug them in and ping "base_url": "https://sandbox.<your-domain>", "api_key": "<key-we-attach-to-every-call>", "auth_header": "Client-Api-Key (or yours, just name it)", "signing_secret": "<shared-secret-for-callback-HMAC>"
The four calls
Price it. Returns a quote_reference that locks the price.
Hand it over. Idempotent on Idempotency-Key.
You POST signed events to the job's callback_url.
Before pickup only.
Get rates
Price a trip before committing. We send you the pickup and dropoff coordinates, parcel weight, dimensions and value, and the slot. You return one number.
The quote_reference you return is passed back verbatim at booking. It locks the price so neither side reprices mid-job. Recommended timeout: 10s.
Parcel units are kg, metres and GHS. If your API takes other units, say so at onboarding and the adapter converts.
{
"quote_reference": "Q-2PT-88121",
"amount": 25.00, "currency": "GHS",
"expires_at": "2026-09-13T12:00:00Z",
"breakdown": { "base": 10, "distance": 9, "weight": 2, "priority": 0, "tax": 4 }
}
Post a job
Hand over the full job packet. Retries reuse the same Idempotency-Key. Duplicates return the original booking (201 with an identical reference), never a second job.
idempotency_key field carry the same value: req_{request_id}_pharm_{pharmacy_id}.job_id (MG-{request}-P{pharmacy}) is our identity for the job and is what appears in the callback URL and callback body. The idempotency key is only for deduplicating your bookings.service.zone, pickup.ready_at, fragile, cold_chain) are optional and may be absent. Don't require them.{
"job_id": "MG-1042-P17",
"idempotency_key": "req_1042_pharm_17",
"quote_reference": "Q-2PT-88121",
"distance_km": 7.4,
"service": { "level": "standard", "insurance": false, "date": "2026-09-13", "time": "10:15" },
"pickup": {
"pharmacy_id": 17, "name": "Aseda Pharmacy",
"address": "12 Oxford Street, Osu",
"latitude": 5.5556, "longitude": -0.1833,
"contact": "0244123456"
},
"dropoff": {
"address": "14 Mango Road, East Legon",
"latitude": 5.6380, "longitude": -0.1720,
"receiver_name": "Ama Serwaa", "receiver_phone": "0551234567",
"note": "Call on arrival."
},
"package": {
"description": "Sealed pharmacy parcel", "type": "parcel",
"weight_kg": 0.8,
"length_m": 0.20, "width_m": 0.15, "height_m": 0.10,
"value": 145.50
},
"metadata": {},
"callback_url": "https://api.medsgh.com/api/webhooks/provider/jobs/MG-1042-P17/status?tok=<token>"
}
{ "provider_reference": "uuu24Rres", "status": "accepted", "accepted_at": "2026-09-13T10:16:02Z" }
Status callbacks
You POST to us. Every job packet carries a callback_url, our endpoint minted for that job. Post each status change to it with four headers:
X-Provider-Id: the provider id we gave youX-Provider-Signature: lowercase hex HMAC-SHA256 of the JSON bodyX-Event-Id: a unique id per event (we dedupe on it)X-Event-At: ISO timestamp, within ±10 minutes of our clock
No callback yet? We poll your tracking endpoint as a fallback.
delivered needs proof.otp_verified: true or a proof.photo_url. Unrecognised statuses are rejected with 422 UNKNOWN_STATUS and logged, never guessed.X-Event-Id is already recorded. Fix the payload and resend it with a new event id. Reusing the old one returns 200 {"deduped": true} and nothing is applied.JSON.stringify of the parsed body. Send compact JSON, keep key order stable, and avoid numbers that re-serialize differently (like 1.0). The body is validated strictly: unknown fields get 400 BAD_PAYLOAD, and job_id must match the URL.{
"job_id": "MG-1042-P17", "provider_reference": "uuu24Rres",
"status": "in_transit", "at": "2026-09-13T11:02:00Z",
"rider": { "name": "Kwame M.", "phone": "0559876543", "plate": "GS-4410-22" },
"proof": { "otp_verified": false }
}
const body = JSON.stringify(event); const sig = crypto.createHmac('sha256', SIGNING_SECRET) .update(body).digest('hex'); await fetch(callbackUrl, { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Provider-Id': PROVIDER_ID, 'X-Provider-Signature': sig, 'X-Event-Id': crypto.randomUUID(), 'X-Event-At': new Date().toISOString(), }, body, });
The six words
| Status | Meaning | Triggers on our side |
|---|---|---|
accepted | Job taken | Assigned; pharmacy and customer notified |
picked_up | Collected from pharmacy | Customer tracking updates |
in_transit | On the way | Customer tracking updates |
delivered | Handed over + proof | Payout triggered; order completed |
failed | Not deliverable + reason | Job re-offered; pharmacy notified |
cancelled | Stood down pre-pickup | Job returned to pool |
What our endpoint answers
| HTTP | Code / flag | When |
|---|---|---|
| 200 | — | Applied. |
| 200 | deduped: true | We've already seen this X-Event-Id. Nothing changed. |
| 200 | stale: true | The job is already finished (delivered, failed or cancelled) and this event says something different. Acknowledged, ignored. |
| 400 | BAD_SIGNATURE | Wrong tok or wrong signature. |
| 400 | BAD_PAYLOAD | Missing X-Event-Id, unknown fields, or job_id doesn't match the URL. |
| 403 | FORBIDDEN_JOB | The job belongs to a different provider. |
| 404 | UNKNOWN_JOB | No such job. |
| 409 | STALE_EVENT | X-Event-At is outside the ±10 minute window. |
| 422 | UNKNOWN_STATUS | Not one of the six words. |
| 422 | PROOF_REQUIRED | delivered without OTP or photo. |
Failures look like { "success": false, "code": "…", "message": "…" }.
Cancel
Valid before pickup only. Post-pickup cancellations return 409 TOO_LATE_TO_CANCEL. End the job as failed with a reason instead.
Wallet
We read your balance endpoint for accrued amounts, and you confirm transfers via callbacks to us. Reconcile daily and report mismatches with job ids attached.
Timeouts and retries
| Call | Timeout | Retries |
|---|---|---|
| rates | 10s | No retry. A fresh quote on the next open is cheaper than a stale one. |
| create job | 15s | 3 attempts, backoff 1s → 2s → 4s, same idempotency key. |
| track | 10s | On demand. Callbacks are the live channel; track is the fallback. |
| cancel | 10s | Idempotent by reference, so it's safe to re-send. |
Error contract (your API)
Failures from your API return { code, message }. These are the codes we expect from you. The codes our callback endpoint returns are listed under Status callbacks.
| Code | HTTP | When |
|---|---|---|
INVALID_QUOTE | 422 | Quote reference missing, expired or mismatched |
UNKNOWN_REFERENCE | 404 | Booking reference not found |
TOO_LATE_TO_CANCEL | 409 | Cancel attempted after pickup |
NO_COVERAGE | 422 | Zone not served |
PROVIDER_DOWN | 502 | Upstream unreachable after retries |