Payment Terminal Persona

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 mailto\ support\@cabfare com for integration assistance refer to the error handling and troubleshooting section for common issues and diagnostic guidance