Overview
How a delivery company integrates with MedsGH
One standard, identical for every provider. If you can read a table and send a web request, you can integrate.
Concept
MedsGH is a medicine order-and-delivery platform. When a customer pays, the order is split into jobs, one per pharmacy. Providers accept jobs, deliver them, and report progress back to MedsGH.
Providers supply credentials and configuration. The contract itself does not change from one provider to the next.
The four calls
The whole integration is four interactions.
MedsGH sends pickup, dropoff and package details. You return a price and a quote reference.
MedsGH sends the full job packet. You return your booking reference.
You POST events to the per-job callback URL (preferred). MedsGH polls your tracking endpoint only as a fallback.
Valid before pickup only. After pickup a job ends as delivered or failed.
Settlement runs alongside: MedsGH reads your GET /wallet/balance for accrued amounts, and you confirm transfers via callbacks.
The job packet
Every job arrives in the same structure. Fields may be added over time, so ignore any you do not recognise.
| Block | Contents | Example |
|---|---|---|
| Identity | Job id, idempotency key for safe retries, quote reference | MG-1042-P17 |
| Pickup | Pharmacy name, address, coordinates, contact number | Aseda Pharmacy, Osu |
| Dropoff | Address, coordinates, receiver name and phone, delivery note | East Legon, “call on arrival” |
| Package | Description, weight, dimensions, declared value | 0.8 kg sealed parcel |
| Service | Service level (standard or express), pickup slot, insurance flag | Standard, 13 Sep 10:15 |
| Callback | Per-job URL to which you post status updates | signed, per-job |
idempotency_key. Duplicates return the original booking, so a job is never booked twice.callback_url is created with the job and delivered inside the packet. There is nothing to register on your side.Statuses
Whatever your internal system calls things, translate to these six values before communicating with MedsGH.
acceptedThe job has been taken.picked_upThe rider collected the parcel from the pharmacy.in_transitThe rider is on the way to the customer.deliveredThe customer has the parcel. Requires proof.
failedDelivery was not possible. Always include a reason.cancelledThe job was stood down before pickup.delivered is accepted only with a verified customer code (OTP) or a photo URL.What each status triggers
Providers do not need MedsGH internals, but this is the flow your updates drive.
| Status | Effect on MedsGH |
|---|---|
accepted | Job assigned. Pharmacy and customer notified. |
picked_up / in_transit | Customer tracking shows the parcel on its way. |
delivered | Provider payout triggered. Order marked complete. |
failed | Job re-offered. Pharmacy notified with the reason. |
cancelled | Job returned to the pool for reassignment. |
Onboarding
Progress on this checklist is saved in your browser.
Existing APIs
If your system uses its own field names and status vocabulary, MedsGH maintains a small translation layer on its side: a renaming table and nothing more. Dispatch logic does not change, and the layer becomes redundant once you adopt the standard directly.
| Standard term | Your equivalent |
|---|---|
pickup.latitude | your field |
delivered | your status |