Skip to main content
Every ride moves through a series of statuses from the moment it is booked to the moment it ends. Understanding these statuses helps you build a reliable integration and handle edge cases like cancellations.

​
Status flow

REQUESTED → ACCEPTED → PICKED → COMPLETED
                ↓           ↓          ↓
            CANCELLED   CANCELLED  CANCELLED
1

REQUESTED

Triggered by: RiderWhen you call POST /rides/book, the ride is created with status REQUESTED. The ride is now visible to available drivers via GET /rides/requested.At this point, the ride has a startOtp and endOtp generated by the server. These one-time passwords are used to verify that the correct driver picks up and completes the ride.
2

ACCEPTED

Triggered by: DriverA driver calls POST /rides/status/{rideId} with "status": "ACCEPTED" and their driverId. The ride is assigned to that driver and acceptedAt is recorded.
POST /rides/status/{rideId}

{
  "status": "ACCEPTED",
  "driverId": "42"
}
The rider can now poll GET /rides/status/{rideId} to see the driver’s live location as it updates via driverLat and driverLon.
3

PICKED

Triggered by: DriverWhen the driver arrives and picks up the rider, they call POST /rides/status/{rideId} with "status": "PICKED" and the startOtp provided by the rider. The server validates the OTP before accepting the transition.
{
  "status": "PICKED",
  "driverId": "42",
  "otp": "7391"
}
The startOtp confirms the right driver picked up the right rider. If the OTP is incorrect, the request is rejected.
4

COMPLETED

Triggered by: DriverAt the destination, the driver calls POST /rides/status/{rideId} with "status": "COMPLETED" and the endOtp provided by the rider. The server validates the OTP before marking the ride complete.
{
  "status": "COMPLETED",
  "driverId": "42",
  "otp": "5824"
}
Once completed, the rider can submit a rating and feedback via POST /rides/feedback/{rideId}.

​
Cancelling a ride

Either the rider or the driver can cancel a ride at any point before completion by calling POST /rides/cancel/{rideId}. The request body accepts an optional reason string. 
POST /rides/cancel/{rideId}

{
  "reason": "Driver took too long to arrive"
}
The response includes the updated ride object with status set to CANCELLED, cancelledBy set to the user who cancelled, and cancellationReason populated with the reason you provided.
Cancelling a ride after it has been accepted may incur a cancellation fee. Check the cancellationFee field on the returned ride object to see the amount charged. The fee is determined by platform policy based on the stage at which you cancel.

​
Updating driver location

While a ride is active, the driver should call POST /rides/location/{rideId} periodically to broadcast their position to the rider. 
POST /rides/location/{rideId}

{
  "lat": 12.9716,
  "lon": 77.5946
}
The ride object is returned with updated driverLat, driverLon, and driverLocationUpdatedAt fields.

​
The Ride object

Below is a representative ride object as returned by the API. 
{
  "id": 101,
  "status": "ACCEPTED",
  "riderId": 7,
  "driverId": 42,
  "pickupLocation": "MG Road, Bengaluru",
  "dropLocation": "Whitefield, Bengaluru",
  "pickupLat": 12.9758,
  "pickupLon": 77.6069,
  "dropLat": 12.9698,
  "dropLon": 77.7499,
  "pickupPlusCode": "7J4VXMJM+PQ",
  "dropPlusCode": "7J4VXP2Q+88",
  "pickupLandmark": "Near Cauvery Emporium, MG Road Metro Station",
  "dropLandmark": "ITPL Main Gate, Whitefield",
  "fare": 185.50,
  "paymentMode": "UPI",
  "paymentStatus": "PENDING",
  "paymentReference": null,
  "startOtp": "7391",
  "endOtp": "5824",
  "createdAt": "2026-04-02T10:15:00Z",
  "acceptedAt": "2026-04-02T10:16:30Z",
  "driverLat": 12.9720,
  "driverLon": 77.6050,
  "driverLocationUpdatedAt": "2026-04-02T10:18:00Z",
  "cancellationReason": null,
  "cancelledBy": null,
  "cancellationFee": null,
  "riderRating": null,
  "riderFeedback": null,
  "driverRating": null,
  "driverFeedback": null,
  "riderName": "Alice",
  "riderEmail": "alice@example.com"
}

​
Key fields

FieldDescription
statusCurrent lifecycle status: REQUESTED, ACCEPTED, PICKED, COMPLETED, or CANCELLED
startOtpOne-time password the rider shares with the driver to confirm pickup
endOtpOne-time password the rider shares with the driver to confirm drop-off
fareEstimated fare in INR calculated at booking time
paymentModePayment method chosen at booking (e.g. UPI, CARD, CASH)
paymentStatusCurrent payment status: PENDING, PAID, or FAILED
paymentReferenceRazorpay payment ID, populated after successful payment verification
driverLat / driverLonDriver’s most recent reported coordinates
cancellationFeeFee applied if the ride was cancelled after acceptance
riderRatingRating (1–5) the rider gave the driver after completion
driverRatingRating (1–5) the driver gave the rider after completion