API Conventions

View as Markdown

Base URLs

Base URLs are provided per environment and per location. Refer to the relevant location section for the specific base URL applicable to your integration.

Versioning

The CabFare Connect API is versioned. The current version is v0.5.0. The API version is included in the base URL path. When a new version is released, the previous version will remain available for a transition period. CabFare will notify integration partners of version changes with sufficient lead time to update their implementations.

Request Format

All requests must:

• Use HTTPS
• Include the Content-Type: application/json header
• Include the X-API-KEY and X-API-SECRET authentication headers
• Send request bodies as valid JSON

Response Codes

CabFare Connect uses standard HTTP status codes to indicate the outcome of every request.

Code	Meaning	Common Cause
200 OK	Request successful, response body contains data	Ping, subsidy validation, trip end with subsidy
202 Accepted	Request accepted with a notable condition	Trip start where driver Subsidy Scheme status is not valid
204 No Content	Request accepted, no response body	Driver logout, link request accepted, trip end without subsidy
400 Bad Request	Malformed or invalid request payload	Missing required fields, incorrect data types, invalid enum values
401 Unauthorized	Missing or invalid credentials	Missing or incorrect X-API-KEY or X-API-SECRET
403 Forbidden	Authenticated but operation not permitted	Driver or vehicle not authorised for Subsidy Scheme trips
404 Not Found	Referenced resource not found	Unknown device ID, driver not currently logged in
409 Conflict	Active session already exists	Duplicate tripId, existing active trip for vehicle
500 Server Error	Internal CabFare Connect error	Contact support@cabfare.com

Error Response Format

For 4xx responses, CabFare Connect returns a structured error body to help identify the cause.

{
  "status": 400,
  "error": "Bad Request",
  "detail": [
    {
      "field": "driverId",
      "message": "must not be blank"
    }
  ]
}

Inspect the detail array for specific field-level errors when troubleshooting a 400 response.

Currency Format

All monetary amounts in CabFare Connect are expressed in cents as integers, not dollars as floats.

A fare of $10.00 must be submitted as 1000

This applies to all fare amounts, subsidy amounts, lifting fees, and payment amounts across all endpoints.

Identifiers

The following identifiers must be consistent across all API calls within a session:

Identifier	Description
taxiMeterId	Unique identifier for the Taxi Meter device or system
terminalId	Unique identifier for the Payment Terminal device or application
driverId	Unique identifier for the accredited driver
vehiclePlate	Registered vehicle plate number
tripId	Unique identifier for a single trip — must be unique per trip
transactionId	Unique identifier for a single payment transaction

Inconsistent identifiers across the Taxi Meter and Payment Terminal are the most common cause of linking failures and session errors.