# Troubleshooting

## Overview

This guide provides step-by-step diagnostic procedures for identifying and resolving integration issues. Follow the standard diagnostic flow first, then refer to the specific playbooks for common failure scenarios.

***

## Standard Diagnostic Flow

When any workflow fails — linking, Subsidy Card validation, trip, or payment — use this flow before escalating to CabFare support.

### Step 1 — Identify the failing step

Determine exactly which step in the workflow is failing:

- Driver login
- Device link request
- Trip start
- Subsidy Card validation
- Trip end and subsidy processing
- Balance payment
- Job done and shift end

### Step 2 — Check the last request and response

Log and inspect the full HTTP request and response for the failing call:

- URL and method
- Headers — are `X-API-KEY` and `X-API-SECRET` present and correct?
- Request body — is it valid JSON with all required fields?
- HTTP status code
- Response body — inspect the `detail` array for field-level errors

Never log your full `X-API-SECRET` value. Redact secrets in all logs and support tickets.

### Step 3 — Cross-check identifiers

For the failing request verify:

- `driverId` matches the value used during login on both devices
- `vehiclePlate` is present and consistent across both devices
- `taxiMeterId` or `terminalId` is stable and consistent for the hardware
- `tripId` is the correct value for the current hire
- `transactionId` is unique and correct for the payment attempt

Inconsistent identifiers are the most common cause of `404 Not Found` and linking failures.

### Step 4 — Reproduce with a minimal payload

Use curl or Postman with known-good test data from the sandbox to reproduce the issue. Compare the failing request against the working test to identify the discrepancy.

```bash
curl -i -X POST https://dcp-sandbox.nbggroup.com.au/api/v0.5.0/meter/driver/login \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your-sandbox-key" \
  -H "X-API-SECRET: your-sandbox-secret" \
  -d '{
    "taxiMeterId": "TM100",
    "driverId": "999998",
    "vehiclePlate": "M1000"
  }'
```

### Step 5 — Check connectivity

If all requests are failing verify basic connectivity to the API:

```bash
curl -i https://dcp-sandbox.nbggroup.com.au/api/v0.5.0/ping
```

Expect `200 OK` with body `{"response": "Pong"}`. If this fails check your network, firewall, and TLS configuration.

***

## What to Capture in Your Logs

For reliable self-diagnosis and efficient support escalation, log the following for every API call:

- Timestamp in UTC
- Endpoint and HTTP method
- HTTP status code returned
- `taxiMeterId` or `terminalId`
- `driverId`
- `vehiclePlate`
- `tripId` where applicable
- `transactionId` where applicable
- Any `status`, `error`, and `detail` fields from error responses
- For trip end and payment calls, the monetary values submitted and the values returned

Never log full card numbers or PCI-sensitive data. For Subsidy Card numbers log only the last 4 digits where necessary.

***

## Troubleshooting Playbooks

### Playbook 1 — Driver Cannot Start a Subsidy Scheme Trip

1. Confirm driver is logged in on the Taxi Meter — `POST /meter/driver/login` returned `200 OK`
2. Confirm driver is logged in on the Payment Terminal — `POST /terminal/driver/login` returned `200 OK`
3. Check `mptpDriverData.mptpStatus` in both login responses — if `MPTP_DRIVER_INVALID` on either device, Subsidy Scheme mode must be disabled
4. Confirm the Payment Terminal sent `POST /terminal/link/request` and received a success response via `POST /link/response`
5. Poll `POST /meter/driver/poll` until `loginStatus: true` and `linkStatus: true`
6. If link never becomes true, verify your `POST /link/response` event handler is implemented and reachable
7. Once linked, confirm the Taxi Meter calls `POST /meter/trip/start` and handles both `204` (Subsidy Scheme valid) and `202` (Subsidy Scheme invalid) responses correctly

***

### Playbook 2 — Manual Subsidy Card Entry Keeps Failing

1. Verify the driver UI only accepts 9 digits and instructs the driver to omit the card number prefix
2. Call `POST /meter/mptp/validate` with the 9-digit number in the `mptpNumbers` array
3. For each item in the response array check `mptpStatus` — if invalid or expired display a clear error to the driver
4. If the API returns `403 Forbidden`, the driver or vehicle is not authorised for Subsidy Scheme trips — contact CabFare support

***

### Playbook 3 — Payment Not Settling Correctly

1. Confirm `POST /terminal/payment/complete` is being called for every payment attempt — approved and declined
2. Verify all required fields are present: `terminalId`, `driverId`, `transactionId`, `paymentStatus`
3. Confirm `paymentStatus` correctly reflects the outcome — an incorrect status may cause the backend to treat the transaction as unpaid
4. Match `transactionId` to the corresponding `tripId` in your internal logs to trace the full payment flow
5. If the payment was approved on the terminal but not reflected in CabFare Connect, the driver can manually mark the payment as successful on the Taxi Meter and continue

***

## Contacting CabFare Support

When escalating to CabFare support include the following information to ensure fast resolution:

**Environment details:**

- Sandbox or production
- API version (e.g. `v0.5.0`)

**Affected components:**

- Taxi Meter provider name and software version
- Payment Terminal provider name and version

**Problem description:**

- What the driver or operator attempted and what happened
- Whether the issue is reproducible or intermittent
- Approximate time and date of occurrence in UTC

**Technical artefacts:**

- HTTP logs of the failing requests and responses — status code, response body, and relevant headers
- `taxiMeterId` or `terminalId`, `driverId`, `vehiclePlate`, `tripId`, `transactionId`
- Any UI screenshots or error messages shown to the driver

Contact: [support@cabfare.com](mailto:support@cabfare.com)

---
Source: https://docs.cabfare.com/api/troubleshooting