# Payment Terminal API

> **Full endpoint reference:** See every endpoint, with code samples and **Test Request**, in the [Payment Terminal API reference](https://docs.cabfare.com/api/reference/payment-terminal).

## Overview

The Payment Terminal API defines the endpoints that the Payment Terminal partner must implement and host. CabFare Connect calls these endpoints to deliver real-time inbound event notifications to the Payment Terminal 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/response`   | Receive link request outcome from CabFare Connect              |
| POST   | `/mptp/read`       | Receive Subsidy Card read request from CabFare Connect         |
| POST   | `/payment/request` | Receive card payment request from CabFare Connect              |
| POST   | `/payment/cancel`  | Receive card payment cancellation request from CabFare Connect |
| POST   | `/print/receipt`   | Receive receipt print request from CabFare Connect             |
| POST   | `/driver/logout`   | Receive driver logout notification from CabFare Connect        |

## Endpoint Details

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

CabFare Connect calls this endpoint to deliver the outcome of a link request to the Payment Terminal following the Taxi Meter's response.

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

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

**Responses:**

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

The Payment Terminal must use the `status` field to determine whether to enter linked mode or display an error and continue in unlinked mode.

### POST `/mptp/read` — Subsidy Card read request

CabFare Connect calls this endpoint to instruct the Payment Terminal to prompt the driver to present the passenger's Subsidy Card.

**Required fields:** `terminalId`, `driverId`

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

**Responses:**

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

Upon receipt the Payment Terminal prompts the driver to present the passenger Subsidy Card. The card read result is then submitted to CabFare Connect via `POST /terminal/mptp/validate` on the CabFare Connect API.

### POST `/payment/request` — Card payment request

CabFare Connect calls this endpoint to instruct the Payment Terminal to collect a card payment for the specified amount.

**Required fields:** `terminalId`, `driverId`, `tripId`, `paymentAmount`

**Optional fields:** `vehiclePlate`, `clientIds`, `transactionId`, `paymentDetails`, `additionalData`, `isSubsidy`

**Responses:**

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

The `paymentAmount` is expressed in cents as an integer. The Payment Terminal processes this as a blind amount — it does not need to know the fare breakdown. The payment outcome is reported back to CabFare Connect via `POST /terminal/payment/complete` on the CabFare Connect API.

### POST `/payment/cancel `— Card payment cancellation request

CabFare Connect calls this endpoint to cancel a pending card payment request on the Payment Terminal.

**Required fields:** `terminalId`, `driverId`, `transactionId`

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

**Responses:**

| Code               | Meaning                                                        |
| ------------------ | -------------------------------------------------------------- |
| `204 No Content`   | Cancellation received successfully                             |
| `400 Bad Request`  | Malformed request                                              |
| `401 Unauthorized` | Invalid credentials                                            |
| `404 Not Found`    | Payment Terminal or driver not found in current context        |
| `410 Gone`         | Transaction has already been completed and cannot be cancelled |

### POST `/print/receipt` — Print receipt request

CabFare Connect calls this endpoint to instruct the Payment Terminal to print a receipt including trip, subsidy, and payment details.

**Required fields:** `terminalId`, `driverId`, `receiptDetails`

**Optional fields:** `vehiclePlate`, `clientIds`, `transactionId`, `additionalData`, `paidAt`

**Responses:**

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

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

CabFare Connect calls this endpoint to notify the Payment Terminal that the driver has logged out of the linked Taxi Meter. The Payment Terminal must unlink from the Taxi Meter and log the driver out if configured to do so.

**Required fields:** `terminalId`, `driverId`

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

**Responses:**

| Code               | Meaning                                                 |
| ------------------ | ------------------------------------------------------- |
| `204 No Content`   | Notification received successfully                      |
| `400 Bad Request`  | Malformed request                                       |
| `401 Unauthorized` | Invalid credentials                                     |
| `404 Not Found`    | Payment Terminal 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/payment-terminal-api