Appearance

Troubleshooting ​

View as Markdown

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