Get started
Welcome to the Paisha API
The Paisha API makes it convenient to tap into the digital network that spans across cities. By sending requests to our API endpoints, we provide you with everything necessary to create innovative and enchanting experiences for your users. The possibilities are limitless!
Production API
All production API requests are made to:
https://<paisha-production-api-domain-url>/api/<version>
The current version of our API is v1 If there are any changes that are not compatible with previous versions, we will increment the version number. Some of our API endpoints require JWT Authorization. To get started, please refer to the Authentication & Authorization guide.
Sandbox API
During the development and testing phase, we offer a sandbox environment where requests should be made to:
https://<paisha-sandbox-api-domain-url>/api/<version>
Feel free to explore the sandbox environment to refine your applications before moving to the production environment.
REST API
The Paisha API is a RESTful API, which implies that it is structured to enable you to retrieve, create, modify, and remove objects using the HTTP methods GET, POST, PUT, PATCH, and DELETE.
JSON
The Paisha API exclusively communicates using JSON. Therefore, it is crucial to include the Content-Type header in your requests and set it to application/json. This ensures that your requests are correctly recognized and processed by the API.
Authentication
All API calls for the Paisha API require authentication using either basic or JWT bearer token, depending on the specific endpoint. Bearer tokens are used to authorize your application to access the Paisha API on behalf of a user. These tokens are obtained once a user has granted authorization to your application through one of the supported OAuth 2.0 authorization grants. Bearer tokens remain valid for authentication across all API endpoints.
Pagination
Certain endpoints, like Rider History, can potentially return a large array of objects. To ensure manageable response sizes, the Paisha API utilizes pagination. Pagination is a method that allows the API to return a subset of results for a specific request and enables subsequent requests to navigate through the remaining results until reaching the end. Paginated endpoints adhere to a standardized interface that involves two query parameters: limit and offset. The response payload follows a standardized format.
The limit parameter specifies the maximum number of objects to be included in the response, while the offset parameter determines the starting point for fetching the objects. These parameter names and their functionality are inspired by the LIMIT and OFFSET keywords used in MYSQL.
Example: The SQL query below says "return only 10 records, start on record 16 (OFFSET 15)": $sql = "SELECT * FROM Orders LIMIT 10 OFFSET 15";
Versioning
The Paisha API undergoes continuous development to introduce new features, enhancements, and bug fixes. Consequently, you should anticipate and be prepared for changes that are introduced and documented. Whenever a significant modification is made to an endpoint, the version number in the resource's path will be incremented.
However, there are certain changes or additions that are considered backwards-compatible, and your applications should be designed to accommodate them. These include:
- Addition of new endpoints to the API: New endpoints may be added to provide additional functionality or access to new resources.
- Addition of new attributes to the response of an existing endpoint: Existing endpoints may have new attributes included in their response payload, providing more information or data.
- Changing the order of attributes in response: JSON, being an object of unordered key/value pairs, does not guarantee a specific order of attributes. Therefore, the order of attributes in the response payload may change over time.
Common Types
In the Paisha API, the IDs assigned to resources are not guaranteed to be universally unique identifiers (UUIDs), and their length may vary.
Date and time values in the API are represented as integers, indicating the number of seconds elapsed since the Unix epoch in Coordinated Universal Time (UTC).
Latitude and longitude values are expressed as double numbers, allowing up to six decimal places of precision. This precision applies to both the request and response formats.
Phone numbers are formatted using the E.164 standard, which provides a globally recognized and standardized format for phone numbers.
Country codes in the Paisha API are expressed using the ISO 3166-1 alpha-3 code, which is a three-letter code representing a specific country.
Please ensure that your application handles these data types and formats correctly to ensure accurate processing and compatibility with the Paisha API.
Errors & HTTP Status Codes
The Paisha API uses the following error codes or http status codes:
| Error or Status Code | Meaning |
|---|---|
| 200 | OK. Everything worked as expected |
| 201 | Created, we will return a 201 after succesful POST where resource was created. |
| 302 | Retry Request, url my be given for redirect |
| 400 | Malformed request. |
| 401 | Unauthorized. The request requires user authentication (not logged in). Also used for invalid OAuth 2.0 credentials. |
| 402 | Forbidden. Also used for unauthorized requests such as improper OAuth 2.0 scopes or permissions issues. |
| 403 | User not allowed. User is banned and is not permitted to request a ride |
| 404 | Not found |
| 406 | Unacceptable content type. Client sent an accepts header for a content type which does not exist on the server. Body includes a list of acceptable content types, such as “Unacceptable content type. Request resource as: application/json. |
| 409 | A conflict needs to be resolved before the request can be made. |
| 422 | Invalid request. The request body is parse-able however with invalid content or there are issues with a rider’s user account. |
| 429 | Too Many Requests. Exceeded the rate limit for requests. |
| 500 | Internal Server Error. |
| 503 | The backend server is not available. |
Errors
Consistently formatted JSON bodies will be provided for error responses. These JSON bodies may contain a variety of keys, including:
| Key | Value |
|---|---|
message |
Human redable message which corresponds to the clients error. |
code |
Undercored delimited string |
fields(optional) |
A hash of field names that have validations. This has a value of an array with member strings that describe the specific validation error. |
Error Response
Status-Code: 422 Invalid Request
{
"message": "Invalid user",
"code": "invalid",
"fields": {
"first_name": ["Required"]
}
}
API Endpoints
| Method | Endpoint | Description |
|---|---|---|
| POST | /getToken | Get JWT Token |
| GET | /products | List products |
| GET | /products/{productId} | Get product details |
| GET | /estimates/price | Get price estimates |
| GET | /estimates/time | Get time estimates |
| GET | /me | Get user information |
| GET | /history | Get user history |
| GET | /places/{place_id} | Get saved place |
| PUT | /places/{place_id} | Update a saved place |
| PATCH | /me | Apply a user promotion |
| POST | /requests/estimate | Get request estimate |
| POST | /requests | Create ride request |
| GET | /requests/{requestId} | Get ride details |
| PATCH | /requests/{requestId} | Update request |
| GET | /requests/{requestId}/receipts | Get receipt |
GET JWT Authentication Token
# Here is a curl example for get getToken request
curl \
-X POST https://<paisha-sandbox-api-domain-url>/api/<version>/getToken \
-F 'secret_key=your_api_key_shared_to_you' \
-F 'client_id=your_client_id_shared_to_you' \
-F 'expire_in=1624345246'
To get JWT token you need to make a POST call to the following endpoint :
/getToken
You will be provided with secrete key to used to generate JWT, Algorithm to be used will be HS512
Check parameters description that will be required to request JWT Token in query parameters table
Success Result example :
{
"token_type":"Bearer",
"expire_in":1685691464,
"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJqdGkiOiI2NDc5MGY3ODIwN2JjIiwiaWF0IjoxNjI0MzQ1MjQ2LCJzdWIiOiJha
XJ0ZWxfYWZyaWNhIiwiaXNzIjoiYWlydGVsX2FmcmljYSIsIlBheWxvYWQiOnsidHhuSWQiOiIifSwiZXhwIjozNjc4NzM1MTM4fQ.-2jUejeHoc-5Gr7Dac2F4nzZWyJb4AcQaZIx__dMRDZfYoqa1ePQH9ILjaUf4AhWBnafIrsgYcvHiIweSksQjQ",
}
REQUEST QUERY PARAMETERS
| Field | Type | Description |
|---|---|---|
| secret_key | String | Your Secrete or password that will be used to generate JWT Token, this will be provided during onbording process and needs to be sent as base64 encoded when making request |
| client_id | String | A client Id of your Application, this will be provided during onboarding process |
| expire_in | String | A timestamp representing the expiration time expressed in seconds as integer indicating the number of seconds elapsed since unix EPOCH. Now being the time request was sent. Feel free to set any expire date you wish |
Use bearer token
You have the option to use the token obtained in the authorization request as a bearer token in the Authorization header
Example: OAuth token sent in a header
Replace
# Here is a curl example to use bearer token
curl -H "Authorization: Bearer " \
https://development.paisha.app/api/v1/products?latitude=-6.7677829&longitude=38.5948978 Request-Response =>
#Example products request
curl -H 'Authorization: Bearer ' \
-H 'Content-Type: application/json' \
'https://development.paisha.app/api/v1/products?latitude=-6.7677829&longitude=38.5948978' Response
Status-Code 200 OK
#Response from products request
{
"products": [
{
"upfrontfareEnabled": true,
"numberOfSeats": 4,
"productId": "b065aaca-01dd-11ee-be56-0242ac120002",
"priceDetails": {
"serviceFees": [
{
"fee": 200,
"name": "Booking fee"
}
],
"pricePerMinute": 100.0,
"distanceUnit": "km",
"minimumFare": 3000,
"pricePerKm": 900,
"baseFare": 1000,
"cancellationFee": 0,
"currencyCode": "TZS"
},
"image": "https://paisha-storage.s3.eu-west-2.amazonaws.com/ride/ride-type/2023-05-21-646a59bb33150.png",
"cashEnabled": false,
"shared": false,
"shortDescription": "car",
"displayName": "car",
"productCategory": "car",
"description": "Best Ride Ever"
},
{
"upfrontfareEnabled": false,
"numberOfSeats": 1,
"productId": "b065aaca-01dd-11ee-be56-0242ac120003",
"priceDetails": {
"serviceFees": [
{
"fee": 250,
"name": "Booking fee"
}
],
"pricePerMinute": 100.0,
"distanceUnit": "km",
"minimumFare": 3000,
"pricePerKm": 900,
"baseFare": 1000,
"cancellationFee": 0,
"currencyCode": "TZS"
},
"image": "https://paisha-storage.s3.eu-west-2.amazonaws.com/ride/ride-type/2023-05-21-646a59bb33150.png",
"cashEnabled": true,
"shared": false,
"shortDescription": "boda",
"displayName": "Boda boda",
"productCategory": "bodabda",
"description": "Best Cheap shared Ride Ever for every day life"
},
{
"upfrontfareEnabled": false,
"numberOfSeats": 3,
"productId": "b065aaca-01dd-11ee-be56-0242ac120004",
"priceDetails": {
"serviceFees": [
{
"fee": 250,
"name": "Booking fee"
}
],
"pricePerMinute": 100.0,
"distanceUnit": "km",
"minimumFare": 3000,
"pricePerKm": 900,
"baseFare": 1000,
"cancellationFee": 0,
"currencyCode": "TZS"
},
"image": "https://paisha-storage.s3.eu-west-2.amazonaws.com/ride/ride-type/2023-05-21-646a59bb33150.png",
"cashEnabled": true,
"shared": true,
"shortDescription": "bajaji",
"displayName": "Bajaji",
"productCategory": "bajaji",
"description": "Best Cheap shared Ride Ever for every day life"
}
]
}
GET /products
Products
The Products endpoint for Paisha provides information about the available Paisha products at a specific location. The response includes details like the product's display name like car, boda or bajaji and other relevant information, presenting the products in the correct order for display. However, certain products like Food or Grocery etc are not included in the response from this endpoint.
It's important to note that the information returned by this endpoint doesn't reflect real-time availability of the products or ride categories. To obtain real-time availability and estimated time of arrival (ETA) for the products, please utilize the Time Estimates endpoint.
Additionally, please be aware that the list of products returned by this endpoint may vary based on the time of day in certain markets. This variation is due to time and zone restrictions on when specific products can be utilized.
Resource
GET /api/v1/products
Use Bearer token for Authorization obtained in previous steps
REQUEST QUERY PARAMETERS
| Field | Type | Description |
|---|---|---|
| latitude | double | latitude component of location |
| longitude | double | longitude component of location |
Example products request
Replace token obtained from authorization process
GET /products/{productId}
Products Details
Request-Response =>
#Response from products request by productId
{
"products": [
{
"upfrontfareEnabled": true,
"numberOfSeats": 4,
"productId": "b065aaca-01dd-11ee-be56-0242ac120002",
"priceDetails": {
"serviceFees": [
{
"fee": 200,
"name": "Booking fee"
}
],
"pricePerMinute": 100.0,
"distanceUnit": "km",
"minimumFare": 3000,
"pricePerKm": 900,
"baseFare": 1000,
"cancellationFee": 0,
"currencyCode": "TZS"
},
"image": "https://paisha-storage.s3.eu-west-2.amazonaws.com/ride/ride-type/2023-05-21-646a59bb33150.png",
"cashEnabled": false,
"shared": false,
"shortDescription": "car",
"displayName": "car",
"productCategory": "car",
"description": "Best value for money"
},
]
}
The endpoint for Product Details provides information regarding a specific Paisha product. The response contains essential details about the product, including its display name and other relevant information.
Resource
GET /api/v1/products/{productId}
Use Bearer token for Authorization obtained in previous steps
REQUEST QUERY PARAMETERS
| Field | Type | Description |
|---|---|---|
| productId | string | It represents a unique identifier that corresponds to a specific product based on the provided latitude and longitude. |
Example products request
Replace token obtained from authorization process
#Example products request by product id
curl -H 'Authorization: Bearer ' \
-H 'Content-Type: application/json' \
'https://development.paisha.app/api/v1/products/b065aaca-01dd-11ee-be56-0242ac120002'
Response
Status-Code 200 OK
GET /estimates/price
Request-Response =>
curl -H 'Authorization: Token <ACCESS_TOKEN >' \
-H 'Content-Type: application/json' \
'https://development.paisha.app/api/v1/estimates/price?startLatitude=-6.7752315&startLongitude=37.418075&endLatitude=-6.7752415&endLongitude=-37.8518075'
Response
Status-Code 200 OK
#Response From price estimate Request
{
"prices": [
{
"localizedDisplayName": "bodaboda",
"distance": 6.17,
"displayName": "bodaboda",
"productId": "b065aaca-01dd-11ee-be56-0242ac120001",
"highEstimate": 1300,
"lowEstimate": 1000,
"duration": 1080,
"estimate": "1000-1300",
"currencyCode": "TZS"
},
{
"localizedDisplayName": "car",
"distance": 6.17,
"displayName": "car",
"productId": "b065aaca-01dd-11ee-be56-0242ac120002",
"highEstimate": 1500,
"lowEstimate": 1300,
"duration": 1080,
"estimate": "1300-1500",
"currencyCode": "TZS"
},
{
"localizedDisplayName": "bajaji",
"distance": 10,
"displayName": "bajaji",
"productId": "b065aaca-01dd-11ee-be56-0242ac120003",
"highEstimate": 1700,
"lowEstimate": 1300,
"duration": 1080,
"estimate": "1300-1700",
"currencyCode": "TZS"
},
{
"localizedDisplayName": "paishaXL",
"distance": 10,
"displayName": "paishaXL",
"productId": "b065aaca-01dd-11ee-be56-0242ac120004",
"highEstimate": 25000,
"lowEstimate": 20000,
"duration": 1080,
"estimate": "20000-25000",
"currencyCode": "TZS"
}
]
}
Price Estimates
The Price Estimates endpoint of the Paisha API provides an estimated price range for each product available in a specific area. The estimated price is returned as a formatted string, displaying the full range along with the localized currency symbol.
In addition to the price range, the response may include low and high estimates, as well as the ISO 4217 currency code for cases that involve currency conversion. If there is a surge in effect for a particular product, the surge multiplier will be greater than 1. However, the provided price estimate already incorporates this multiplier.
It's important to note that the Price Estimates endpoint does not reflect real-time product availability. To obtain real-time availability and estimated time of arrival (ETA) for products, please utilize the Time Estimates endpoint instead.
Resource
GET /api/v1/estimates/price
Use Bearer token for Authorization obtained in previous steps
REQUEST QUERY PARAMETERS
| Field | Type | Description |
|---|---|---|
| startLatitude | double | Latitude component of start location. |
| startLongitude | double | Longitude component of start location. |
| endLatitude | double | Latitude component of end location. |
| endLongitude | double | Longitude component of end location. |
Example Price Estimate Request
Replace <ACCESS_TOKEN > with token obtained from authorization process
Request-Response
curl -H 'Authorization: Token <ACCESS_TOKEN >' \
curl -H 'Authorization: Bearer <ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
'https://development.paisha.app/api/v1/estimates/time?startLatitude=-6.7752315&startLongitude=37.2180750''
#Response From time estimates Request
{
"times": [
{
"localizedDisplayName": "car",
"estimate": 60,
"displayName": "car",
"productId": "b065aaca-01dd-11ee-be56-0242ac120001"
},
{
"localizedDisplayName": "bodaboda",
"estimate": 60,
"displayName": "bodaboda",
"productId": "ab065aaca-01dd-11ee-be56-0242ac120002"
},
{
"localizedDisplayName": "bajaji",
"estimate": 240,
"displayName": "bajaji",
"productId": "b065aaca-01dd-11ee-be56-0242ac120003"
},
{
"localizedDisplayName": "paishaXL",
"estimate": 240,
"displayName": "paishaXL",
"productId": "b065aaca-01dd-11ee-be56-0242ac120004"
}
]
}
GET /estimates/time
Time Estimates
The Time Estimates endpoint of the Paisha API returns estimated time of arrival (ETA) for all available products at a specific location. The ETA for each product is expressed in seconds as integers.
If a product is returned from the GET /api/v1/products endpoint but not from the Time Estimates endpoint for a given latitude/longitude pair, it indicates that there are currently no available instances of that particular product for requesting.
We recommend calling this endpoint periodically, ideally every minute, to ensure accurate and up-to-date ETAs. This will provide the most reliable information on estimated arrival times.
In certain markets, the list of products returned from this endpoint may vary based on the time of day. This is because certain products have time restrictions on when they can be utilized. Therefore, the availability of products may change depending on the time of the day.
Using the Time Estimates endpoint regularly will help you stay updated with the latest information on product availability and ETAs for a given location.
Resource
GET /api/v1/estimates/time
Use Bearer token for Authorization obtained in previous steps
REQUEST QUERY PARAMETERS
| Field | Type | Description |
|---|---|---|
| startLatitude | double | Latitude component. |
| startLongitude | double | Longitude component. |
| productId | string | Unique identifier representing a specific product for a given latitude & longitude |
Example Time Estimate request
Replace <ACCESS_TOKEN> with token obtained from authorization process
Response
Status-Code 200 OK
Request-Response
curl -X POST \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
"productId": "ab065aaca-01dd-11ee-be56-0242ac120002",
"startLatitude": -6.7751279,
"startLongitude": 37.9197515,
"endLatitude": -6.8773228,
"endLongitude": 37.6272052
}' "https://development.paisha.app/api/v1/requests/estimate"
#Response From request estimates
{
"fare": {
"value": 10000.00,
"fareId": "521349b8-5e83-414c-99f6-ea7b7ff357f4",
"expiresAt": 1685995391,
"display": "10000.00",
"currencyCode": "TZS",
"breakdown": [
{
"type": "discount",
"value": -1000.00,
"name": "Discount"
},
{
"type": "base_fare",
"notice": "Fares are higher due to demand today",
"value": 1000,
"name": "Base Fare"
}
]
},
"trip": {
"distanceUnit": "km",
"durationEstimate": 540,
"distanceEstimate": 10.5
},
"pickupEstimate": 2
}
#Another simple example
#request
curl -X POST -H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" -d \
'{
"productId": "ab065aaca-01dd-11ee-be56-0242ac120002",
"startLatitude":"-6.775232",
"startLongitude": "37.4197513",
"endLatitude":"-6.7899886", "endLongitude": "37.4021253"}' \
https://development.paisha.app/api/v1/requests/estimate
#Response
{
"fare": {
"value": 4000,
"fareId": "521349b8-5e83-414c-99f6-ea7b7ff357f4",
"expiresAt": 1685995391,
"display": "4000",
"currencyCode": "TZS"
},
"trip": {
"distanceUnit": "km",
"durationEstimate": 600,
"distanceEstimate": 5
},
"pickupEstimate": 4
}
POST /requests/estimate
Ride Request - Estimates
The Request Estimate endpoint in the Paisha API allows you to get an estimate for a ride based on the desired product, start location, and end location. It provides information about the fare or an estimated range, depending on the product's configuration.
Using this endpoint, you can obtain an upfront fare before actually requesting a ride. It is especially useful when upfront fares are not enabled for a specific product or location. Additionally, you can check if surge pricing is in effect for the product and location by making a request to this endpoint. By doing this preemptively, you can inform the user about surge pricing and provide them with a surge confirmation link (surge_confirmation_href) obtained from the API response.
To ensure a smooth user experience, it is recommended to utilize this endpoint before initiating a ride request. By doing so, you can display the fare estimate or surge information to the user and allow them to confirm the request accordingly.
Depending on the product's configuration, the response from this endpoint can include either an upfront fare (available in the "fare" key) or a range estimate (available in the "estimate" key). The specific type of estimate returned will depend on how the product is set up and configured.
Resource
GET /api/v1/requests/estimate
Use Bearer token for Authorization obtained in previous steps
REQUEST QUERY PARAMETERS
| Field | Type | Description |
|---|---|---|
| productId | string | The unique ID of the product being requested. If none is provided, it will default to the cheapest product for the given location. |
| startLatitude | double | The beginning or “pickup” latitude. This must be specified |
| startLongitude | double | The beginning or “pickup” longitude. |
| endLatitude | double | The end or “destination” latitude. |
| endLongitude | double | The end or “destination” longitude. |
Example Time Estimate request
Replace <ACCESS_TOKEN> with token obtained from authorization process
Response
Status-Code 200 OK
Request-Response
curl -X POST -H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" -d \
'{
"productId": "ab065aaca-01dd-11ee-be56-0242ac120002",
"startLatitude":"-6.775232",
"startLongitude": "37.4197513",
"endLatitude":"-6.7899886",
"endLongitude": "37.4021253",
"customerPhoneNumber":"255768111111",
"customerName":"Maria"
"fareId":"521349b8-5e83-414c-99f6-ea7b7ff357f4"}' \
https://development.paisha.app/api/v1/requests
#Response
{
"status": "processing",
"productId": "ab065aaca-01dd-11ee-be56-0242ac120002",
"destination": {
"latitude": -6.7899886,
"longitude": 37.4021253
},
"driver": null,
"pickup": {
"latitude": -6.775232,
"longitude": 37.4197513
},
"requestId": "40f77f03-98b9-4704-aca7-f4f323205643",
"eta": null,
"location": null,
"vehicle": null,
"shared": false
}
POST /requests
Ride Request - Create
The Ride Request endpoint in the Paisha API enables you to request a ride on behalf of a Paisha user. It allows your application to initiate a ride request and provide a seamless experience for users.
The Paisha API lets you Request a Paisha Product for riders. Given you know a rider’s location, where they want to go, and which Paisha product they want, you can request a ride for them with a few simple API endpoints.
1. In the products endpoint GET /products, products have the upfront_fare_enabled field set to true.
2. Use the request estimate endpoint POST /requests/estimate with a productId to get a fareId. The fareId is used to set an upfront fare and arrival time for a trip. The fareId expires after two minutes. If the fareId expires or isn’t valid, a 422 error is returned.
2 Request a ride using the request endpoint POST /requests with the fareId returned in the previous step.
Resource
POST /api/v1/requests
Use Bearer token for Authorization obtained in previous steps
REQUEST QUERY PARAMETERS
| Field | Type | Description |
|---|---|---|
| productId | string | The unique ID of the product being requested. |
| startLatitude | double | The beginning or “pickup” latitude. This must be specified |
| startLongitude | double | The beginning or “pickup” longitude. |
| endLatitude | double | The end or “destination” latitude. |
| endLongitude | double | The end or “destination” longitude. |
| customerName | string | Name for the customer that can be displayed to driver |
| customerPhoneNumber | string | Phone number for customer so that driver can call the customer |
Example create ride request
Replace <ACCESS_TOKEN> with token obtained from authorization process
There are three potential outcomes when making this request:
1. If your request is valid and all the necessary information, such as the product, start location, and end location, are provided correctly, you will receive a 202 Accepted response. This means that your request has been received and is being processed.
2. However, if there are no drivers available in your area or at the given time, you will receive a 409 Conflict response. This indicates that an error occurred, specifically due to the unavailability of drivers.
3. Another possibility is receiving a 422 Unprocessable Entity response. This typically occurs when there is an issue with the rider's Paisha account, such as an invalid payment method or an account-related problem. The error is likely attributed to the rider's account and not the request itself.
In most cases, when you provide valid information for the product, start location, and end location, you can expect to receive a 202 Accepted response, indicating that your request is being processed.
Response
Status-Code 202 Accepted
Request-Response
curl -H 'Authorization: Bearer <ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
'https://development.paisha.app/api/v1/requests/<REQUEST_ID>'
#Response
{
"productId": "17cb78a7-b672-4d34-a288-a6c6e44d5315",
"requestId": "a1111c8c-c720-46c3-8534-2fcdd730040d",
"status": "accepted",
"shared": true,
"driver": {
"phoneNumber": "+255717222000",
"smsNumber": "+255717222000",
"rating": 5,
"pictureUrl": "https://paisha-storage.s3.eu-west-2.amazonaws.com/driver/2023-05-21-646a59bb33150.png",
"name": "John Doe"
},
"vehicle": {
"make": "Toyota",
"model": "Vits",
"licensePlate": "T123PAISHA",
"pictureUrl": "https://paisha-storage.s3.eu-west-2.amazonaws.com/ride/ride-type/car.png"
},
"location": {
"latitude": -6.3382129093,
"longitude": 37.8863287568,
"bearing": 328
},
"pickup": {
"latitude": -6.3303463,
"longitude": 37.8890484,
"name": "11 Urisno St.",
"address": "11 Urisno St. Mikocheni, dar es salaam",
"eta": 5
},
"destination": {
"latitude": 37.6213129,
"longitude": -122.3789554,
"name": "12 Mwenge St.",
"address": "12 Mwenge St. mwenge",
"eta": 19
},
"waypoints": [
{
"riderId":0f613db2-05e6-11ee-be56-0242ac120002,
"latitude":37.77508531,
"type":"pickup",
"longitude":-122.3976683872
},
{
"riderId":"0f613db2-05e6-11ee-be56-0242ac120002",
"latitude":-6.7752423,
"type":"dropoff",
"longitude":37.4175658
}
],
"riders":
[
{
"riderId":"0f613db2-05e6-11ee-be56-0242ac120002",
"firstName":"Maria",
"phoneNumber": +255768000000
},
]
}
GET /requests/{requestId}
Ride Request - Details and Trip Status
The Ride Request endpoint allows retrieving the status of an ongoing or completed trip that was created by your app.
Resource
GET /api/v1/requests/{requestId}
Use Bearer token for Authorization obtained in previous steps
REQUEST QUERY PARAMETERS
| Field | Type | Description |
|---|---|---|
| requestId | string | Unique identifier representing a Request. |
Example request status
Replace <ACCESS_TOKEN> with token obtained from authorization process
There are three potential outcomes when making this request:
Response
Status-Code 200 OK
Trips fields
- Driver
- Vehicle
- Location
- Pickup
- Destination
- Riders
- Waypoints
# For completed request response will look like this.
{
"status": "completed",
"product_id": "a1111c8c-c720-46c3-8534-2fcdd730040d",
"request_id": "2b61e340-27bd-4937-8304-122009e4a393",
"driver": null,
"location": null,
"vehicle": null,
"shared": false
}
While a trip is in progress, it may be necessary to display trip details to the rider, enabling them to understand the current state of their trip or contact their driver.
For example, during the processing state, it is advisable to inform the rider that Paisha is actively seeking a driver. Utilizing a spinner or loading indicator effectively conveys this message.
Once the status changes to accepted, riders can be informed that a vehicle is en route. Additional information such as the pickup location, driver's details, or the driver's location on a map can also be provided.
When the request status transitions to arriving, it is beneficial to notify riders in a manner that captures their attention.
Once the status becomes in_progress, you can offer riders useful information that they may find valuable while they are in the vehicle.
In the event of a driver cancellation, the status changes to driver_canceled. It is crucial to inform riders promptly so that they can request another driver.
Occasionally, riders may need to contact drivers to clarify pickup locations or vehicle details. Providing a convenient way to call or send SMS messages to drivers from within your app is recommended.
The possible status values are:
STATUSES
| Field | Description |
|---|---|
| processing | Paisha is searching or matching the driver |
| no_drivers_available | Driver was not found, request not successful |
| accepted | The driver accepted the request and is enroute to the start location. |
| arriving | The driver arrived or will shortly. |
| in_progress | The trip is in progress from the start location to the end location. |
| driver_canceled | The driver cancelled the request. |
| rider_canceled | The rider cancelled the request. |
| completed | The trip is completed by the driver. |
Request-Response =>
#Example store details request
curl -H 'Authorization: Bearer ' \
-H 'Content-Type: application/json' \
'https://development.paisha.app/api/v1/client/store/details' Response
Status-Code 200 OK
#Response from store details request
{
"id": 197,
"name": "Elite Bookstore",
"phone": "1234567890908765",
"email": "store@gmai.com",
"logo": "2024-08-22-66c7476ece975.png",
"latitude": "-6.778431099999999",
"longitude": "39.2576664",
"address": "Dar es salaam",
"footer_text": null,
"minimum_order": 0,
"comission": null,
"schedule_order": false,
"status": 1,
"vendor_id": 200,
"created_at": "2024-08-22T14:13:03.000000Z",
"updated_at": "2024-08-22T14:13:10.000000Z",
"free_delivery": false,
"cover_photo": "2024-08-22-66c7476f1f08a.png",
"delivery": true,
"take_away": true,
"item_section": true,
"tax": 0,
"zone_id": 3,
"reviews_section": true,
"active": true,
"off_day": " ",
"self_delivery_system": 0,
"pos_system": false,
"minimum_shipping_charge": 0,
"delivery_time": "1-4 hours",
"veg": 1,
"non_veg": 1,
"order_count": 0,
"total_order": 0,
"module_id": 16,
"order_place_to_schedule_interval": 0,
"featured": 1,
"per_km_shipping_charge": 0,
"whatsapp_no": null,
"avg_rating": 0,
"rating_count ": 0,
"category_ids": [],
"gst_status": false,
"gst_code": "",
"discount": null,
"schedules": [
{
"id": 457,
"store_id": 197,
"day": 0,
"opening_time": "00:00:00",
"closing_time": "23:59:59",
"created_at": "2024-08-22T14:13:03.000000Z",
"updated_at": "2024-08-22T14:13:03.000000Z"
},
{
"id": 458,
"store_id": 197,
"day": 1,
"opening_time": "00:00:00",
"closing_time": "23:59:59",
"created_at": "2024-08-22T14:13:03.000000Z",
"updated_at": "2024-08-22T14:13:03.000000Z"
},
{
"id": 459,
"store_id": 197,
"day": 2,
"opening_time": "00:00:00",
"closing_time": "23:59:59",
"created_at": "2024-08-22T14:13:03.000000Z",
"updated_at": "2024-08-22T14:13:03.000000Z"
},
{
"id": 460,
"store_id": 197,
"day": 3,
"opening_time": "00:00:00",
"closing_time": "23:59:59",
"created_at": "2024-08-22T14:13:03.000000Z",
"updated_at": "2024-08-22T14:13:03.000000Z"
},
{
"id": 461,
"store_id": 197,
"day": 4,
"opening_time": "00:00:00",
"closing_time": "23:59:59",
"created_at": "2024-08-22T14:13:03.000000Z",
"updated_at": "2024-08-22T14:13:03.000000Z"
},
{
"id": 462,
"store_id": 197,
"day": 5,
"opening_time": "00:00:00",
"closing_time": "23:59:59",
"created_at": "2024-08-22T14:13:03.000000Z",
"updated_at": "2024-08-22T14:13:03.000000Z"
},
{
"id": 463,
"store_id": 197,
"day": 6,
"opening_time": "00:00:00",
"closing_time": "23:59:59",
"created_at": "2024-08-22T14:13:03.000000Z",
"updated_at": "2024-08-22T14:13:03.000000Z"
}
]
}
GET /api/v1/client/store/details
Store
This Store API provides comprehensive details, allowing you to retrieve essential store information, including the store's name, a detailed description, its physical location, and opening hours. Additionally, it offers a summary of store orders, making it an invaluable resource for managing and accessing key store data efficiently. Whether you're looking to display store details on a website, integrate with an app, or analyze store performance, this API offers the tools you need to seamlessly access and utilize store-related information.
Resource
GET /api/v1/client/store/details
Use Bearer token for Authorization obtained in Authorization step
REQUEST QUERY PARAMETERS
Example store details request
Replace token obtained from authorization process
Request-Response =>
#Example store review request
curl -H 'Authorization: Bearer ' \
-H 'Content-Type: application/json' \
'https://development.paisha.app/api/v1/client/store/reviews' Response
Status-Code 200 OK
#Response from store reviews request
[
{
"id": 3,
"item_id": 1737,
"user_id": 996300,
"comment": "Awesome",
"attachment": [],
"rating": 5,
"order_id": 100225,
"created_at": "2024-08-23T11:40:04.000000Z",
"updated_at": "2024-08-23T11:40:04.000000Z",
"item_campaign_id": null,
"status": 1,
"module_id": 16,
"item_name": "Rich Dad Poor Dad",
"item_image": "2024-08-23-66c860e7e8843.png",
"customer_name": "Kevin Zilic"
},
{
"id": 2,
"item_id": 1737,
"user_id": 996300,
"comment": "Nice book",
"attachment": [],
"rating": 5,
"order_id": 100224,
"created_at": "2024-08-23T10:15:21.000000Z",
"updated_at": "2024-08-23T10:15:21.000000Z",
"item_campaign_id": null,
"status": 1,
"module_id": 16,
"item_name": "Rich Dad Poor Dad",
"item_image": "2024-08-23-66c860e7e8843.png",
"customer_name": "Kevin Zilic"
}
]
GET /api/v1/client/store/details
Store Reviews
The Store API offers comprehensive access to all store views, enabling efficient retrieval of store review data.
Resource
GET /api/v1/client/store/reviews
Use Bearer token for Authorization obtained in Authorization step
REQUEST QUERY PARAMETERS
Example store review request
Replace token obtained from authorization process
Request-Response =>
#Example categories request
curl -H 'Authorization: Bearer ' \
-H 'Content-Type: application/json' \
'https://development.paisha.app/api/v1/client/categories' Response
Status-Code 200 OK
#Response from categories request
[
{
"id": 402,
"name": "Business",
"image": "2024-08-22-66c77012e21a3.png",
"parent_id": 0,
"position": 0,
"status": 1,
"created_at": "2024-08-22T17:06:27.000000Z",
"updated_at": "2024-08-22T17:06:27.000000Z",
"priority": 0,
"module_id": 16
}
]
GET /api/v1/client/categories
Categories
The Category API efficiently retrieves all categories within a specific module, facilitating the organization and insertion of items into the store.
Resource
GET /api/v1/client/categories
Use Bearer token for Authorization obtained in Authorization step
REQUEST QUERY PARAMETERS
Example categories request
Replace token obtained from authorization process
Request-Response =>
#Example sub-categories request
curl -H 'Authorization: Bearer ' \
-H 'Content-Type: application/json' \
'https://development.paisha.app/api/v1/client/
categories/childes/{category_id}' Response
Status-Code 200 OK
#Response from categories request
[
{
"id": 403,
"name": "UK",
"image": "def.png",
"parent_id": 402,
"position": 1,
"status": 1,
"created_at": "2024-08-22T17:14:45.000000Z",
"updated_at": "2024-08-22T17:14:45.000000Z",
"priority": 0,
"module_id": 16
}
]
GET /api/v1/client/categories/childes/{category_id}
Subcategories
The Category API efficiently retrieves all categories within a specific module, facilitating the organization and insertion of items into the store.
Resource
GET /api/v1/client/categories/childes/{category_id}
Use Bearer token for Authorization obtained in Authorization step
REQUEST QUERY PARAMETERS
| Field | Type | Description |
|---|---|---|
| category_id | integer | Category Id |
Example categories request
Replace token obtained from authorization process
Request-Response =>
#Example Units request
curl -H 'Authorization: Bearer ' \
-H 'Content-Type: application/json' \
'https://development.paisha.app/api/v1/client/
categories/units' Response
Status-Code 200 OK
#Response from units request
[
{
"id": 1,
"unit": "Pieces",
"created_at": "2023-05-17T09:57:28.000000Z",
"updated_at": "2023-05-17T09:57:28.000000Z"
},
{
"id": 2,
"unit": "Kg",
"created_at": "2023-06-09T10:09:38.000000Z",
"updated_at": "2023-06-09T10:09:38.000000Z"
},
{
"id": 3,
"unit": "Gram",
"created_at": "2023-06-09T10:10:15.000000Z",
"updated_at": "2023-06-09T10:10:15.000000Z"
}
]
GET /api/v1/client/categories/units
Units
The Units API efficiently retrieves all units within a specific module, facilitating the organization and insertion of items into the store.
Resource
GET /api/v1/client/categories/units
Use Bearer token for Authorization obtained in Authorization process
Example units request
Replace token obtained from authorization process
Request-Response =>
REQUEST QUERY PARAMETERS
#Example Save Item request
curl -H 'Authorization: Bearer ' \
-H 'Content-Type: application/json' \
'https://development.paisha.app/api/v1/client/item/store'
#Example Payload
{
"price": "100000.0",
"discount": "20.0",
"veg": "0",
"discount_type": "percent",
"category_id": "323",
"sub_category_id": null,
"translations": [
{
"id": null,
"locale": "en",
"key": "name",
"value": "Richdad Poor Dad"
},
{
"id": null,
"locale": "en",
"key": "description",
"value": "Business book"
}
],
"current_stock": "100",
"unit": "1",
"image": {},
"item_images": {}
}
Response
Status-Code 200 OK
#Response from units request
{
"message": "Item added successfully"
}
POST /api/v1/client/item/store
Save Items
This API it stores the item to the database.
Resource
POST /api/v1/client/item/store
Use Bearer token for Authorization obtained in Authorization process
Example save item request
Replace token obtained from authorization process
Note: All field with * are mandantory fields
| Field | Type | Description |
|---|---|---|
| price * | double | This is the price of the item |
| discount * | integer | Double | The discount amount depends on the discount type, this is the value for the discount amount |
| veg * | boolean | Use 0 or 1, it is used for restaurants only, 1-means the food is only vergie otherwise it is 0. Put 0 for all stores other than restaurants |
| discount_type * | string | The discount type can be either amount or percent |
| category_id * | integer | The category_id is the id of the category from the categories API. |
| sub_category_id * | integer | The sub_category_id is the id of the subcategory from the subcategories API. |
| translations * | Array | It has the array of JSONS that contains the name and description of the item. "id": null, => This is the id of the item "locale": "en", => represents the languange either en (English) & sw (Swahili) "key": "name", => Defines the key that can be name or description "value": "Richdad Poor Dad" => The value of the key, which is either the item name or description it depends with the key |
| current_stock * | Integer | This is the items current in stock and it is applied to all stores except the restaurants. |
| unit * | Integer | This is the ID of the unit that is obtained from the Unit API |
| image * | string | This is the cover of the item |
| item_images | Array | This is the array of string that contains a series of images, max images are 5 |
Request-Response =>
REQUEST QUERY PARAMETERS
#Example Update Item request
curl -H 'Authorization: Bearer ' \
-H 'Content-Type: application/json' \
'https://development.paisha.app/api/v1/client/item/update'
#Example Payload
{
"id": 4
"price": "100000.0",
"discount": "20.0",
"veg": "0",
"discount_type": "percent",
"category_id": "323",
"sub_category_id": null,
"translations": [
{
"id": null,
"locale": "en",
"key": "name",
"value": "Richdad Poor Dad"
},
{
"id": null,
"locale": "en",
"key": "description",
"value": "Business book"
}
],
"current_stock": "100",
"unit": "1",
"image": {},
"item_images": {}
}
Response
Status-Code 200 OK
#Response from Update Item request
{
"message": "Item updated successfully"
}
PUT /api/v1/client/item/update
Update Item
This API it update the item in the database.
Resource
PUT /api/v1/client/item/update
Use Bearer token for Authorization obtained in Authorization process
Example Update item request
Replace token obtained from authorization process
Note: All field with * are mandantory fields
| Field | Type | Description |
|---|---|---|
| id * | integer | This is the ID of the item |
| price * | double | This is the price of the item |
| discount * | integer | Double | The discount amount depends on the discount type, this is the value for the discount amount |
| veg * | boolean | Use 0 or 1, it is used for restaurants only, 1-means the food is only vergie otherwise it is 0. Put 0 for all stores other than restaurants |
| discount_type * | string | The discount type can be either amount or percent |
| category_id * | integer | The category_id is the id of the category from the categories API. |
| sub_category_id * | integer | The sub_category_id is the id of the subcategory from the subcategories API. |
| translations * | Array | It has the array of JSONS that contains the name and description of the item. "id": null, => This is the id of the item "locale": "en", => represents the languange either en (English) & sw (Swahili) "key": "name", => Defines the key that can be name or description "value": "Richdad Poor Dad" => The value of the key, which is either the item name or description it depends with the key |
| current_stock * | Integer | This is the items current in stock and it is applied to all stores except the restaurants. |
| unit * | Integer | This is the ID of the unit that is obtained from the Unit API |
| image * | string | This is the cover of the item |
| item_images | Array | This is the array of string that contains a series of images, max images are 5 |