# Taxi Meter API

> **Full endpoint reference:** See every endpoint, with code samples and **Test Request**, in the [Taxi Meter API reference](https://docs.cabfare.com/api/reference/taxi-meter).

## Overview

The Taxi Meter API defines the endpoints that the Taxi Meter partner must implement and host. CabFare Connect calls these endpoints to deliver real-time inbound event notifications to the Taxi Meter system.

This API is the inbound communication path — CabFare Connect calls your system.

## Implementation Requirements

Your system must expose these endpoints to receive events from CabFare Connect. When your system receives an inbound request from CabFare Connect it must:

- Return an immediate `200 OK` or `204 No Content` response before processing the event
- Validate that the `X-API-KEY` header in the inbound request matches your issued key
- Handle the event and update your UI or internal state accordingly

Where possible response codes should be implemented as documented. Error response bodies are optional but recommended during development as they assist with troubleshooting.

## Endpoints

| Method | Endpoint            | Summary                                                                     |
| ------ | ------------------- | --------------------------------------------------------------------------- |
| POST   | `/link/request`     | Receive a link mode request from CabFare Connect                            |
| POST   | `/mptp/member`      | Receive Subsidy Card read notification and member data from CabFare Connect |
| POST   | `/payment/complete` | Receive payment outcome notification from CabFare Connect                   |
| POST   | `/driver/logout`    | Receive driver logout notification from CabFare Connect                     |

## Endpoint Details

### POST `/link/request` — Link mode request

CabFare Connect calls this endpoint to forward a link mode request to the Taxi Meter after receiving a link request from the Payment Terminal.

**Required fields:** `taxiMeterId`, `driverId`

**Optional fields:** `vehiclePlate`, `paymentTerminalConfiguration`, `clientIds`

**Responses:**

| Code               | Meaning                                             |
| ------------------ | --------------------------------------------------- |
| `200 OK`           | Link request accepted — return link success details |
| `400 Bad Request`  | Malformed request                                   |
| `401 Unauthorized` | Invalid credentials                                 |
| `404 Not Found`    | Taxi Meter or driver not found in current context   |

The Taxi Meter must return a success or error response. CabFare Connect uses this response to determine what to send back to the Payment Terminal via `/link/response`.

***

### POST `/mptp/member` — Subsidy Card read notification

CabFare Connect calls this endpoint to deliver Subsidy Card validation results to the Taxi Meter following a card read or validation request.

**Required fields:** `taxiMeterId`, `driverId`, `mptpMemberData`

**Optional fields:** `clientIds`, `terminalFailure`

**Responses:**

| Code               | Meaning                                           |
| ------------------ | ------------------------------------------------- |
| `204 No Content`   | Notification received successfully                |
| `400 Bad Request`  | Malformed request                                 |
| `401 Unauthorized` | Invalid credentials                               |
| `404 Not Found`    | Taxi Meter or driver not found in current context |

The `terminalFailure` field indicates whether the notification is being sent because the Payment Terminal failed to read the card.

***

### POST `/payment/complete` — Payment complete notification

CabFare Connect calls this endpoint to notify the Taxi Meter of the outcome of a card payment processed on the Payment Terminal.

**Required fields:** `taxiMeterId`, `driverId`, `tripId`, `transactionId`, `paymentStatus`, `paymentDetails`

**Optional fields:** `clientIds`

**Responses:**

| Code               | Meaning                                           |
| ------------------ | ------------------------------------------------- |
| `204 No Content`   | Notification received successfully                |
| `400 Bad Request`  | Malformed request                                 |
| `401 Unauthorized` | Invalid credentials                               |
| `404 Not Found`    | Taxi Meter or driver not found in current context |

***

### POST `/driver/logout` — Driver logout notification

CabFare Connect calls this endpoint to notify the Taxi Meter that the driver has logged out of the linked Payment Terminal. The Taxi Meter must determine whether to also log the driver out or continue in unlinked mode.

**Required fields:** `taxiMeterId`, `driverId`, `status`

**Optional fields:** `clientIds`

**Responses:**

| Code               | Meaning                                           |
| ------------------ | ------------------------------------------------- |
| `204 No Content`   | Notification received successfully                |
| `400 Bad Request`  | Malformed request                                 |
| `401 Unauthorized` | Invalid credentials                               |
| `404 Not Found`    | Taxi Meter or driver not found in current context |

## Important Notes

- Full endpoint schemas, request and response bodies, and error details are available in the interactive API reference imported from the OpenAPI specification
- The base URL for these endpoints is your own hosted URL — CabFare Connect will be provided your base URL during the integration onboarding process

---
Source: https://docs.cabfare.com/api/taxi-meter-api