One API, and the whole product is built on it

Quickstart

Four calls take you from nothing to a moving car. Run these against the demo environment.

# 1. Ask for a sign-in code. The demo echoes it back; production sends an SMS.
curl -sX POST "$API/v1/auth/otp/request" \
  -H 'content-type: application/json' \
  -d '{"phone":"082 123 4567","surface":"web"}'
# -> {"sent":true,"expiresInSeconds":300,"devCode":"418320"}

# 2. Exchange it for tokens. deviceId must be stable per install.
curl -sX POST "$API/v1/auth/otp/verify" \
  -H 'content-type: application/json' \
  -d '{"phone":"082 123 4567","code":"418320","deviceId":"my-device-0001"}'
# -> {"accessToken":"eyJ...","refreshToken":"...","expiresIn":900}

# 3. Who is around?
curl -s "$API/v1/trips/nearby?lat=-26.1076&lng=28.0567" \
  -H "authorization: Bearer $TOKEN"

# 4. Book. The response carries the PIN the driver must be told out loud.
curl -sX POST "$API/v1/trips" \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{
    "pickup":  {"lat":-26.1076,"lng":28.0567,"address":"Sandton City"},
    "dropoff": {"lat":-26.1467,"lng":28.0436,"address":"Rosebank Mall"},
    "rideType":"standard",
    "idempotencyKey":"quickstart-0001"
  }'

Ready.

Environments

Authentication

South African riders are phone-first, so there are no passwords anywhere in this product. You request a code, you exchange it for tokens, and you refresh.

The sign-in response is deliberately identical whether or not the number is registered. Telling an unauthenticated caller “this number has a SafeCab account” is a safety problem for exactly the people this product exists to protect.

Conventions

• Money is integer cents in ZAR. No floats, anywhere. Displayed prices include 15% VAT; receipts break the VAT out of the total rather than adding it on top.
• Times are epoch milliseconds, UTC. South Africa is UTC+2 with no daylight saving.
• Idempotency. Anything that creates a trip or moves money takes an idempotencyKey. Retrying with the same key returns the original result — a flaky connection must never send two cars or take two payments.
• Errors carry a stable code. Switch on that, never on the message, so we can reword copy without breaking an app three releases behind.

Booking a trip

POST/v1/trips/estimate prices a trip over real roads with traffic applied. POST/v1/trips books it and starts dispatch.

Both sides then confirm. The Guardian accepts the trip; the rider accepts that specific Guardian with POST/v1/trips/{id}/confirm after seeing their name, rating, car, colour and plate.

The PIN handshake

Booking returns a four-digit pin. The driver must enter it before the trip can start. This is the cheapest possible defence against the most common e-hailing attack in South Africa: somebody who is not your driver pulling up and saying your name.

• The PIN is never sent to the driver's client — it is redacted server-side per audience.
• Three wrong attempts locks the trip and raises a safety alert.
• A trip cannot reach in_progress without pin_verified. That guard lives in the shared state machine, so every surface inherits it.

Guardians nearby

GET/v1/trips/nearby?lat=&lng=&rideType=

Returns idle Guardians, the current surge, and which ride tiers are servable at that point. Pass a driverId back as preferredDriverId when booking to offer that Guardian first — they still have to pass every safety filter for the ride type, so this reorders the queue without weakening anything.

Realtime trip stream

WS/v1/trips/{tripId}/ws?token=&lastSeq=

One socket per trip, shared by the rider, the driver, up to three guardians, the ops desk and read-only share viewers. Every server frame carries a monotonic seq. Reconnect with the last one you processed and the server replays what you missed.

const ws = new WebSocket(
  `${API.replace(/^http/, 'ws')}/v1/trips/${tripId}/ws?token=${accessToken}&lastSeq=${lastSeq}`
);

ws.onmessage = (event) => {
  const { type, seq, payload } = JSON.parse(event.data);
  lastSeq = Math.max(lastSeq, seq);

  switch (type) {
    case 'welcome':      render(payload.snapshot); break;
    case 'trip_state':   render(payload.snapshot); break;
    case 'location':     moveCar(payload.driver); break;
    case 'eta':          showEta(payload.etaSeconds); break;
    case 'safety_event': onSafety(payload.event); break;
    case 'prompt':       ask(payload.kind, payload.timeoutSeconds); break;
  }
};

That replay is not a nicety. Load-shedding takes mobile towers down for hours at a time in South Africa, and a guardian watching a child's trip must not be left looking at a frozen map when the signal comes back.

Driver integration

A shift starts with a liveness selfie matched against the driver's enrolled licence photo — the one check that stops an approved account being worked by somebody else, which is what makes every other check meaningful. It fails closed.

The safety model

Every detector emits the same envelope, so the ops desk, the guardian view and trip replay all consume one shape.

{
  "id": "sev_01m11...",
  "tripId": "trp_01m11...",
  "at": 1787830000000,
  "kind": "route_deviation",
  "severity": "alert",
  "source": "detector",
  "data": { "offRouteMeters": 940, "sustainedSeconds": 78 },
  "location": { "lat": -26.118, "lng": 28.061 }
}

Detectors run inside the trip's own Durable Object, synchronously on each location frame, so the critical path never waits on a queue. Budget from detector to an operator seeing it: under two seconds.

Panic button

POST/v1/trips/{tripId}/sos

There is also a covert text channel: a rider can set a safe phrase, and sending it in trip chat raises a critical event without acknowledging anything to anyone. A person under duress cannot press a red button in front of the person threatening them, but they can type a sentence.

The driver is never told that an SOS was raised, at any severity.

Kids and handovers

A guardian creates child profiles, and a child rides on their own account with their own wallet — never a payment method, never a free-text address.

• Pickup needs a photo and the PIN before the car can move.
• Drop-off completes only against an approved receiver, verified by their standing code or by a guardian confirming in-app, inside the drop-off geofence.
• Any mismatch stops the handover, pages every guardian, and the driver is told to wait.
• Up to three guardians watch the same live stream.
• Cash is refused outright on a kids trip. A child should never handle money or end up in a fare dispute at the kerb.

Payments

Ask GET/v1/payments/config at startup rather than hard-coding a payment menu you might not be able to honour.

Card details never reach SafeCab. /v1/payments/cards/setup returns a Stripe SetupIntent client secret that your client confirms directly with Stripe, which is what keeps this platform out of PCI scope.

Webhooks

POST/v1/webhooks/{provider}

The handler verifies the signature, stores the raw body, and enqueues. Processing happens off the request, so a slow ledger write can never make us miss a provider's retry window, and a stored body means any event can be replayed. Duplicate deliveries are acknowledged, not reprocessed.

Errors

{ "error": { "code": "insufficient_funds",
             "message": "Top up your wallet to book this trip.",
             "detail": { "amountCents": 8570, "balanceCents": 2000,
                         "shortfallCents": 6570,
                         "alternatives": ["topup","cash","card"] } } }

Rate limits

OpenAPI

The full machine-readable description is generated from the running deployment, so it can never drift from what is actually deployed: openapi.json. Point your generator at it.

npx @hey-api/openapi-ts -i "$API/v1/openapi.json" -o ./src/safecab