Fix Odoo POS Payment Terminal Errors: Connection & Transaction Issues

POS Payment Terminal Issues

Odoo POS integrates with payment terminals (Adyen, Ingenico, Worldline, Stripe) via direct connection or IoT Box. Terminal communication failures disrupt checkout and frustrate customers. Here are the common issues and fixes.

Terminal Not Connecting

# Error: "Could not connect to the payment terminal"

# Fix 1: Check network connection
# Terminal and POS must be on same network
# Verify terminal IP is reachable:
ping 192.168.1.100  # Terminal IP

# Fix 2: Verify terminal configuration
# POS → Configuration → Payment Methods
# Check: Payment Terminal IP/Port is correct
# Check: Protocol matches (Adyen/Ingenico/Worldline)

# Fix 3: IoT Box connection
# If using IoT Box:
# - IoT Box must be online (green LED)
# - Check IoT Box dashboard: http://iotbox-ip:8069
# - Terminal must appear in connected devices
# - Restart IoT Box if terminal not detected

# Fix 4: Firewall blocking
# Ensure port is open between POS and terminal
# Common ports: 8443 (Adyen), 3000 (Ingenico)

Transaction Timeout

# Error: "Payment terminal timed out"

# Cause 1: Customer didn't interact with terminal
# Timeout default: 60 seconds
# Fix: Increase timeout in payment method config
# Or prompt customer to complete payment

# Cause 2: Slow network
# Terminal → payment processor round-trip too slow
# Fix: Check internet connection on terminal
# Wired connection preferred over WiFi

# Cause 3: Terminal firmware outdated
# Fix: Update terminal firmware from provider portal
# Adyen: Adyen Customer Area → Terminals
# Ingenico: MyPortal → Terminal Management

# Cause 4: SSL certificate expired on terminal
# Fix: Trigger certificate renewal from provider
# Or factory reset terminal and reconfigure

Refund Failures

# Error: "Refund failed" or "Referenced transaction not found"

# Cause 1: Original transaction too old
# Some processors limit refund window (90-180 days)
# Fix: Process manual refund via provider portal

# Cause 2: Transaction ID mismatch
# Odoo stores transaction reference for refunds
# If reference lost, manual refund needed

# Cause 3: Terminal doesn't support referenced refunds
# Some terminals require unreferenced refunds
# Fix: Configure payment method for unreferenced refunds
# POS → Payment Methods → Allow unreferenced refunds

# Cause 4: Insufficient merchant balance
# Processor won't process refund if balance < refund amount
# Fix: Ensure settlement has occurred first

Stripe Terminal Issues

# Stripe Terminal (BBPOS, Verifone) specific:

# Fix 1: Reader not discovered
# Stripe readers connect via internet, not local network
# Verify: reader registered in Stripe Dashboard
# Location must match POS configuration

# Fix 2: Reader offline
# Stripe readers need constant internet
# Check WiFi or Ethernet connection
# Dashboard: Stripe → Terminal → Readers → Status

# Fix 3: Incorrect location
# Each reader assigned to a Stripe Location
# Must match Odoo POS payment method location config
# Stripe Dashboard → Terminal → Locations

# Fix 4: API key mismatch
# Live vs Test mode keys
# Production POS must use live Stripe keys

IoT Box Troubleshooting

# IoT Box issues with terminals:

# 1. Cannot find IoT Box
# URL: http://iotbox.local:8069 or http://[IP]:8069
# If not found: connect monitor to IoT Box, get IP

# 2. IoT Box not detecting terminal
# - USB terminals: unplug and replug
# - Network terminals: add IP in IoT Box form
# - Restart IoT Box: unplug power, wait 10s, replug

# 3. Driver missing
# IoT Box auto-downloads drivers on boot
# Requires internet access for driver updates
# Manual driver upload via IoT Box dashboard

# 4. Multiple POS using same terminal
# Only one POS session can use a terminal at a time
# Second session gets "terminal busy" error

Recovery Steps

# When payment is stuck:
# 1. Check terminal screen for pending transaction
# 2. Cancel on terminal if possible
# 3. In Odoo POS: retry or use alternative payment
# 4. Never close POS session with pending payments
# 5. Reconcile manually if needed:
#    POS → Orders → [order] → Payment lines

# Force close stuck payment:
# POS → Debug → Force payment validation
# Only use when terminal confirmed payment
# but Odoo didn't receive confirmation

DeployMonkey

DeployMonkey's AI agent can help configure and troubleshoot POS payment terminal integrations in your Odoo instance.