💳 ecr17-protocol

The Italian ECR17 payment protocol in pure Rust — drive Nexi Group POS terminals over LAN from any Rust app, plus a Tauri desktop control panel.

The most complete open-source ECR17 toolkit for Rust & the desktop.

🐘 Using PHP / Laravel? → padosoft/laravel-ecr17  ·  📱 Using React Native / mobile? → padosoft/react-native-ecr17-protocol — the same ECR17 protocol, ported to each ecosystem.

📚 Table of contents

• What is ECR17?
• Why this exists
• Highlights
• Screenshots
• Feature status
• Installation
• Quick start
• Money-safety
• Configuration
• API reference
• Events
• Tokenization & receipts
• Protocol cheat-sheet
• Architecture
• The Tauri control panel
• Testing
• Other ports
• Vibe-coding batteries included
• License

🧭 What is ECR17?

ECR17 is the Italian standard protocol — supported by Nexi Group terminals — that integrates an Electronic Cash Register (ECR) with an EFT-POS payment terminal over a local LAN connection. The cash register sends a request (payment, reversal, status…), the terminal talks to the acquiring host, and replies synchronously.

This crate speaks that protocol from Rust: a pure, #![forbid(unsafe_code)] protocol engine plus an async Ecr17Client and an optional tokio TCP transport — no C, no FFI, no bridge.

📚 Official protocol reference (public): https://developer.nexigroup.com/traditionalpos/en-EU/docs/ — the authoritative source. Field positions, message codes and lrcMode may vary by terminal/firmware; always check against the official docs.

🎯 Why this exists

Integrating Italian POS terminals has long been needlessly painful. The ECR17 protocol is not publicly documented — the specifications are shared under NDA, mostly with established point-of-sale software vendors — so everyone else reverse-engineers it by trial and error across terminals and firmware versions. (The classic trap that blocks almost everyone: the LRC is computed over a base of 0x7F, not 0x00 — handled here, and configurable per terminal.)

A few community efforts exist for server-side languages, but there was nothing idiomatic for Rust or the desktop. To our knowledge this is the most complete open-source ECR17 toolkit for Rust: the full command set, response parsing, the ACK/NAK + retransmit orchestration, configurable LRC modes, and payment-safety — all tested, all async, all pure Rust.

The goal is simple: Rust and desktop developers should no longer struggle to talk to Italian POS terminals. No NDA hunting, no guesswork — just client.pay(&req).await.

🤝 Compatibility notes (lrcMode, field quirks per terminal/firmware) are welcome as issues, so we can build, together, the reference the ecosystem never had.

✨ Highlights

• 🦀 Pure-Rust protocol core — framing / LRC / orchestration, #![forbid(unsafe_code)], no FFI.
• 🔄 Async, Future-based API — client.pay(&req).await, built on tokio.
• 🧱 Full command set — payment, extended payment, reversal, pre-auth (request / incremental / closure), card verification, close session, totals, last result, ECR printing, reprint, VAS.
• 🛡️ Robust by design — fixed-width field validation, defensive response parsing, ACK/NAK handshake with retransmit and timeouts.
• 💰 Money-safe — a financial command is never blindly re-sent after a reconnect (double-charge protection), locked by unit tests. Recover a lost response via send_last_result() (spec G).
• 📡 Live events — progress messages, streamed receipt lines, connection state — via callbacks.
• 🔌 Transport-agnostic — I/O lives behind an async Transport trait; the real tokio TCP socket is one feature flag away, and the in-memory FakeTransport makes the whole stack testable with no hardware.
• 🖥️ Tauri control panel — a cross-platform desktop debug console that exercises every command and streams the behind-the-scenes log live.
• ✅ Heavily tested — 108 Rust unit / flow / money-safety tests (LRC, codec, every builder, every parser, full session orchestration) plus 12 Vitest + 12 Playwright e2e for the UI, all green in CI.
• 🤖 Vibe-coding batteries included — ships first-class AI-agent context (AGENTS.md, CLAUDE.md, docs/LESSON.md, PROGRESS.md). See below.

📸 Screenshots

The repo ships a Tauri Control Panel app that exercises every ECR17 command against a real terminal and streams the behind-the-scenes log (sent / progress / receipt / result / error) live — with card PANs masked.

📊 Feature status

📦 Installation

# Protocol core only (bring your own transport):
cargo add ecr17-protocol

# With the real tokio TCP transport:
cargo add ecr17-protocol --features tokio-transport
cargo add tokio --features full

MSRV 1.85 (the TCP liveness probe uses std::task::Waker::noop).

🚀 Quick start

