FikaChu Ride Booker API

Partner integration guide for booking on-demand, prebooked, and flexible ridehail (and delivery) through FikaChu.

How to use these docs

1. Start at the developer hub / for product cards and getting-started.
2. Use this guide for auth, flows, curl examples, webhooks, and errors.
3. Track wire cutovers in API_CHANGES.md (/guides/api-changes/).

This document is self-contained for partner integration.

Table of contents

1. Introduction
2. Getting access
3. Environments
4. Auth
5. Ride types at a glance
6. Endpoint reference
7. On-demand rides
8. Prebooked rides
9. Flexible rides
10. Delivery use case
11. Webhooks
12. Errors
13. Sandbox checklist
14. Related APIs
15. FikaChu integration notes

1. Introduction

The Ride Booker API lets third-party platforms (resellers, corporate travel, e-commerce shipping, etc.) create and manage trips on FikaChu without embedding the rider mobile app.

Core pattern for every bookable category:

1. Estimate — POST …/estimations with stops (and schedule when required) → receive categories[], each with one or more fare_id values.
2. Create — POST …/create with a chosen fare_id and the same stops → receive ride_id.
3. Track — poll GET …/details (and on-demand GET …/location), and/or receive webhooks.
4. Finish — GET …/receipt after completion, or POST …/cancel while cancellation is allowed.

fare_id binds vehicle type and payment method. Do not send vehicle_type_id or payment_method on create.

All paths below are relative to your environment base URL (see Environments). Unless noted, every call requires a Bearer access token.

2. Getting access

1. Contact your FikaChu representative to enable Ride Booker API access for your organisation.
2. Obtain OIDC / OAuth client credentials and the identity issuer URL from your FikaChu contact.
3. Confirm which payment methods (cash, wallet, …) and vehicle categories are enabled for your partnership.
4. Optionally register HTTPS webhook endpoints your platform can receive (see Webhooks).

Your integration obtains Bearer tokens from that issuer. FikaChu validates them via OAuth2 token introspection and does not mint partner tokens itself.

3. Environments

Replace the host with the value your FikaChu contact provides.

Example full on-demand estimate URL:

https://api.example.com/ride-booker/v1/rides/estimations

4. Auth

Every Ride Booker request must include:

Authorization: Bearer <access_token>
Content-Type: application/json

4.1 Obtaining a token

Token issuance is performed against the OIDC / OAuth issuer your FikaChu contact provides. A typical client credentials flow looks like:

curl --request POST 'https://oidc.example.com/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'scope=openid'

Example successful response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "openid"
}

Exact scope values and token lifetime depend on your issuer configuration. Cache the token and refresh before expiry (or retry once on 401).

4.2 Using the token

curl --request GET \
  'https://api.example.com/ride-booker/v1/rides/details?ride_id=550e8400-e29b-41d4-a716-446655440000' \
  --header 'Authorization: Bearer YOUR_TOKEN'

Missing, expired, or unintrospectable tokens → 401 Unauthorized.

4.3 Common authentication issues

5. Ride types at a glance

Important: After a prebooked or flexible ride is dispatched into the live matching pool, continue tracking with the on-demand details / cancel / receipt paths using the same ride_id.

Lifecycle states (selected)

Values are the string status field on ride payloads (Ride FSM).

On-demand / in-progress

Prebooked / flexible (scheduled)

6. Endpoint reference

All paths relative to /ride-booker/v1/.

Coordinate convention

• Fika request/response longitude shortform is **lon** (stops, nested booker vehicle, driver_location).
• GBFS MobilityData feeds still use lon (separate contract).

Conventions shared by all creates

7. On-demand rides

Typical flow: Estimate → Create → Track → Receipt (or Cancel before pickup completion rules apply).

7.1 Estimate

POST /rides/estimations

Notes

• stops: minimum 2 waypoints, visited in order.
• Optional payment_methods (e.g. ["cash","wallet"]). Omit to use the intersection of rider-allowed methods across priced vehicle types (defaults to ["cash"] when empty).
• Do not send vehicle_type_id or a single top-level payment_method.
• Each category × allowed payment method yields its own fare_id.
• eta is seconds until nearest eligible driver (or trip routing duration when no online drivers).
• Invalid payment methods for a category are omitted from estimations (not a 400).

Request

