POS ZVT Terminal - ZVT Payment Terminal Integration | Kartenterminal, girocard, Germany, Austria
by Modvanta$ 65.00
In-App Purchases
POS ZVT Terminal for Odoo 19
Take card payments in the Odoo Point of Sale on a German or Austrian card terminal (Kartenterminal) over the ZVT ECR interface (Kassenschnittstelle): payment, refund, reversal, end-of-day and cancel from the POS, the terminal messages on the payment screen and the terminal receipt on the POS receipt.
Written and supported by Modvanta - modvantaapps@gmail.com
What it does
ZVT is the cash register interface of most card terminals in Germany and Austria. The module adds "ZVT Terminal" as a payment terminal of the Odoo Point of Sale. When the cashier picks the card payment method, Odoo sends the amount to the terminal with the ZVT Authorization command, shows the terminal messages ("Insert card", "Please wait...") under the payment line, stores the result with the card name, the last four card digits, the trace and receipt numbers and the authorisation, and prints the customer copy of the terminal receipt on the POS receipt.
Who it is for: shops, bakeries, restaurants and kiosks in Germany and Austria whose card terminal offers the ZVT interface (ask the terminal supplier to enable the ECR / Kassen interface and give you its IP address, port and password), and Odoo partners who set up the Point of Sale for them.
Why merchants pick it
Nobody pays twice If the connection breaks after the card was used, Odoo does not guess: it asks the terminal for its last stored transaction (Repeat Receipt) and decides from the trace number and the amount. No new card payment starts on that terminal until the result is known. | A paid sale is never lost The terminal result is stored in Odoo before Odoo acknowledges it to the terminal. If Odoo cannot store it, no acknowledgement is sent and the terminal reverses the payment itself, as the ZVT protocol requires. | Cashier sees the terminal The intermediate status messages of the terminal are shown under the payment line, in English or German, and a decline shows the reason the terminal gave. |
Payment, refund, reversal A positive amount is a payment (06 01), a refund order a refund (06 31), and the Reverse button of the payment line sends a reversal / Storno (06 30) of the same-day payment. | End-of-Day Kassenschnitt from the terminal form or automatically when the POS session closes, with the totals per card brand and the end-of-day receipt kept in Odoo. | Hosted Odoo too The Odoo server can open the TCP connection itself, or a small relay program in the shop does it and calls Odoo over HTTPS, so Odoo.sh and other hosted Odoo work. |
Key features
Address and port (default 20007), the 6 digit terminal password as a protected field, receipts by Odoo or by the terminal, Print Line or Print Text-Block, receipt line width, UTF-8 request, the T3 and T4 time-outs and the receipt number synchronisation (TLV 1F1F). Register, Terminal Status, End-of-Day and Reprint Last Receipt are buttons on the form; the terminal ID comes from the registration.

Pick "ZVT Terminal" under Use a Payment Terminal and choose the terminal.

While the customer pays, the payment line shows what the terminal says. Cancel sends the ZVT Abort (06 B0); the terminal stops if the card has not been used yet.

With "Odoo receives the receipt lines" the terminal sends its receipt over ZVT; the customer copy is printed with the POS receipt, the merchant copy is kept on the transaction.

The result code of the terminal is shown to the cashier and the line can be sent again.

Approved, declined, cancelled, error and unknown attempts with the cashier, the order, the card, trace and receipt numbers. Point of Sale managers see all of them, cashiers only their own, and nobody can edit them.

Each transaction keeps the steps of the ZVT dialogue (sent, accepted, intermediate status, result, acknowledgement, completion) and the receipts.

Totals per card brand from the terminal and its end-of-day receipt.

Here the connection dropped right after the result: Odoo asked the terminal for its last stored transaction and recorded the answer. A manager can also record the result by hand after looking at the terminal.

Generate a relay token, download the relay (Python 3, standard library) and run it on a computer in the shop. It polls Odoo every second over HTTPS and talks to the terminal on the shop network.

All screens and the terminal messages are translated into German.

