Payment Terminal API

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