{
  "stops": [
    { "lat": -6.7924, "lon": 39.2083, "address": "Masaki, Dar es Salaam" },
    { "lat": -6.8161, "lon": 39.2803, "address": "Julius Nyerere Int'l Airport" }
  ],
  "payment_methods": ["cash", "wallet"]
}

curl

curl --request POST 'https://api.example.com/ride-booker/v1/rides/estimations' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "stops": [
      {"lat": -6.7924, "lon": 39.2083},
      {"lat": -6.8161, "lon": 39.2803}
    ],
    "payment_methods": ["cash"]
  }'

Response 200

{
  "categories": [
    {
      "vehicle_type": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": [{"text": "Economy", "language": "en"}],
        "short_description": [{"text": "Affordable everyday rides", "language": "en"}],
        "description": [{"text": "…", "language": "en"}],
        "vehicle_assets": {
          "icon_url": "https://www.example.com/assets/icon_car.svg",
          "icon_url_dark": "https://www.example.com/assets/icon_car_dark.svg",
          "icon_last_modified": "2021-06-15"
        },
        "rider_capacity": 4,
        "propulsion_type": "combustion",
        "cargo_volume_capacity": 2000,
        "cargo_load_capacity": 1000,
        "max_range_meters": 80,
        "vehicle_image": "https://www.example.com/assets/icon_car_dark.svg"
      },
      "pickup_estimate": 240,
      "no_vehicles_available": false,
      "available_vehicle_count": 3,
      "trip": {
        "distance_estimate": 5.0,
        "distance_unit": "km",
        "duration_estimate": 600
      },
      "estimations": [
        {
          "payment_method": "cash",
          "fare_id": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example-fare-token",
          "expires_at": 1730000000,
          "price": {
            "amount": "12500–12500 TZS",
            "minimum_amount": 12500.0,
            "maximum_amount": 12500.0,
            "currency_code": "TZS"
          }
        }
      ]
    }
  ]
}

Response fields

Store the chosen estimations[].fare_id for create. Prefer expires_at over hard-coding TTL.

7.2 Create

POST /rides/create

Notes

• fare_id is mandatory, single-use, and expires after 5 minutes.
• Stops should match the estimation route (same coordinates and order).
• Optional user.phone / user.name for driver communication; authenticated user remains ride owner unless Developer rules apply.
• On success, persist ride_id for all subsequent calls.

Request

{
  "fare_id": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example-fare-token",
  "stops": [
    { "lat": -6.7924, "lon": 39.2083, "address": "Masaki, Dar es Salaam" },
    { "lat": -6.8161, "lon": 39.2803, "address": "JNIA Terminal 3" }
  ],
  "user": { "phone": "+255700000000", "name": "Asha Mwangi" },
  "notes": "Please call on arrival",
  "webhook_url": "https://partner.example.com/hooks/fikachu-rides"
}

Response 201

{
  "ride_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "SEARCHING",
  "service_type": "ridehail",
  "booking_type": "on_demand",
  "stops": [
    {
      "order": 0,
      "lat": -6.7924,
      "lon": 39.2083,
      "address": "Masaki, Dar es Salaam",
      "notes": ""
    },
    {
      "order": 1,
      "lat": -6.8161,
      "lon": 39.2803,
      "address": "JNIA Terminal 3",
      "notes": ""
    }
  ],
  "estimated_cost": "12500.00",
  "currency": "TZS",
  "payment_method": "cash",
  "notes": "Please call on arrival",
  "created": "2026-08-03T12:00:00.000000Z",
  "user": { "phone": "+255700000000", "name": "Asha Mwangi" }
}

Error examples

• Invalid / expired / already consumed fare_id → 400 { "detail": "Invalid or expired fare_id. Request a new estimation." }
• Foreign phone without Developer group → 403

7.3 Details (track)

GET /rides/details?ride_id=<uuid>

Returns the same RideSerializer shape as create. Poll no more often than about once every 10 seconds unless your agreement says otherwise; prefer webhooks for status fan-out.

curl --request GET \
  'https://api.example.com/ride-booker/v1/rides/details?ride_id=550e8400-e29b-41d4-a716-446655440000' \
  --header 'Authorization: Bearer YOUR_TOKEN'

When a vehicle is assigned, vehicle may look like:

