💳 laravel-ecr17

Drive Italian ECR17 / "Protocollo 17" POS terminals (Nexi Group) over TCP — straight from your Laravel app.

The most complete open-source ECR17 toolkit for PHP & Laravel.

📱 Building for iOS / Android (React Native)? There's a sibling port: padosoft/react-native-ecr17-protocol — the same ECR17 protocol as a React Native / Nitro module. It is the behavioral source of truth; this PHP package mirrors its protocol core and test suite.

📚 Table of contents

• What is ECR17?
• Highlights
• Requirements
• Installation
• Quick start
• Configuration
• Commands
• Events
• Money safety
• Connection handling
• Demo debug console
• Production usage
• Testing
• License

💡 What is ECR17?

ECR17 ("Protocollo 17") is the Italian amount-exchange protocol spoken between a cash register (ECR) and a payment terminal (POS) over TCP/IP, supported by Nexi Group terminals. The ECR frames an application message (STX … ETX LRC), the terminal ACK/NAKs it, streams progress and receipt lines, and returns the transaction result. This package implements the full protocol — framing, LRC, the ACK/NAK handshake with retransmission and timeouts, every command builder and response parser — as a clean, framework-free PHP core wrapped in a thin Laravel layer.

✨ Highlights

• Framework-free protocol core (Padosoft\Ecr17\Protocol|Response|Session) — pure PHP, unit-tested in isolation.
• Every ECR17 command: status, pay, extended pay, reverse, pre-auth, incremental, pre-auth closure, card verification, close session, totals, send-last-result, ECR printing, reprint, VAS, plus tokenization (U).
• 💰 Money-safe by design — a financial command is never blindly re-sent after a drop (no double-charge); recover via sendLastResult() (G).
• Proactive reconnection — a stale (peer-closed) socket is detected and reconnected before sending, so a payment never starts on a dead socket.
• Progress & receipt streaming via events/callbacks.
• Tested against real scripted scenarios (Pest), ported 1:1 from the React Native sibling's GoogleTest suite.

✅ Requirements

• PHP 8.3+, Laravel 13 (PHP 8.3–8.5).
• The PHP server must be able to reach the POS terminal over TCP on the LAN.

📦 Installation

composer require padosoft/laravel-ecr17

Publish the config (optional):

php artisan vendor:publish --tag=ecr17-config

🚀 Quick start

use Padosoft\Ecr17\Facades\Ecr17;

// Configure via config/ecr17.php (or .env), then:
Ecr17::connect();

$result = Ecr17::pay(amountCents: 1000, paymentType: 'credit'); // €10.00

if ($result->outcome === \Padosoft\Ecr17\Response\Outcome::Ok) {
    // $result->authCode, $result->pan, $result->stan, ...
}

Or build a client explicitly (e.g. with your own transport):

use Padosoft\Ecr17\Ecr17Client;
use Padosoft\Ecr17\Ecr17Config;
use Padosoft\Ecr17\Transport\SocketTransport;

$config = new Ecr17Config(host: '192.168.1.50', port: 10000, terminalId: '12345678', cashRegisterId: '1');
$client = new Ecr17Client(new SocketTransport($config->host, $config->port, $config->connectionTimeoutMs), $config);

$status = $client->status();

⚙️ Configuration

config/ecr17.php (all keys overridable via .env):

🧾 Commands

status(), pay(), payExtended(), reverse(), preAuth(), incrementalAuth(), preAuthClosure(), verifyCard(), closeSession(), totals(), sendLastResult(), enableEcrPrinting(), reprint(), vas().

Payments/pre-auth/verify accept an optional TokenizationRequest (U).

📡 Events

Wire callbacks for real-time updates:

$client->setOnProgress(fn (string $msg) => /* "INSERIRE CARTA" ... */);
$client->setOnReceiptLine(fn (string $line) => /* receipt text */);
$client->setOnConnectionStateChange(fn (string $state) => /* connecting|connected|disconnected */);

💰 Money safety

A connection can drop after the terminal has charged the card but before the response arrives. Re-sending the request would double-charge. Therefore a financial command is never retried after a drop — only read-only/idempotent commands (status, totals, sendLastResult, enableEcrPrinting) are. To recover a lost result, call sendLastResult() (command G). This invariant lives in Session\RetryPolicy and is locked by its tests.

🔌 Connection handling

ECR17/Nexi terminals often close the TCP socket between transactions. The client runs a non-destructive liveness probe before each command and reconnects proactively, so a command never starts on a stale, half-open socket (which would otherwise fail and — correctly — refuse a financial retry).

🖥️ Demo debug console

The demo/ directory contains a small Laravel app with a React + Tailwind debug console (AJAX): configure & connect to a POS, run every command, and watch the behind-the-scenes log (on screen + file). See demo/README.md.

🏭 Production usage

The demo runs commands synchronously for simplicity. A payment can block up to response_timeout_ms (~60s) while the cardholder interacts — that would tie up a PHP-FPM worker. In production, drive the package from a queued job (Laravel Queue + worker) and poll/push the result, or run it under Octane/Swoole. Never block a web request on a live payment.

🧪 Testing

composer test     # Pest
composer lint     # Pint --test
composer analyse  # PHPStan

📄 License

MIT © padosoft