Arsalan YasinPayment processing is the lifeblood of any retail operation. If you’re using Odoo POS, you already know how smooth and flexible it can be—but without integration to modern EFTPOS terminals like Linkly, you’re leaving time and efficiency on the table. In this developer’s guide, we’ll walk through every step needed to integrate Linkly/EFTPOS terminals with Odoo POS, transforming your point-of-sale from good to great.
Introduction
Why integrate EFTPOS with Odoo POS?
Ever tried juggling cash, cards, and vouchers separately? It’s like trying to herd cats. Integrating an EFTPOS terminal streamlines payment handling, reduces human error, and enhances customer trust. Plus, it frees up your staff to focus on selling, not reconciling.
Who is this guide for?
This guide is tailored for Odoo developers, IT managers, and technical consultants who want a hands‑on tutorial. You should be comfortable with Python, Odoo module development, and basic networking concepts.
Understanding the Basics
What is Odoo POS?
Odoo POS is the point‑of‑sale application built into Odoo’s ERP suite. It supports retail, restaurant, and service‑based operations. Its modular design allows custom payment methods, making it the perfect candidate for EFTPOS integration.
What are Linkly/EFTPOS terminals?
Linkly terminals are secure card payment devices supporting chip, PIN, and contactless payments. They communicate via serial or network interfaces and use JSON or proprietary protocols.
Key features of Linkly devices
- Multi-payment support: Chip, PIN, NFC
- Multiple communication options: Ethernet, USB, Bluetooth
- SDKs and documentation: Ready‑to‑use APIs
EFTPOS payment flows
- Payment initiation in the POS.
- Transaction request sent to terminal.
- Terminal processing, customer interaction (PIN/NFC).
- Approval or decline returned.
- POS finalizes the order.
Prerequisites and Setup
Development environment requirements
- Odoo 16 or higher (ensure compatibility).
- Python 3.9+ installed.
- PostgreSQL database running.
- Access to Linkly SDK or protocol documentation from your provider.
Odoo version compatibility
While Odoo 14–18 may work, this guide focuses on Odoo 16+ due to its improved POS architecture and async support.
Hardware requirements for terminals
- A Linkly EFTPOS terminal (e.g., WisePad 3).
- USB/Ethernet adapter or Bluetooth dongle depending on connectivity.
Overview of the Integration Workflow
Transaction initiation in Odoo POS
When a cashier clicks Pay, Odoo triggers a payment creation flow. We’ll hook into this event to redirect it to our terminal connector.
Communication with the terminal
Our custom module will open a socket or serial connection, format a JSON request, and send it to the device.
Handling terminal responses
Once the terminal finishes processing, it sends back approval or error codes. We parse these and update Odoo’s payment records.
Configuring Odoo POS
Installing the POS module
- Activate developer mode.
- Go to Apps → Update Apps List.
- Search for Point of Sale and install.
Enabling payment method settings
Navigate to Point of Sale → Configuration → Payment Methods. Add a new payment method called Linkly or EFTPOS.
Defining a new payment acquirer
Under Invoicing → Payment Acquirers, create a new acquirer pointing to your terminal connector’s API endpoint. Set credentials and callback URLs.
Building the Linkly/EFTPOS Connector Module
Module skeleton and manifest
Create a new module folder pos_linkly_connector with a __manifest__.py:
python
{
‘name’: ‘POS Linkly Connector’,
‘version’: ‘1.0’,
‘depends’: [‘point_of_sale’],
‘data’: [‘views/pos_config.xml’],
‘qweb’: [‘static/src/xml/terminal.xml’],
‘installable’: True,
}
Defining models and settings
In models/pos_config.py, extend pos.config to include terminal IP, port, and protocol settings.
Creating communication services
In services/terminal_service.py, implement a Python class to manage socket/serial connections and JSON message exchange.
Establishing Communication Protocols
Serial vs. network protocols
- Serial (USB/RS232): Direct cable, low latency.
- Network (Ethernet/TCP): Flexible, multiple devices.
JSON/RPC message structures
Use JSON for clarity:
Sample request payload
json
{
“transaction”: {
“amount”: 123.45,
“currency”: “AUD”,
“order_id”: “POS/ORD/0001”
}
}
Sample response handling
json
{
“status”: “approved”,
“auth_code”: “A1B2C3”,
“message”: “Transaction approved”
}
Implementing Payment Flow
Initiating a payment request
In static/src/js/pos_terminal.js, override the PaymentScreen:
javascript
this.rpc({
model: ‘pos.payment’,
method: ‘send_to_terminal’,
args: [paymentInfo],
})
Waiting for terminal approval
Display a loading spinner and listen for a WebSocket or long-polling response.
Finalizing the transaction in Odoo
On approval, call pos_model.finalize_payment(); on decline, show an error popup.
Error Handling and Logging
Common terminal errors
- Timeouts
- Connection refused
- Invalid response format
Retry mechanisms
Implement exponential backoff for retrying failed sends.
Logging best practices
Use Odoo’s logging module to record debug/info/error logs, making sure sensitive data is masked.
Testing the Integration
Simulating transactions
Use a mock server that replicates terminal responses. Helps you test without hardware.
Unit and integration tests
Write tests in tests/test_terminal.py using unittest or pytest, verifying each state transition.
Using mock terminals
Some providers offer software simulators. Leverage these to ensure real-world parity.
Deployment Considerations
Packaging the module
Zip your module and place it in the addons directory or publish to a private Odoo App Store.
Upgrading production servers
- Backup database.
- Install module in Maintenance Mode.
- Test in staging before live rollout.
Rolling back on failures
Keep previous module versions handy and use Odoo’s -u all option cautiously.
Security and Compliance
PCI DSS considerations
Never store raw card data. Use tokenization or let the terminal handle sensitive data entirely.
Secure storage of credentials
Store terminal credentials in Odoo’s ir.config_parameter with sudo() access control.
Data encryption
Use TLS for network communication and ensure end‑to‑end encryption where possible.
Performance Optimization
Reducing latency
Batch communication calls and avoid blocking the main UI thread.
Asynchronous processing
Leverage Odoo’s @job decorator or external message queues (e.g., RabbitMQ) to process transactions.
Resource monitoring
Track CPU/memory usage of your connector service to avoid bottlenecks during peak hours.
Real-World Tips and Tricks
Handling network instability
Implement fallback to USB if Ethernet fails. Inform users gracefully.
Terminal firmware updates
Schedule updates during off‑peak hours and notify staff in advance.
Customer experience improvements
Customize on‑screen prompts, add branding, and pre‑fill order details to speed checkout.
Conclusion
Integrating Linkly/EFTPOS terminals with Odoo POS is like adding a turbocharger to your payment process: faster, more reliable, and ready for any scale. By following this guide—from environment setup and module creation to testing and deployment—you’ll ensure a smooth, secure, and high-performing payment integration. Now go ahead, give your customers the seamless checkout experience they deserve!
Follow me on LinkedIn for more latest updates
Frequently Asked Questions
Integration works best on Odoo 16+ due to async handling but can be back‑ported to versions 14 and 15 with minor tweaks.
Yes. Configure each terminal as a separate POS configurationand assign unique ports or IPs.
Use your terminal provider’s OTA (Over‑The‑Air) update service or Linkly’s management portal during non‑business hours.
Most EFTPOS providers offer a software simulator. Check Linkly’s developer portal for details.
Implement retry logic or fall back to manual card entry modes. Always log transactions for reconciliation.