{
  "vehicle_id": "veh_public_123",
  "vehicle_type": {
    "vehicle_type_id": "…",
    "name": "Economy",
    "form_factor": "car",
    "rider_capacity": 4
  },
  "lat": -6.795,
  "lon": 39.21,
  "vehicle_image": null,
  "color": "white",
  "vehicle_plate_no": "T123ABC"
}

and driver_location:

{ "lat": -6.795, "lon": 39.21 }

7.4 Location

GET /rides/location?ride_id=<uuid>

Lightweight live position for active rides only.

Response 200

{
  "lat": -6.8012,
  "lon": 39.2145,
  "last_updated": "2026-08-03T12:05:01.000000Z"
}

Suitable for map polylines (e.g. up to ~1 Hz). Inactive / wrong status → 400.

7.5 Receipt

GET /rides/receipt?ride_id=<uuid>

Call after COMPLETED. Receipt may appear immediately or shortly after finalization (finalize_pending: true until cost breakdown exists).

Response 200

{
  "ride_id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": 12500.0,
  "amount_paid": 0.0,
  "amount_due": 12500.0,
  "currency_code": "TZS",
  "invoice_url": null,
  "invoice_uuid": null,
  "fare_breakdown": [
    { "type": "ride_fee", "amount": 12000.0 },
    { "type": "booking_fee", "amount": 500.0 }
  ],
  "fare_lines": [],
  "finalize_pending": false,
  "payment_status": "pending"
}

7.6 Cancel

POST /rides/cancel

Request

{
  "ride_id": "550e8400-e29b-41d4-a716-446655440000",
  "reason": "Passenger changed plans"
}

Response 200

{
  "ride_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "CANCELLED"
}

Cancellation is only allowed in certain in-flight statuses (on-demand: through ARRIVED_AT_CLIENT, not after driving with client / completed). Wrong state → 400 with detail. Rider cancel via this API sets status to **CANCELLED**.

8. Prebooked rides

Same estimate → create pattern with a future pickup_time.

8.1 Estimate

POST /rides/prebooked/estimations

• pickup_time required: ≥ 30 minutes and ≤ 90 days from now.
• Stops: min 2, same rules as on-demand.
• Response envelope identical: { "categories": [ … fare_id … ] }.
• Fare TTL: 300 seconds.

Request

{
  "pickup_time": "2026-08-10T07:30:00+03:00",
  "stops": [
    { "lat": -6.7924, "lon": 39.2083 },
    { "lat": -6.8161, "lon": 39.2803 }
  ],
  "payment_methods": ["cash"]
}

Error if pickup_time is out of window → 400 { "detail": "pickup_time must be at least 30 minutes in the future." } (or the max-ahead message).

8.2 Create

POST /rides/prebooked/create

Include the same pickup_time and stops used for the fare. Optional delivery / webhook fields apply as on on-demand create.

Request

{
  "fare_id": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example-prebooked-fare",
  "pickup_time": "2026-08-10T07:30:00+03:00",
  "stops": [
    { "lat": -6.7924, "lon": 39.2083, "address": "Hotel lobby" },
    { "lat": -6.8161, "lon": 39.2803, "address": "JNIA" }
  ],
  "user": { "name": "Asha Mwangi", "phone": "+255700000000" },
  "notes": "Flight AB123"
}

Response 201 — same ride shape; typically booking_type: "prebooked", status: "SCHEDULED", pickup_time set.

If server auto-dispatch is enabled, the ride may later move into matching (SEARCHING / on-demand path). After handoff, use on-demand details/cancel/receipt with the same ride_id.

8.3 Details / cancel / history

History response 200 (paginated)

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "ride_id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "SCHEDULED",
      "service_type": "ridehail",
      "booking_type": "prebooked",
      "pickup_time": "2026-08-10T04:30:00Z",
      "stops": [],
      "vehicle": null,
      "driver_location": null,
      "estimated_cost": "12500.00",
      "currency": "TZS",
      "total_cost": null,
      "payment_method": "cash",
      "start_time": null,
      "end_time": null,
      "notes": "Flight AB123",
      "manifest_items": [],
      "manifest_actions": [],
      "created": "2026-08-03T12:00:00.000000Z",
      "user": { "phone": "+255700000000", "name": "Asha Mwangi" }
    }
  ]
}

9. Flexible rides

Flexible rides pre-create a booking token / ride the passenger can use when ready.

