Skip to main content

Terminal Card Reader Troubleshooting

Use this playbook when in-person card payments fail or reader status looks wrong.

Quick Triage (60 Seconds)​

  1. Confirm the reader has power and battery.
  2. Confirm internet is available on shop Wi-Fi or reader network.
  3. Confirm the reader appears as ONLINE or READY in Bloomber.
  4. Retry once after cancelling any active reader action.

Reader Offline​

Symptoms​

  • Reader shows OFFLINE in Terminal settings
  • Payment flow cannot start

Checks​

  • Re-seat power cable and charger
  • Reconnect reader to network
  • Move reader closer to router/access point
  • Run reader status sync from Terminal settings

Escalation​

  • If offline for more than 10 minutes, restart reader and retry sync.

Card Declined​

Symptoms​

  • Reader returns a decline message
  • PaymentIntent status is failed/requires action

Checks​

  • Ask client to try insert instead of tap (or another card)
  • Verify amount is correct
  • Retry only once to avoid duplicate attempts

Escalation​

  • Use fallback method (cash/manual flow) and document decline reason.

Stuck Processing​

Symptoms​

  • Reader stays in processing state
  • Checkout does not complete

Checks​

  • Use Cancel payment in Terminal controls
  • Retry payment on same reader once
  • If still stuck, switch to another registered reader

Escalation​

  • Ask owner/admin to run terminal reconciliation.

Wrong Reader Selected​

Symptoms​

  • Charge appears on the wrong station

Checks​

  • Verify reader labels (example: Front Desk, Station 3)
  • Reassign reader to correct barber or keep as shared intentionally

Escalation​

  • Update labels and assignments in Settings -> Terminal -> Readers.

Reconciliation Mismatch​

Symptoms​

  • Stripe dashboard and Bloomber appointment state do not match

Checks​

  • Poll payment status endpoint from the appointment
  • Run terminal reconciliation endpoint/tool
  • Verify webhook processing is healthy

Escalation​

  • If mismatch persists, open support incident with:
    • tenant slug
    • payment intent id
    • reader label/id
    • timestamp of attempted charge

Prevention Checklist​

  • Keep readers charged before peak hours
  • Use clear reader labels by station
  • Run periodic status sync
  • Train barbers to cancel stale actions before retrying