How it works
1 | Enable ZVT on the terminal Your terminal supplier enables the ECR (Kassen) interface over TCP/IP and gives you the IP address, the port (usually 20007) and the terminal password. |
2 | Add the terminal in Odoo Point of Sale > Configuration > ZVT Terminals. Choose who connects: the Odoo server (Odoo in the shop network or over a VPN) or the shop relay. Test Connection, then Register. |
3 | Create the payment method Point of Sale > Configuration > Payment Methods: Use a Payment Terminal = ZVT Terminal, pick the terminal, add the method to your Point of Sale. |
4 | Take payments Pick the method on the payment screen. Odoo registers the terminal if needed, sends the amount, follows the terminal messages and finishes the line when the terminal answers. |
Settings
| Setting | What it does |
| Connection | Odoo server connects (TCP/IP from the Odoo server) or Shop relay connects (relay in the shop, TCP/IP or RS232). |
| Terminal address / port | IP address and port of the terminal as seen by the Odoo server or the relay; default port 20007. |
| Terminal password | 6 digits, sent as 3 byte BCD with refund, reversal, end-of-day and repeat receipt. Visible to POS managers only. |
| Receipts | Odoo receives the receipt lines (Print Line 06 D1 or Print Text-Block 06 D3) or the terminal prints its own. |
| Receipt line width / UTF-8 | Printer width sent to the terminal (TLV 12) and an optional UTF-8 request (TLV 14), used only when the terminal accepts it. |
| Send currency | ISO numeric currency code with each command (EUR when not sent). |
| Receipt number synchronisation | Sends TLV 1F1F with the receipt number of the last transaction Odoo accepted (ZVT chapter 4). |
| T3 / T4 / connect time-outs | Answer time-out (default 5 s), transaction time-out (default 180 s, restarted by every terminal message), connect time-out. |
| End-of-Day on session close | Runs the terminal End-of-Day when a POS session using the terminal closes. |
Connection design and limits
A browser cannot open a TCP connection to a terminal, so the Point of Sale never talks to the terminal itself: it asks Odoo, and Odoo runs the ZVT dialogue in a background thread (server mode) or hands it to the shop relay (relay mode). Every step is stored in the database and the POS asks Odoo for the progress every 0.7 seconds.
Server mode needs the Odoo server to reach the terminal's address: Odoo installed in the shop, or a VPN between the server and the shop network. In a multi-worker Odoo the dialogue runs in the worker that started it; if that worker is restarted during a payment, the minute cron marks the transaction as unknown and checks it on the terminal.
Relay mode needs a computer that stays on in the shop (Windows, macOS or Linux with Python 3) running the relay; nothing has to be opened in the shop firewall. RS232 terminals need the relay and pyserial. The Odoo IoT Box is not used: in Odoo 19 Community it has no ZVT driver, and this module does not depend on it.
Tested how: the module was not run on a real terminal. It is written from the public ZVT specification (revision 13.13 and the transport protocol revision 04) and tested against a ZVT terminal simulator built from that specification, which ships with the module. The serial (RS232) transport is implemented but was tested only at the framing level (DLE/STX, CRC). Ask your terminal supplier whether your model offers ZVT over TCP/IP; we are glad to help with the first set-up. Not included: OPI, DCC, tips, pre-authorisation and fuel / vending commands.
FAQ
Compatibility and support
Odoo 19 Community and Enterprise, Point of Sale. On-premise (server mode or relay) and hosted Odoo such as Odoo.sh (relay). English and German. Price shown in USD.
Support: modvantaapps@gmail.com - questions, set-up help and custom work are welcome.
EMAIL modvantaapps@gmail.com | AUTHOR Modvanta | INCLUDED Module, relay, simulator |
Odoo Proprietary License v1.0 This software and associated files (the "Software") may only be used (executed, modified, executed after modifications) if you have purchased a valid license from the authors, typically via Odoo Apps, or if you have received a written agreement from the authors of the Software (see the COPYRIGHT file). You may develop Odoo modules that use the Software as a library (typically by depending on it, importing it and using its resources), but without copying any source code or material from the Software. You may distribute those modules under the license of your choice, provided that this license is compatible with the terms of the Odoo Proprietary License (For example: LGPL, MIT, or proprietary licenses similar to this one). It is forbidden to publish, distribute, sublicense, or sell copies of the Software or modified copies of the Software. The above copyright notice and this permission notice must be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Please log in to comment on this module