MedsGH Developers
v0.1 · draft

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.

Customer paysfor an order
Order is splitone job per pharmacy
Standard contractthe same for every provider
Provider deliversand reports status
Customer receivestheir medication

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.

MedsGHProvider
1GET rates

MedsGH sends pickup, dropoff and package details. You return a price and a quote reference.

2POST job

MedsGH sends the full job packet. You return your booking reference.

3Status callbacks

You POST events to the per-job callback URL (preferred). MedsGH polls your tracking endpoint only as a fallback.

4Cancel

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.

BlockContentsExample
IdentityJob id, idempotency key for safe retries, quote referenceMG-1042-P17
PickupPharmacy name, address, coordinates, contact numberAseda Pharmacy, Osu
DropoffAddress, coordinates, receiver name and phone, delivery noteEast Legon, “call on arrival”
PackageDescription, weight, dimensions, declared value0.8 kg sealed parcel
ServiceService level (standard or express), pickup slot, insurance flagStandard, 13 Sep 10:15
CallbackPer-job URL to which you post status updatessigned, per-job
Safe retriesIf a request times out, resend it with the same idempotency_key. Duplicates return the original booking, so a job is never booked twice.
No webhook registrationEach job's 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.

  1. acceptedThe job has been taken.
  2. picked_upThe rider collected the parcel from the pharmacy.
  3. in_transitThe rider is on the way to the customer.
  4. deliveredThe customer has the parcel. Requires proof.
failedDelivery was not possible. Always include a reason.
cancelledThe job was stood down before pickup.
Proof of deliverydelivered is accepted only with a verified customer code (OTP) or a photo URL.
Strict vocabularyAn unrecognised status is rejected and logged. MedsGH does not infer intent. You can test this in the callback simulator.

What each status triggers

Providers do not need MedsGH internals, but this is the flow your updates drive.

StatusEffect on MedsGH
acceptedJob assigned. Pharmacy and customer notified.
picked_up / in_transitCustomer tracking shows the parcel on its way.
deliveredProvider payout triggered. Order marked complete.
failedJob re-offered. Pharmacy notified with the reason.
cancelledJob 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 termYour equivalent
pickup.latitudeyour field
deliveredyour status

Continue to the technical guide