9.1 Estimate

POST /rides/flexible/estimations

Stops and pickup_time are optional. Response still uses the shared { "categories": […] } envelope with **fare_id** per vehicle type × payment method (not a separate vehicle-type-only booking field).

Flexible fare tokens use a longer TTL: 86 400 seconds (24 hours).

Request (minimal)

{
  "payment_methods": ["cash"]
}

Request (with stops)

{
  "stops": [
    { "lat": -6.7924, "lon": 39.2083 },
    { "lat": -6.8161, "lon": 39.2803 }
  ],
  "pickup_time": "2026-08-03T18:00:00+03:00",
  "payment_methods": ["cash"]
}

Response — same shape as on-demand estimations.

9.2 Create

POST /rides/flexible/create

fare_id required. Stops optional; if omitted, placeholder coordinates may be used until updated.

Request

{
  "fare_id": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example-flexible-fare",
  "stops": [
    { "lat": -6.7924, "lon": 39.2083 },
    { "lat": -6.8161, "lon": 39.2803 }
  ],
  "user": { "name": "Asha Mwangi", "phone": "+255700000000" }
}

Response 201 — ride with booking_type: "flexible", often SCHEDULED / READY_TO_DISPATCH depending on configuration.

9.3 Details / cancel

• GET /rides/flexible/details?ride_id=
• POST /rides/flexible/cancel with { "ride_id", "reason"? } before on-demand dispatch

After dispatch, use on-demand endpoints with the same ride_id.

10. Delivery use case

Delivery rides use the same estimate/create endpoints. On create, set:

• service_type: "delivery"
• manifest_items[]: cargo catalog (external_id is the stable id)
• stops[].actions[]: pickup | dropoff | return with item_external_ids listing catalog external_ids
• Optional stops[].verification_requirements for proof of delivery

Quantities must balance across the trip (pickup / dropoff / return). Unknown requirement keys → 400.

10.1 Create delivery example

Estimate first with the same stop coordinates (actions are not required on estimate). Then:

Request

{
  "fare_id": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example-fare-token",
  "service_type": "delivery",
  "notes": "Handle with care",
  "webhook_url": "https://shop.example.com/api/webhook/shipping/",
  "manifest_items": [
    {
      "external_id": "BOX-1",
      "name": "Cell phone box",
      "quantity": 1,
      "weight": 30,
      "price": 10000,
      "dimensions": { "length": 40, "width": 40, "height": 40 },
      "is_fragile": true
    },
    {
      "external_id": "LAP123",
      "name": "Laptop",
      "quantity": 2,
      "weight": 3000,
      "price": 12000,
      "dimensions": { "length": 30, "width": 10, "height": 20 }
    }
  ],
  "stops": [
    {
      "lat": -6.78652,
      "lon": 39.259711,
      "address": "Warehouse A",
      "notes": "Pickup parcels",
      "actions": [
        { "type": "pickup", "item_external_ids": ["BOX-1", "LAP123"] }
      ]
    },
    {
      "lat": -6.798702,
      "lon": 39.255937,
      "address": "Customer B",
      "notes": "Dropoff phone box",
      "actions": [
        { "type": "dropoff", "item_external_ids": ["BOX-1"] }
      ],
      "verification_requirements": {
        "pincode": { "enabled": true, "value": "4242" },
        "picture": { "enabled": true },
        "signature": { "enabled": true, "collect_signer_name": true },
        "barcodes": {
          "enabled": true,
          "barcodes": [{ "type": "CODE128", "value": "BOX-1" }]
        }
      }
    },
    {
      "lat": -6.78652,
      "lon": 39.259711,
      "address": "Warehouse A",
      "notes": "Return laptops",
      "actions": [
        { "type": "return", "item_external_ids": ["LAP123"] }
      ]
    }
  ],
  "user": { "name": "Shop Desk", "phone": "+255711111111" }
}

Response 201 (excerpt)