use std::time::Duration;
use ecr17_protocol::{Ecr17Client, Ecr17Config, LrcMode, PaymentRequest, ReversalRequest};
use ecr17_protocol::transport::tcp::TcpTransport; // needs feature "tokio-transport"

#[tokio::main]
async fn main() -> ecr17_protocol::Result<()> {
    let config = Ecr17Config {
        host: "192.168.1.50".into(),   // terminal IP on the LAN
        port: Some(10000),              // configured ECR port
        terminal_id: "12345678".into(),
        cash_register_id: "00000001".into(),
        lrc_mode: Some(LrcMode::Std),
        keep_alive: Some(true),
        auto_reconnect: Some(true),
        connection_timeout_ms: Some(5000),
        response_timeout_ms: Some(60000),
        ack_timeout_ms: Some(2000),
        receipt_drain_ms: None,
        retry_count: Some(3),
        retry_delay_ms: Some(200),
        debug: Some(false),
    };

    let transport = TcpTransport::new(
        config.host.clone(),
        config.port.unwrap_or(10000),
        Duration::from_secs(5),
    );
    let mut client = Ecr17Client::new(transport, config);

    client.connect().await?;

    let result = client.pay(&PaymentRequest {
        amount_cents: 650,               // €6.50
        cash_register_id: None,
        payment_type: None,
        card_already_present: None,
        receipt_text: None,
        tokenization: None,
    }).await?;

    if result.outcome == ecr17_protocol::TransactionOutcome::Ok {
        println!(
            "Approved: auth {:?} PAN {:?}",
            result.auth_code, result.pan, // both Option<String> — masked PAN
        );
    } else {
        eprintln!("Declined: {:?}", result.error_description);
    }

    // Reversal ("annullamento") of the last transaction (no STAN → reverses the last):
    client.reverse(&ReversalRequest { cash_register_id: None, stan: None }).await.ok();

    let _status = client.status().await?;   // PosStatusResponse
    client.disconnect().await;
    Ok(())
}

Request structs are plain data — construct the fields you need and leave the Option ones None. The optional .. fields map straight onto the wire defaults.

💰 Money-safety

This crate drives a terminal that charges real cards, so payment integrity is a first-class, tested invariant — not an afterthought:

• A financial command is never blindly re-sent. pay, pay_extended, reverse, pre_auth, incremental_auth, pre_auth_closure are not replayed after a transport drop/reconnect (a blind retry can double-charge). The decision lives in one tiny, unit-locked place — should_retry_after_reconnect — which only ever allows retrying safe/idempotent ops (status, totals).
• Recover a lost response, don't replay it. If the reply is lost mid-flight, call send_last_result() (the spec's G command) to fetch the real outcome.
• Proactive drop detection. Nexi terminals close the TCP socket between transactions, so the transport does a non-destructive liveness probe (poll_peek) before sending — never writing bytes on the peer's protocol stream — so a financial command never even starts on a stale socket.
• Reusable across reconnects. The session holds no sticky "disconnected" flag; it resets its per-transaction state, so a fresh transaction is never blocked by a previous drop.

These rules are guarded by regression tests (financial_command_not_replayed_on_drop, safe_command_retried_after_reconnect, recovers_and_succeeds_after_reconnect, …) that must stay green.

⚙️ Configuration

Ecr17Config: host (required), port?, terminal_id (required), cash_register_id (required), lrc_mode?, keep_alive?, auto_reconnect?, connection_timeout_ms?, response_timeout_ms?, ack_timeout_ms?, receipt_drain_ms?, retry_count?, retry_delay_ms?, debug?.

All fields serde-camelCase on the wire (cash_register_id ⇄ cashRegisterId), so the same config round-trips cleanly to the Tauri frontend / any JSON consumer.

📖 API reference

Every command is async and performs a full request/response exchange. new / configuration are synchronous.

Commands require an open connection (connect() first) and error on timeout / retransmission exhaustion / disconnect.

📡 Events

client.set_on_progress(|e| println!("progress: {}", e.message));
client.set_on_receipt_line(|l| append_to_receipt(l.text));
client.set_on_connection_state_change(|s| println!("connection: {s:?}"));

Callbacks are Fn(..) + Send + Sync + 'static. They are invoked with no client lock held, so a callback may safely call back into the client.

🧾 Tokenization & receipts

// Tokenization: attach a contract to a payment / preAuth / verifyCard. The 'U'
// additional-data message is sent automatically (P -> ACK -> U -> ACK -> result).
use ecr17_protocol::{TokenizationRequest, TokenizationService};

let req = PaymentRequest {
    amount_cents: 1000,
    tokenization: Some(TokenizationRequest {
        service: TokenizationService::Recurring,
        contract_code: "1666354841608".into(),
    }),
    cash_register_id: None, payment_type: None,
    card_already_present: None, receipt_text: None,
};

