Payment Terminal Persona

View as Markdown

Overview

This guide is for Payment Terminal and mobile payment application developers integrating with CabFare Connect. As a Payment Terminal partner you are the transaction interface — you initiate the device link, read physical Subsidy Cards (if applicable), and process card payments for the balance amount instructed by the Taxi Meter.

Read this guide alongside the Workflows section and the API Reference before beginning your implementation.

Your Integration at a Glance

You must:

• Call the CabFare Connect API endpoints listed below to send events to CabFare Connect
• Implement and host the Payment Terminal API endpoints to receive inbound events from CabFare Connect

Endpoints You Call — CabFare Connect API

Endpoint	When to Call
POST /terminal/driver/login	When the driver logs in on the Payment Terminal
POST /terminal/driver/poll	To check current driver and link status after connectivity loss
POST /terminal/driver/validate	When the driver presents their card on the Payment Terminal for validation (if applicable)
POST /terminal/link/request	When the driver initiates device linking on the Payment Terminal
POST /terminal/mptp/validate	When the Payment Terminal successfully reads a passenger Subsidy Card (if applicable)
POST /terminal/payment/complete	When a card payment is approved or declined on the Payment Terminal
POST /terminal/driver/logout	When the driver logs out of the Payment Terminal

Endpoints You Host — Payment Terminal API

Endpoint	Purpose
POST /link/response	Receive link request outcome from CabFare Connect
POST /mptp/read	Receive Subsidy Card read request from CabFare Connect (if applicable)
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

Implementation Checklist

Shift Management

• [ ] Implement POST /terminal/driver/login — submit terminalId, driverId and handle the returned Subsidy Scheme eligibility status
• [ ] Display driver Subsidy Scheme eligibility status on screen after login (if applicable)
• [ ] Disable Subsidy Scheme functions if driver eligibility status is invalid (if applicable)
• [ ] Implement POST /terminal/driver/logout — notify CabFare Connect when the driver logs out of the Payment Terminal
• [ ] Implement POST /terminal/driver/poll — use after connectivity loss to recover session state

Linking

• [ ] Implement POST /terminal/link/request — initiate device link after driver login, submitting terminalId and driverId
• [ ] Host POST /link/response — receive link outcome from CabFare Connect
• [ ] Enter linked mode on receipt of a successful link response
• [ ] Display error and continue in unlinked mode on receipt of a failed link response
• [ ] Host POST /driver/logout — receive driver logout notification from CabFare Connect, unlink from Taxi Meter, and log driver out if configured

Subsidy Card Handling (if applicable)

• [ ] Host POST /mptp/read — receive Subsidy Card read request from CabFare Connect and prompt driver to present passenger Subsidy Card
• [ ] Implement POST /terminal/mptp/validate — submit card details to CabFare Connect after a successful card read
• [ ] Display a clear message directing the driver to perform manual entry on the Taxi Meter if the card cannot be read
• [ ] Implement POST /terminal/driver/validate — submit driver card details to CabFare Connect when the driver presents their card for validation

Payment Processing

• [ ] Host POST /payment/request — receive card payment request from CabFare Connect and prompt driver to present passenger card
• [ ] Process the payment as a blind amount in cents — the Payment Terminal does not need to know the fare breakdown
• [ ] Implement POST /terminal/payment/complete — call for every payment attempt regardless of whether it was approved or declined
• [ ] Host POST /payment/cancel — receive and action payment cancellation requests from CabFare Connect
• [ ] Handle 410 Gone response to /payment/cancel — the transaction has already been completed and cannot be cancelled

Receipt

• [ ] Host POST /print/receipt — receive receipt print request from CabFare Connect and print receipt including subsidy and payment details if the system is configured with a Payment Terminal printer

Key Technical Reminders

• All monetary amounts are in cents as integers — never dollars as floats
• POST /terminal/payment/complete must be called for every payment attempt — approved or declined
• The terminalId, driverId, and vehiclePlate must be consistent across all API calls within a session
• Return an immediate 200 OK or 204 No Content when receiving inbound events from CabFare Connect before processing the event
• Use POST /terminal/driver/poll after connectivity loss to verify session state before resuming normal operation
• If linking is not successful continue in unlinked mode — standard operation is not blocked

Support

Contact support@cabfare.com for integration assistance. Refer to the Error Handling and Troubleshooting section for common issues and diagnostic guidance.