{
  "ride_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "SEARCHING",
  "service_type": "delivery",
  "booking_type": "on_demand",
  "manifest_items": [
    {
      "external_id": "BOX-1",
      "name": "Cell phone box",
      "quantity": 1.0,
      "weight": 30.0,
      "length": 40.0,
      "width": 40.0,
      "height": 40.0,
      "price": 10000.0,
      "is_fragile": true,
      "must_be_upright": false
    }
  ],
  "manifest_actions": [
    {
      "stop_order": 0,
      "action": "pickup",
      "item_external_ids": ["BOX-1", "LAP123"]
    },
    {
      "stop_order": 1,
      "action": "dropoff",
      "item_external_ids": ["BOX-1"]
    },
    {
      "stop_order": 2,
      "action": "return",
      "item_external_ids": ["LAP123"]
    }
  ],
  "stops": [
    {
      "order": 1,
      "lat": -6.798702,
      "lon": 39.255937,
      "address": "Customer B",
      "notes": "Dropoff phone box",
      "verification_requirements": {
        "pincode": { "enabled": true, "value": "4242" },
        "picture": { "enabled": true },
        "signature": { "enabled": true, "collect_signer_name": true },
        "barcodes": {
          "enabled": true,
          "barcodes": [{ "type": "CODE128", "value": "BOX-1" }]
        }
      },
      "verification": {}
    }
  ]
}

10.2 Verification requirement keys

Only these top-level keys are allowed:

10.3 Partner expectations during fulfillment

Partners do not upload PoD media on the booker API. Drivers collect evidence via the driver app:

• POST /drivers/v1/trips/{ride_id}/stops/{stop_order}/verification-media
• PATCH /drivers/v1/trips/{ride_id} with arrive_at_stop / complete and verification

Partners should:

1. Poll GET /rides/details (or consume webhooks) for status and stop verification blobs.
2. Treat completed delivery when status is COMPLETED and required stop verifications are present.

After driver start, FikaChu advances current_stop_index past pickup when a next stop exists (drivers are not asked to re-confirm stop 0).

11. Webhooks

11.1 Registering a URL

Pass webhook_url on create (HTTPS recommended):

"webhook_url": "https://shop.example.com/api/webhook/shipping/"

FikaChu POSTs JSON when ride status events are delivered. Retries: up to 3 attempts with delay on failure.

11.2 Envelope

Outbound body matches the realtime envelope:

{
  "schema": "fika.v1",
  "type": "ridebooker",
  "event_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "event_time": 1722686400,
  "event_type": "rides_ride.status_changed",
  "meta": {
    "ride_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "SEARCHING",
    "service_type": "delivery",
    "user_id": "42"
  }
}

Headers: Content-Type: application/json. Respond with 2xx quickly; slow or non-2xx responses are retried.

11.3 Recommended partner handling

1. Deduplicate on event_id.
2. Update your order from meta.status / meta.ride_id.
3. Optionally confirm with GET /rides/details before showing terminal states to end users.
4. Do not expose your webhook URL publicly without verification (network allowlists, shared secret at your edge, etc.). FikaChu ride webhooks currently POST without a platform HMAC header—protect the endpoint yourself.

12. Errors

12.1 Shapes

Field validation:

{
  "stops": ["Ensure this field has at least 2 elements."],
  "fare_id": ["This field is required."]
}

Generic:

{ "detail": "Invalid or expired fare_id. Request a new estimation." }

Nested verification errors may appear under keys such as verification_requirements, pincode, barcodes.

12.2 HTTP status codes

12.3 Common issues

13. Sandbox checklist

Use the staging / sandbox host your FikaChu contact provides:

1. Obtain a Bearer token from the issuer.
2. POST /rides/estimations with two stops → pick a fare_id.
3. POST /rides/create within 5 minutes → store ride_id.
4. Poll GET /rides/details and/or receive a webhook.
5. Optional: create a delivery with manifest + verification_requirements + webhook_url.
6. On completion, GET /rides/receipt.

14. Related APIs

Not required for core Ride Booker integration; see API_CHANGES.md for details.

Rental find/ring: POST /ride-booker/v1/rentals/{ride_id}/ping-vehicle (in session) or POST /drivers/v1/rental-vehicles/{vehicle_id}/ping-vehicle (browse). Body { lat, lon }; refused beyond 200 m (ping_too_far). Do not send typed alarmArm. Errors: 400 (not configured / no equipment / too far), 404 (no device), 502 (IoT delivery). See API_CHANGES.md (2026-08-15).

15. FikaChu integration notes

Support

Include when contacting FikaChu support: environment host, UTC timestamp, ride_id / fare_id (if any), HTTP status, and response detail or validation body.