// Receipts printed by the ECR: enable printing, set receipt_drain_ms in the config,
// and receive lines via the event.
client.enable_ecr_printing(true).await?;
client.set_on_receipt_line(|l| append_to_receipt(l.text));

🔐 Protocol cheat-sheet

App frame: STX(0x02) · payload · ETX(0x03) · LRC. Progress: SOH(0x01) · 20 chars · EOT(0x04) (no LRC). Confirmation: ACK(0x06) / NAK(0x15) · ETX · LRC. LRC = 0x7F XOR-folded; the framing bytes folded in are selectable via lrc_mode (stx / std / noext / stx_noext). Status code is lowercase s; a P payment request is 167 bytes; receipts arrive as one or more S messages. Outcome map: 00→ok, 01→ko, 05→cardNotPresent, 09→unknownTag.

🏗️ Architecture

crates/ecr17-protocol/src/
├── lrc.rs        # LRC (4 modes, base 0x7F) + LrcMode
├── codec.rs      # framing: STX·ETX·SOH·EOT·ACK·NAK + LRC (encode/decode)
├── types.rs      # request/result/enum data model (serde, camelCase)
├── protocol.rs   # request builders (all commands), fixed-width + validated
├── response.rs   # response field parsers -> plain structs (incl. DCC, PAN mask)
├── retry.rs      # 💰 RetryPolicy — a financial command is never replayed
├── transport.rs  # async Transport trait + in-memory FakeTransport (tests)
├── session.rs    # ACK/NAK + retransmit + timeout + receipt-drain orchestration
├── client.rs     # Ecr17Client async API + events + auto/proactive reconnect
└── transport/tcp.rs   # tokio TCP transport (feature "tokio-transport")
app/
├── src-tauri/    # Rust backend: managed Ecr17Client, one #[tauri::command] per cmd, events
└── src/          # React 19 + TypeScript + Vite control panel (typed IPC, useEcr17 hook)

Design. The codec / protocol / response layers are pure and sync — trivially unit-testable with no runtime. I/O lives behind the async Transport trait, so the session/client run against a scripted FakeTransport in tests (including simulated mid-exchange drops) and a real tokio socket in production.

🖥️ The Tauri control panel

app/ is a cross-platform Tauri 2 desktop app (React 19 + TypeScript + Vite) that holds an Ecr17Client in managed state and exposes one #[tauri::command] per protocol command. It’s the fastest way to poke a terminal: pick a command, fill the dynamically-generated parameters sheet (money fields coerce € → cents), hit run, and watch the sent/progress/receipt/result log stream live — PANs masked. Native installers (Windows .msi/NSIS, macOS .dmg, Linux .deb/AppImage) are built in CI and attached to each GitHub Release.

🧪 Testing

# Exactly what CI (rust-tests) runs:
cargo test --workspace --all-features            # 108 unit / flow / money-safety tests
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo fmt --all -- --check

# Frontend (from app/):
bun run typecheck && bun run test  # 12 Vitest
bun run e2e                        # 12 Playwright (Tauri IPC mocked)

The Rust tests cover LRC, packet (de)framing edge cases, every builder's byte layout, every response parser, and the documented payment / reversal / re-pay / progress / receipt / NAK-retransmit / timeout / reconnect-recovery flows (against an in-memory FakeTransport).

Against a real terminal (opt-in)

An #[ignore]d integration test runs the core over a real TCP socket. It is skipped unless ECR17_TEST_HOST is set:

ECR17_TEST_HOST=192.168.1.50 ECR17_TEST_PORT=10000 \
  cargo test --features tokio-transport -- --ignored real_terminal

🧩 Other ports

The same ECR17 protocol, maintained across ecosystems:

🤖 Vibe-coding batteries included

Building on an undocumented payment protocol is exactly where AI assistants get things subtly wrong. This repo ships the context to prevent that, so an agent (or a new contributor) is productive and safe from minute one:

• AGENTS.md / CLAUDE.md — project guide, the mandatory per-task workflow, CI strategy, and the money-critical rules (e.g. never blindly retry a payment).
• docs/LESSON.md — accumulated, verified engineering lessons (Rust/Tauri APIs, toolchain traps, protocol facts, money-safety) — the gotchas already solved.
• PROGRESS.md — crash-safe resume state across sessions.

The result: less hallucination, fewer footguns, and changes that respect the payment-safety invariants by default.

📄 License

MIT © padosoft

Disclaimer: independent integration library. "ECR17", "Nexi" and related marks belong to their respective owners and are referenced for interoperability only.