Appearance
Payment Terminal API
Full endpoint reference
See every endpoint, with code samples and Test Request, in the Payment Terminal API reference.
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 OKor204 No Contentresponse before processing the event - Validate that the
X-API-KEYheader 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