# 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.

---
Source: https://docs.cabfare.com/api/payment-terminal-persona