Set up as a merchant on Gumza Dispatch

Before you start

• An email address you can receive a code on.
• A Kenyan mobile number for the account owner.
• The address riders collect from, and ideally its coordinates — the fee and ETA are calculated from the pickup point.
• An HTTPS endpoint on your side that can accept POST webhooks. You can add this later, but without it you will have to poll for status.

Create the account

Go to dispatch.gumza.ke/signup. The flow mirrors Gumza: email, code, owner details, business details.

1. Email and code

   Enter your email, then the six-digit code that arrives. The code is exchanged for a short-lived signup token that carries the verified address through the rest of the form.

2. Owner

   Name, mobile number and a password of at least 10 characters including a letter and a number. Nobody vets self-signup accounts before they can create deliveries, which is why the password floor here is higher than for an invited staff member.

3. Business

   Business name, category, the pickup location, and your sales channels. This creates the merchant record that your API key will be scoped to.

Set your pickup defaults

A merchant carries a default pickup address, phone, coordinates and notes. Every dispatch you create can override them, but setting sensible defaults means a minimal create call is just the customer and the dropoff.

Set them in the dashboard, or ask your operator to set them — they map to defaultPickupAddress, defaultPickupPhone, defaultPickupLat, defaultPickupLng and defaultPickupNotes on the merchant record.

Get an API key

API keys are issued per merchant and look like <keyId>.<secret>. The keyId half is a public prefix we store in clear so we can find the row; the secret half is stored only as a bcrypt hash.

A merchant can hold several live keys at once. Issue one per system that talks to us (website, back office, warehouse scanner) so you can revoke one without taking the others down. Every key records a last_used_at, so an unused key is easy to spot and retire.

Confirm it works

POST /api/v1/external/ping is the hello-world call. It takes no body, tells you which merchant the key belongs to, and flips your connection status to connected so your operator can see the integration is live.

curl -X POST https://api.dispatch.gumza.ke/api/v1/external/ping \
  -H "X-API-Key: $DISPATCH_API_KEY"

# → {
#     "success": true,
#     "data": {
#       "merchantId": "8f1c…",
#       "merchantName": "Example Stores",
#       "connectionStatus": "connected",
#       "lastConnectedAt": "2026-10-12T08:14:22.004Z",
#       "webhookConfigured": false
#     }
#   }

webhookConfigured: false is the thing to fix next.

Register your webhook URL

Give your operator one HTTPS URL. In return you get a webhook signing secret — again, shown once. Every status change on your deliveries is then POSTed to that URL, signed with that secret.

Setting a webhook URL rotates the signing secret. The previous secret stops verifying immediately, so change the URL and roll the secret in your app together.

Full event list, the signature scheme and retry behaviour are in Webhooks. There is a test event you can fire on demand before any real delivery exists.

Create your first delivery

One call, with your own order id in externalId so you never have to store ours.

curl -X POST https://api.dispatch.gumza.ke/api/v1/external/dispatches \
  -H "X-API-Key: $DISPATCH_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "order_10294",
    "customerName": "Customer 001",
    "customerPhone": "+254700000001",
    "pickup":  { "address": "Shop 4, Westlands, Nairobi", "lat": -1.2672, "lng": 36.8065 },
    "dropoff": { "address": "Kileleshwa, Nairobi", "lat": -1.2833, "lng": 36.7833,
                 "notes": "Gate 2, ask for reception" },
    "paymentType": "COD",
    "amountCents": 250000,
    "currency": "KES"
  }'

The response carries the dispatch id, the calculated feeCents, and a trackingToken you can turn into a link for your customer. See the API reference for every field and Tracking for the link format.

Go live checklist

• ping returns your merchant name from your production key.
• Pickup defaults are set and the coordinates are right.
• Your webhook endpoint verifies signatures and rejects a tampered body.
• Your endpoint answers 2xx fast and does its real work asynchronously.
• Every create sends an Idempotency-Key, and a retry after a timeout reuses the same one.
• One real delivery has run end to end and your system saw every event.

Endpoint summary

• POST/api/v1/auth/signup/emailSend the signup verification code
• POST/api/v1/auth/signup/verifyExchange the code for a signup token
• POST/api/v1/auth/signup/completeCreate the merchant and sign in
• POST/api/v1/external/pingConfirm the API key and mark the integration connected