PHPackages padosoft/laravel-ecr17 - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Payment Processing](/categories/payments) 4. / 5. padosoft/laravel-ecr17 ActiveLibrary[Payment Processing](/categories/payments) padosoft/laravel-ecr17 ====================== Italian ECR17 / Protocollo 17 payment protocol (Nexi Group POS terminals) over TCP for PHP & Laravel. v1.0.0(1mo ago)50MITPHPPHP ^8.3CI failing Since May 29Pushed 1w agoCompare [ Source](https://github.com/padosoft/laravel-ecr17)[ Packagist](https://packagist.org/packages/padosoft/laravel-ecr17)[ Docs](https://github.com/padosoft/laravel-ecr17)[ RSS](/packages/padosoft-laravel-ecr17/feed)WikiDiscussions main Synced 1w ago READMEChangelog (2)Dependencies (6)Versions (3)Used By (0) πŸ’³ laravel-ecr17 =============== [](#-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.** πŸ“š **Official docs:** [![Packagist Version](https://camo.githubusercontent.com/184b47443e738686983733ce96681fad6e6feaf58b8deaa62e6472ee83299e8c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7061646f736f66742f6c61726176656c2d65637231372e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/padosoft/laravel-ecr17)[![Tests](https://github.com/padosoft/laravel-ecr17/actions/workflows/tests.yml/badge.svg)](https://github.com/padosoft/laravel-ecr17/actions/workflows/tests.yml)[![License: MIT](https://camo.githubusercontent.com/6c56804c3814da67aeda53fb73e1dae7b5dd492e476e7511d76cc754f823ffb8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f7061646f736f66742f6c61726176656c2d65637231372e7376673f7374796c653d666c61742d737175617265)](LICENSE)[![PHP](https://camo.githubusercontent.com/29a4b1dfdcf98d7b584e34a45529343c1fe346f17283ea49fcabae2805b28d7f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f7061646f736f66742f6c61726176656c2d65637231372e7376673f7374796c653d666c61742d737175617265)](composer.json) [![laravel-ecr17 banner](resources/banner.png)](resources/banner.png) > πŸ“± **Building for iOS / Android (React Native)?** There's a sibling port: **[padosoft/react-native-ecr17-protocol](https://github.com/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. > > πŸ¦€ **Using Rust / building a desktop app?** There's a sibling port: **[padosoft/rust-ecr17-protocol](https://github.com/padosoft/rust-ecr17-protocol)** β€” the same ECR17 protocol as a pure-Rust crate + a Tauri desktop control panel. --- πŸ“š Table of contents ------------------- [](#-table-of-contents) - [What is ECR17?](#-what-is-ecr17) - [Highlights](#-highlights) - [Requirements](#-requirements) - [Installation](#-installation) - [Quick start](#-quick-start) - [Configuration](#-configuration) - [Commands](#-commands) - [Events](#-events) - [Money safety](#-money-safety) - [Connection handling](#-connection-handling) - [Demo debug console](#-demo-debug-console) - [Production usage](#-production-usage) - [Testing](#-testing) - [License](#-license) πŸ’‘ What is ECR17? ---------------- [](#-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 ------------ [](#-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 -------------- [](#-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 -------------- [](#-installation) ``` composer require padosoft/laravel-ecr17 ``` Publish the config (optional): ``` php artisan vendor:publish --tag=ecr17-config ``` πŸš€ Quick start ------------- [](#-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 ---------------- [](#️-configuration) `config/ecr17.php` (all keys overridable via `.env`): KeyEnvDefaultNotes`host``ECR17_HOST``''`POS terminal IP`port``ECR17_PORT``1024`TCP port`terminal_id``ECR17_TERMINAL_ID``''`8-char terminal id`cash_register_id``ECR17_CASH_REGISTER_ID``''`ECR id`lrc_mode``ECR17_LRC_MODE``std``stx | std | noext | stx_noext``auto_reconnect``ECR17_AUTO_RECONNECT``true`reconnect + retry safe ops on drop`connection_timeout_ms``ECR17_CONNECTION_TIMEOUT_MS``5000``response_timeout_ms``ECR17_RESPONSE_TIMEOUT_MS``60000`cardholder wait`ack_timeout_ms``ECR17_ACK_TIMEOUT_MS``2000``retry_count` / `retry_delay_ms`…`3` / `200`retransmissions`receipt_drain_ms``ECR17_RECEIPT_DRAIN_MS``0`keep forwarding `S` lines after the result🧾 Commands ---------- [](#-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 -------- [](#-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 -------------- [](#-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 --------------------- [](#-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 --------------------- [](#️-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). [![ECR17 Debug Console demo app](resources/screenshoots/ECR17-Debug-Console.png)](resources/screenshoots/ECR17-Debug-Console.png) ``` cd demo composer install cp .env.example .env # PowerShell: Copy-Item .env.example .env php artisan key:generate php artisan serve # then open http://localhost:8000 ``` No `npm`/Vite build is needed β€” the frontend loads React + Tailwind from a CDN. See [`demo/README.md`](demo/README.md) for details. 🏭 Production usage ------------------ [](#-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 --------- [](#-testing) ``` composer test # Pest composer lint # Pint --test composer analyse # PHPStan ``` πŸ“„ License --------- [](#-license) MIT Β© [padosoft](https://github.com/padosoft) ### Health Score 41 β€” FairBetter than 87% of packages Maintenance94 Actively maintained with recent releases Popularity5 Limited adoption so far Community8 Small or concentrated contributor base Maturity50 Maturing project, gaining track record Bus Factor1 Top contributor holds 95% of commits β€” single point of failure How is this calculated?**Maintenance (25%)** β€” Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** β€” Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** β€” Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** β€” Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 57d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/10467699?v=4)[Lorenzo](/maintainers/lopadova)[@lopadova](https://github.com/lopadova) --- Top Contributors [![lopadova](https://avatars.githubusercontent.com/u/10467699?v=4)](https://github.com/lopadova "lopadova (19 commits)")[![ImgBotApp](https://avatars.githubusercontent.com/u/31427850?v=4)](https://github.com/ImgBotApp "ImgBotApp (1 commits)") --- Tags ecr17laravelnexipayment-terminalphpposlaravelposnexiecr17protocollo17payment-terminalcassa ### Code Quality TestsPest Static AnalysisPHPStan Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/padosoft-laravel-ecr17/health.svg) ``` [![Health](https://phpackages.com/badges/padosoft-laravel-ecr17/health.svg)](https://phpackages.com/packages/padosoft-laravel-ecr17) ``` ### Alternatives [psalm/plugin-laravel Psalm plugin for Laravel 3345.3M347](/packages/psalm-plugin-laravel)[laravel/horizon Dashboard and code-driven configuration for Laravel queues. 4.2k95.4M321](/packages/laravel-horizon)[laravel/sail Docker files for running a basic Laravel application. 1.9k205.7M1.3k](/packages/laravel-sail)[illuminate/database The Illuminate Database package. 2.8k54.9M12.2k](/packages/illuminate-database)[laravel/ai The official AI SDK for Laravel. 1.0k3.2M246](/packages/laravel-ai)[moonshine/moonshine Laravel administration panel 1.3k253.1k86](/packages/moonshine-moonshine) PHPackages Β© 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)