@padosoft/react-native-ecr17 0.0.0

package/cpp/Ecr17Protocol/Ecr17Protocol.cpp

@@ -0,0 +1,277 @@
+#include "Ecr17Protocol.hpp"
+
+#include <stdexcept>
+
+namespace margelo::nitro::ecr17 {
+
+namespace {
+
+constexpr char kReserved = '0';     // '0' (0x30) filler for reserved numeric fields
+constexpr char kFieldSep = 0x1B;    // end-of-field for the privative TAG content
+
+// Right-aligns `value` into a fixed-width field of `size` bytes, padding on the
+// left with `ch`. ECR17 fields have a fixed length, so a value longer than the
+// field would shift every following field and corrupt the frame: reject it.
+std::string leftPad(const std::string& value, size_t size, char ch = kReserved) {
+    if (value.size() > size) {
+        throw std::invalid_argument("ECR17: value '" + value + "' exceeds fixed field width of " +
+                                    std::to_string(size) + " bytes");
+    }
+    if (value.size() == size) {
+        return value;
+    }
+    return std::string(size - value.size(), ch) + value;
+}
+
+// Left-aligns `value` into a fixed-width field, padding on the right with `ch`.
+std::string rightPad(const std::string& value, size_t size, char ch = ' ') {
+    if (value.size() > size) {
+        throw std::invalid_argument("ECR17: value '" + value + "' exceeds fixed field width of " +
+                                    std::to_string(size) + " bytes");
+    }
+    return value + std::string(size - value.size(), ch);
+}
+
+std::string amountField(int amountCents) {
+    if (amountCents < 0) {
+        throw std::invalid_argument("ECR17: amount must be non-negative");
+    }
+    return leftPad(std::to_string(amountCents), 8);
+}
+
+char flag(bool on) { return on ? '1' : '0'; }
+
+// Shared 167-byte payment-family layout (codes 'P', 'X', 'p').
+std::string buildPaymentLike(char code, const std::string& terminalId,
+                             const std::string& cashRegisterId, int amountCents, char paymentType,
+                             bool cardAlreadyPresent, bool withAdditionalData,
+                             const std::string& receiptText) {
+    std::string m;
+    m += leftPad(terminalId, 8);                  // 1  : terminal id
+    m += kReserved;                               // 9  : reserved
+    m += code;                                    // 10 : message code
+    m += leftPad(cashRegisterId, 8);              // 11 : cash register id
+    m += flag(withAdditionalData);                // 19 : presence of additional GT data
+    m += "00";                                    // 20 : reserved
+    m += flag(cardAlreadyPresent);                // 22 : start-with-card-present
+    m += paymentType;                             // 23 : payment type
+    m += amountField(amountCents);                // 24 : amount (8)
+    m += leftPad(receiptText, 128, ' ');          // 32 : receipt text (128)
+    m += "00000000";                              // 160: reserved (8)
+    return m;                                     // 167
+}
+
+// Shared 176-byte pre-auth integration/closure layout (codes 'i', 'c').
+std::string buildPreAuthFollowUp(char code, const std::string& terminalId,
+                                 const std::string& cashRegisterId, int amountCents,
+                                 const std::string& originalPreAuthCode, bool withAdditionalData,
+                                 const std::string& receiptText) {
+    std::string m;
+    m += leftPad(terminalId, 8);            // 1  : terminal id
+    m += kReserved;                         // 9  : reserved
+    m += code;                              // 10 : message code
+    m += leftPad(cashRegisterId, 8);        // 11 : cash register id
+    m += flag(withAdditionalData);          // 19 : presence of additional GT data
+    m += "0000";                            // 20 : reserved (4)
+    m += amountField(amountCents);          // 24 : amount (8)
+    m += leftPad(receiptText, 128, ' ');    // 32 : receipt text (128)
+    m += leftPad(originalPreAuthCode, 9);   // 160: original pre-auth code (9)
+    m += "00000000";                        // 169: reserved (8)
+    return m;                               // 176
+}
+
+// Shared 26-byte session command layout (codes 'C', 'T').
+std::string buildSessionCommand(char code, const std::string& terminalId,
+                                const std::string& cashRegisterId, bool withAdditionalData) {
+    std::string m;
+    m += leftPad(terminalId, 8);      // 1  : terminal id
+    m += kReserved;                   // 9  : reserved
+    m += code;                        // 10 : message code
+    m += leftPad(cashRegisterId, 8);  // 11 : cash register id
+    m += flag(withAdditionalData);    // 19 : presence of additional GT data
+    m += "0000000";                   // 20 : reserved (7)
+    return m;                         // 26
+}
+
+}  // namespace
+
+std::string Ecr17Protocol::buildPaymentMessage(const std::string& terminalId,
+                                               const std::string& cashRegisterId, int amountCents,
+                                               char paymentType, bool cardAlreadyPresent,
+                                               bool withAdditionalData,
+                                               const std::string& receiptText) {
+    return buildPaymentLike('P', terminalId, cashRegisterId, amountCents, paymentType,
+                            cardAlreadyPresent, withAdditionalData, receiptText);
+}
+
+std::string Ecr17Protocol::buildExtendedPaymentMessage(const std::string& terminalId,
+                                                       const std::string& cashRegisterId,
+                                                       int amountCents, char paymentType,
+                                                       bool cardAlreadyPresent,
+                                                       bool withAdditionalData,
+                                                       const std::string& receiptText) {
+    return buildPaymentLike('X', terminalId, cashRegisterId, amountCents, paymentType,
+                            cardAlreadyPresent, withAdditionalData, receiptText);
+}
+
+std::string Ecr17Protocol::buildPreAuthMessage(const std::string& terminalId,
+                                               const std::string& cashRegisterId, int amountCents,
+                                               char paymentType, bool cardAlreadyPresent,
+                                               bool withAdditionalData,
+                                               const std::string& receiptText) {
+    return buildPaymentLike('p', terminalId, cashRegisterId, amountCents, paymentType,
+                            cardAlreadyPresent, withAdditionalData, receiptText);
+}
+
+std::string Ecr17Protocol::buildIncrementalMessage(const std::string& terminalId,
+                                                   const std::string& cashRegisterId,
+                                                   int amountCents,
+                                                   const std::string& originalPreAuthCode,
+                                                   bool withAdditionalData,
+                                                   const std::string& receiptText) {
+    return buildPreAuthFollowUp('i', terminalId, cashRegisterId, amountCents, originalPreAuthCode,
+                                withAdditionalData, receiptText);
+}
+
+std::string Ecr17Protocol::buildPreAuthClosureMessage(const std::string& terminalId,
+                                                      const std::string& cashRegisterId,
+                                                      int amountCents,
+                                                      const std::string& originalPreAuthCode,
+                                                      bool withAdditionalData,
+                                                      const std::string& receiptText) {
+    return buildPreAuthFollowUp('c', terminalId, cashRegisterId, amountCents, originalPreAuthCode,
+                                withAdditionalData, receiptText);
+}
+
+std::string Ecr17Protocol::buildCardVerificationMessage(const std::string& terminalId,
+                                                        const std::string& cashRegisterId,
+                                                        char paymentType, bool withAdditionalData) {
+    std::string m;
+    m += leftPad(terminalId, 8);      // 1  : terminal id
+    m += kReserved;                   // 9  : reserved
+    m += 'H';                         // 10 : message code
+    m += leftPad(cashRegisterId, 8);  // 11 : cash register id
+    m += flag(withAdditionalData);    // 19 : presence of additional GT data
+    m += "00";                        // 20 : reserved (2)
+    m += '0';                         // 22 : standard card verification
+    m += paymentType;                 // 23 : payment type
+    m += "0000000000000000";          // 24 : reserved (16)
+    return m;                         // 39
+}
+
+std::string Ecr17Protocol::buildCloseSessionMessage(const std::string& terminalId,
+                                                    const std::string& cashRegisterId,
+                                                    bool withAdditionalData) {
+    return buildSessionCommand('C', terminalId, cashRegisterId, withAdditionalData);
+}
+
+std::string Ecr17Protocol::buildTotalsMessage(const std::string& terminalId,
+                                              const std::string& cashRegisterId,
+                                              bool withAdditionalData) {
+    return buildSessionCommand('T', terminalId, cashRegisterId, withAdditionalData);
+}
+
+std::string Ecr17Protocol::buildSendLastResultMessage(const std::string& terminalId,
+                                                      const std::string& cashRegisterId,
+                                                      bool withAdditionalData) {
+    std::string m;
+    m += leftPad(terminalId, 8);      // 1  : terminal id
+    m += kReserved;                   // 9  : reserved
+    m += 'G';                         // 10 : message code
+    m += leftPad(cashRegisterId, 8);  // 11 : cash register id
+    m += flag(withAdditionalData);    // 19 : presence of additional GT data
+    m += "000";                       // 20 : reserved (3)
+    return m;                         // 22
+}
+
+std::string Ecr17Protocol::buildEnableEcrPrintMessage(const std::string& terminalId, bool enabled) {
+    std::string m;
+    m += leftPad(terminalId, 8);  // 1  : terminal id
+    m += kReserved;               // 9  : reserved
+    m += 'E';                     // 10 : message code
+    m += flag(enabled);           // 11 : enable(1)/disable(0) printing on ECR
+    return m;                     // 11
+}
+
+std::string Ecr17Protocol::buildReprintMessage(const std::string& terminalId, bool toEcr,
+                                               char ticketType) {
+    std::string m;
+    m += leftPad(terminalId, 8);  // 1  : terminal id
+    m += kReserved;               // 9  : reserved
+    m += 'R';                     // 10 : message code
+    m += flag(toEcr);             // 11 : 1 = send receipt to ECR, 0 = print on terminal
+    m += ticketType;              // 12 : ticket type flag
+    m += "0000000000";            // 13 : reserved (10)
+    return m;                     // 22
+}
+
+std::string Ecr17Protocol::buildStatusMessage(const std::string& terminalId) {
+    std::string m;
+    m += leftPad(terminalId, 8);  // 1  : terminal id
+    m += kReserved;               // 9  : reserved
+    m += 's';                     // 10 : message code (lowercase per spec)
+    return m;                     // 10
+}
+
+std::string Ecr17Protocol::buildReversalMessage(const std::string& terminalId,
+                                                const std::string& cashRegisterId,
+                                                const std::string& stan) {
+    std::string m;
+    m += leftPad(terminalId, 8);      // 1  : terminal id
+    m += kReserved;                   // 9  : reserved
+    m += 'S';                         // 10 : message code
+    m += leftPad(cashRegisterId, 8);  // 11 : cash register id
+    m += leftPad(stan, 6);            // 19 : STAN ("000000" = no check)
+    m += kReserved;                   // 25 : presence of additional GT data
+    m += kReserved;                   // 26 : reserved
+    return m;                         // 26
+}
+
+std::string Ecr17Protocol::buildVasMessage(const std::string& terminalId, const std::string& ecrId,
+                                           const std::string& xmlRequest) {
+    if (xmlRequest.size() > 1024) {
+        throw std::invalid_argument("ECR17: VAS request exceeds 1024 bytes");
+    }
+    std::string m;
+    m += leftPad(terminalId, 8);                       // 1  : terminal id
+    m += kReserved;                                    // 9  : reserved
+    m += 'K';                                          // 10 : message code
+    m += leftPad(ecrId, 8);                            // 11 : ECR identifier
+    m += "000";                                        // 19 : reserved (3)
+    m += kReserved;                                    // 22 : reserved (1)
+    m += leftPad(std::to_string(xmlRequest.size()), 4);// 23 : VAS request length (4)
+    m += xmlRequest;                                   // 27 : VAS request (XML)
+    return m;
+}
+
+std::string Ecr17Protocol::buildAdditionalTagsMessage(const std::string& terminalId,
+                                                      const std::string& tagContent,
+                                                      const std::string& isoField,
+                                                      const std::string& tagNumber) {
+    if (tagContent.empty() || tagContent.size() > 100) {
+        throw std::invalid_argument("ECR17: additional TAG content must be 1..100 chars");
+    }
+    std::string m;
+    m += leftPad(terminalId, 8);       // 1  : terminal id
+    m += kReserved;                    // 9  : reserved
+    m += 'U';                          // 10 : message code
+    m += "000000";                     // 11 : payment type (6) -> standard payment
+    m += leftPad(isoField, 2);         // 17 : ISO field number (e.g. "62")
+    m += rightPad(tagNumber, 8);       // 19 : TAG number, left-justified, blank-filled
+    m += kReserved;                    // 27 : reserved (1)
+    m += "0000";                       // 28 : exclusive TAG index bytemap (none to send to GT)
+    m += "00000";                      // 32 : reserved (5)
+    m += tagContent;                   // 37 : privative TAG content (1..100)
+    m += kFieldSep;                    //      end-of-field (0x1B)
+    return m;
+}
+
+std::string Ecr17Protocol::formatTokenizationTag(bool recurring, const std::string& contractCode) {
+    if (contractCode.empty() || contractCode.size() > 18) {
+        throw std::invalid_argument("ECR17: tokenization contract code must be 1..18 chars");
+    }
+    const std::string service = recurring ? "0REC" : "0COF";
+    return service + "0TRK" + contractCode + "|0FNZ03";
+}
+
+}  // namespace margelo::nitro::ecr17

package/cpp/Ecr17Protocol/Ecr17Protocol.hpp

@@ -0,0 +1,103 @@
+#pragma once
+
+#include <string>
+
+namespace margelo::nitro::ecr17 {
+
+// Builds ECR17 application-message payloads (the bytes that go between STX and
+// ETX). All fields are fixed-width and validated; values that overflow their
+// field throw std::invalid_argument so a malformed frame is never produced.
+//
+// `paymentType` is the single request digit: '0' auto, '1' debit, '2' credit,
+// '3' other. `cardAlreadyPresent` maps to field "start with card already
+// inserted". `receiptText` is the contract/print text (max 128 chars).
+class Ecr17Protocol {
+   public:
+    // --- Payment family (167 bytes): 'P' payment, 'X' extended, 'p' pre-auth ---
+    static std::string buildPaymentMessage(const std::string& terminalId,
+                                           const std::string& cashRegisterId, int amountCents,
+                                           char paymentType = '0', bool cardAlreadyPresent = false,
+                                           bool withAdditionalData = false,
+                                           const std::string& receiptText = "");
+
+    static std::string buildExtendedPaymentMessage(const std::string& terminalId,
+                                                   const std::string& cashRegisterId, int amountCents,
+                                                   char paymentType = '0',
+                                                   bool cardAlreadyPresent = false,
+                                                   bool withAdditionalData = false,
+                                                   const std::string& receiptText = "");
+
+    static std::string buildPreAuthMessage(const std::string& terminalId,
+                                           const std::string& cashRegisterId, int amountCents,
+                                           char paymentType = '0', bool cardAlreadyPresent = false,
+                                           bool withAdditionalData = false,
+                                           const std::string& receiptText = "");
+
+    // --- Pre-auth integration/closure (176 bytes): 'i' incremental, 'c' closure ---
+    static std::string buildIncrementalMessage(const std::string& terminalId,
+                                               const std::string& cashRegisterId, int amountCents,
+                                               const std::string& originalPreAuthCode,
+                                               bool withAdditionalData = false,
+                                               const std::string& receiptText = "");
+
+    static std::string buildPreAuthClosureMessage(const std::string& terminalId,
+                                                  const std::string& cashRegisterId, int amountCents,
+                                                  const std::string& originalPreAuthCode,
+                                                  bool withAdditionalData = false,
+                                                  const std::string& receiptText = "");
+
+    // --- Card verification 'H' (39 bytes) ---
+    static std::string buildCardVerificationMessage(const std::string& terminalId,
+                                                    const std::string& cashRegisterId,
+                                                    char paymentType = '0',
+                                                    bool withAdditionalData = false);
+
+    // --- Session commands (26 bytes): 'C' close, 'T' totals ---
+    static std::string buildCloseSessionMessage(const std::string& terminalId,
+                                                const std::string& cashRegisterId,
+                                                bool withAdditionalData = false);
+
+    static std::string buildTotalsMessage(const std::string& terminalId,
+                                          const std::string& cashRegisterId,
+                                          bool withAdditionalData = false);
+
+    // --- Send last result 'G' (22 bytes) ---
+    static std::string buildSendLastResultMessage(const std::string& terminalId,
+                                                  const std::string& cashRegisterId,
+                                                  bool withAdditionalData = false);
+
+    // --- Enable/disable ECR printing 'E' (11 bytes) ---
+    static std::string buildEnableEcrPrintMessage(const std::string& terminalId, bool enabled);
+
+    // --- Reprint ticket 'R' (22 bytes) ---
+    static std::string buildReprintMessage(const std::string& terminalId, bool toEcr,
+                                           char ticketType = '0');
+
+    // --- Status 's' (10 bytes) ---
+    static std::string buildStatusMessage(const std::string& terminalId);
+
+    // --- Reversal 'S' (26 bytes); stan "000000" = reverse last, no STAN check ---
+    static std::string buildReversalMessage(const std::string& terminalId,
+                                            const std::string& cashRegisterId,
+                                            const std::string& stan = "000000");
+
+    // --- VAS 'K' (variable, length-prefixed XML, max 1024) ---
+    static std::string buildVasMessage(const std::string& terminalId, const std::string& ecrId,
+                                       const std::string& xmlRequest);
+
+    // --- Additional data for GT / tokenization 'U' (variable) ---
+    // `tagContent` is the privative TAG content (1..100 chars), terminated with
+    // 0x1B by this builder. Use formatTokenizationTag() to produce it.
+    static std::string buildAdditionalTagsMessage(const std::string& terminalId,
+                                                  const std::string& tagContent,
+                                                  const std::string& isoField = "62",
+                                                  const std::string& tagNumber = "DF8D01");
+
+    // Formats the TAG 5 content for tokenization (Intesa-style mapping):
+    //   "0COF0TRK<contract>|0FNZ03" (unscheduled/one-click)
+    //   "0REC0TRK<contract>|0FNZ03" (recurring)
+    // `recurring` selects 0REC vs 0COF.
+    static std::string formatTokenizationTag(bool recurring, const std::string& contractCode);
+};
+
+}  // namespace margelo::nitro::ecr17

package/cpp/Ecr17Response/Ecr17Response.cpp

@@ -0,0 +1,155 @@
+#include "Ecr17Response.hpp"
+
+#include <algorithm>
+#include <cctype>
+
+namespace margelo::nitro::ecr17 {
+
+namespace {
+
+// 1-based field extractor. Returns "" if the field starts beyond the payload;
+// clamps the length to whatever bytes are actually present (defensive parsing).
+std::string at(const std::string& p, size_t pos1, size_t len) {
+    if (pos1 == 0 || pos1 > p.size()) {
+        return "";
+    }
+    const size_t i = pos1 - 1;
+    return p.substr(i, std::min(len, p.size() - i));
+}
+
+std::string trimRight(const std::string& s) {
+    const size_t end = s.find_last_not_of(' ');
+    return end == std::string::npos ? std::string() : s.substr(0, end + 1);
+}
+
+// Extracts the value of a Nexi VAS XML param: <p k="KEY">value</p>.
+std::string xmlValue(const std::string& xml, const std::string& key) {
+    const std::string needle = "\"" + key + "\">";
+    const size_t start = xml.find(needle);
+    if (start == std::string::npos) {
+        return "";
+    }
+    const size_t from = start + needle.size();
+    const size_t end = xml.find('<', from);
+    std::string value = xml.substr(from, end == std::string::npos ? std::string::npos : end - from);
+    // trim surrounding whitespace
+    const size_t a = value.find_first_not_of(" \t\r\n");
+    const size_t b = value.find_last_not_of(" \t\r\n");
+    return a == std::string::npos ? std::string() : value.substr(a, b - a + 1);
+}
+
+}  // namespace
+
+Outcome outcomeFromCode(const std::string& code) {
+    if (code == "00") return Outcome::Ok;
+    if (code == "01") return Outcome::Ko;
+    if (code == "05") return Outcome::CardNotPresent;
+    if (code == "09") return Outcome::UnknownTag;
+    return Outcome::Unknown;
+}
+
+PaymentResponse Ecr17Response::parsePayment(const std::string& p) {
+    PaymentResponse r;
+    const std::string code = at(p, 10, 1);  // message code 'E' (plain) or 'V' (DCC)
+    const bool dcc = code == "V";
+
+    r.resultCode = at(p, 11, 2);
+    r.outcome = outcomeFromCode(r.resultCode);
+
+    if (r.outcome == Outcome::Ko) {
+        r.errorDescription = trimRight(at(p, 13, 24));
+    } else {
+        r.pan = at(p, 13, 19);
+        r.transactionType = trimRight(at(p, 32, 3));
+        r.authCode = trimRight(at(p, 35, 6));
+        r.hostDateTime = at(p, 41, 7);
+    }
+
+    // Common to any response.
+    r.cardType = at(p, 48, 1);
+    r.acquirerId = trimRight(at(p, 49, 11));
+    r.stan = at(p, 60, 6);
+    r.onlineId = at(p, 66, 6);
+
+    if (dcc) {
+        r.currency.applied = at(p, 83, 1) == "1";
+        r.currency.rate = at(p, 84, 8);
+        r.currency.currencyCode = trimRight(at(p, 92, 3));
+        r.currency.amount = at(p, 95, 12);
+        r.currency.precision = at(p, 107, 1);
+    }
+    return r;
+}
+
+StatusResponse Ecr17Response::parseStatus(const std::string& p) {
+    StatusResponse r;
+    r.terminalId = at(p, 1, 8);
+    r.dateTimeRaw = at(p, 21, 10);
+    const std::string s = at(p, 31, 1);
+    r.status = (!s.empty() && std::isdigit(static_cast<unsigned char>(s[0]))) ? s[0] - '0' : -1;
+    r.softwareRelease = trimRight(at(p, 32, p.size()));
+    return r;
+}
+
+TotalsResponse Ecr17Response::parseTotals(const std::string& p) {
+    TotalsResponse r;
+    r.resultCode = at(p, 11, 2);
+    r.outcome = outcomeFromCode(r.resultCode);
+    r.posTotal = at(p, 13, 16);
+    return r;
+}
+
+CloseResponse Ecr17Response::parseClose(const std::string& p) {
+    CloseResponse r;
+    r.resultCode = at(p, 11, 2);
+    r.outcome = outcomeFromCode(r.resultCode);
+    if (r.outcome == Outcome::Ok) {
+        r.posTotal = at(p, 13, 16);
+        r.hostTotal = at(p, 29, 16);
+    } else {
+        r.errorDescription = trimRight(at(p, 13, 19));
+        r.actionCode = at(p, 32, 3);
+    }
+    return r;
+}
+
+PreAuthResponse Ecr17Response::parsePreAuth(const std::string& p) {
+    PreAuthResponse r;
+    r.resultCode = at(p, 11, 2);
+    r.outcome = outcomeFromCode(r.resultCode);
+    if (r.outcome == Outcome::Ko) {
+        r.errorDescription = trimRight(at(p, 13, 24));
+        r.actionCode = at(p, 37, 3);
+    } else {
+        r.pan = at(p, 13, 19);
+        r.transactionType = trimRight(at(p, 32, 3));
+        r.authCode = trimRight(at(p, 35, 6));
+        r.preAuthorizedAmount = at(p, 41, 8);
+        r.preAuthCode = at(p, 49, 9);
+        r.actionCode = at(p, 58, 3);
+        r.hostDateTime = at(p, 61, 7);
+    }
+    // In the OK layout preAuthorizedAmount occupies positions 41-48, so position
+    // 48 is the amount's last digit, NOT a card type. Only read cardType for the
+    // KO layout, where that byte is not part of an amount field.
+    if (r.outcome == Outcome::Ko) {
+        r.cardType = at(p, 48, 1);
+    }
+    r.acquirerId = trimRight(at(p, 72, 11));
+    r.stan = at(p, 83, 6);
+    r.onlineId = at(p, 89, 6);
+    return r;
+}
+
+VasResponse Ecr17Response::parseVas(const std::string& p) {
+    VasResponse r;
+    r.moreMessages = at(p, 15, 1) == "1";
+    r.idMessage = at(p, 16, 3);
+    r.rawXml = at(p, 27, p.size());
+    r.responseId = xmlValue(r.rawXml, "RESPID");
+    r.responseMessage = xmlValue(r.rawXml, "RESPMSG");
+    r.orderId = xmlValue(r.rawXml, "ORDER_ID");
+    return r;
+}
+
+}  // namespace margelo::nitro::ecr17

package/cpp/Ecr17Response/Ecr17Response.hpp

@@ -0,0 +1,113 @@
+#pragma once
+
+#include <cstdint>
+#include <string>
+
+// Parsers for ECR17 terminal *response* application messages. They take the
+// application payload (the bytes between STX and ETX, i.e. DecodedPacket.payload)
+// and return plain C++ structs — intentionally independent of Nitro so they can
+// be unit-tested standalone. HybridEcr17Client maps these to the generated Nitro
+// result types. Field offsets follow the spec response tables in docs/.
+//
+// Parsing is defensive: fields beyond the payload length come back empty rather
+// than throwing, so a short/truncated response degrades gracefully.
+
+namespace margelo::nitro::ecr17 {
+
+enum class Outcome {
+    Ok,             // "00"
+    Ko,             // "01"
+    CardNotPresent, // "05"
+    UnknownTag,     // "09"
+    Unknown,        // anything else / missing
+};
+
+Outcome outcomeFromCode(const std::string& code);
+
+// Optional DCC / currency-exchange block (parsed from a 'V'/'v' response).
+// Named DccInfo (not CurrencyExchange) to avoid clashing with the Nitro-generated
+// CurrencyExchange struct in the same namespace.
+struct DccInfo {
+    bool applied = false;
+    std::string rate;          // 8 digits, 4 decimals
+    std::string currencyCode;  // alpha-3
+    std::string amount;        // 12 digits, in transaction currency
+    std::string precision;     // decimals
+};
+
+// Result of a payment-family response ('E' without DCC, 'V' with DCC). Reused
+// for reversal / card verification / pre-auth closure which share the layout.
+struct PaymentResponse {
+    Outcome outcome = Outcome::Unknown;
+    std::string resultCode;       // raw "00"/"01"/"05"/"09"
+    std::string pan;              // positive
+    std::string transactionType;  // positive, raw "ICC"/"MAG"/...
+    std::string authCode;         // positive
+    std::string hostDateTime;     // positive, raw DDDHHMM
+    std::string errorDescription; // negative
+    std::string cardType;         // common, raw "1"/"2"/"3"
+    std::string acquirerId;       // common
+    std::string stan;             // common
+    std::string onlineId;         // common
+    DccInfo currency;             // only when DCC present
+};
+
+struct StatusResponse {
+    std::string terminalId;
+    std::string dateTimeRaw;  // "DDMMYYhhmm"
+    int status = -1;          // 0..6, -1 = unknown/missing
+    std::string softwareRelease;
+};
+
+struct TotalsResponse {
+    Outcome outcome = Outcome::Unknown;
+    std::string resultCode;
+    std::string posTotal;  // 16 digits, cents
+};
+
+struct CloseResponse {
+    Outcome outcome = Outcome::Unknown;
+    std::string resultCode;
+    std::string posTotal;          // positive, 16 digits
+    std::string hostTotal;         // positive, 16 digits
+    std::string errorDescription;  // negative
+    std::string actionCode;        // negative
+};
+
+struct PreAuthResponse {
+    Outcome outcome = Outcome::Unknown;
+    std::string resultCode;
+    std::string pan;
+    std::string transactionType;
+    std::string authCode;
+    std::string preAuthorizedAmount;  // 8 digits, cents
+    std::string preAuthCode;          // 9 digits, unique pre-auth id
+    std::string actionCode;
+    std::string hostDateTime;
+    std::string errorDescription;
+    std::string cardType;
+    std::string acquirerId;
+    std::string stan;
+    std::string onlineId;
+};
+
+struct VasResponse {
+    std::string responseId;       // RESPID parsed from XML ("0" = OK), "" if absent
+    std::string responseMessage;  // RESPMSG
+    std::string orderId;          // ORDER_ID
+    bool moreMessages = false;    // concatenation flag "1"
+    std::string idMessage;        // 3-digit sequence
+    std::string rawXml;           // the XML body of this message
+};
+
+class Ecr17Response {
+   public:
+    static PaymentResponse parsePayment(const std::string& payload);
+    static StatusResponse parseStatus(const std::string& payload);
+    static TotalsResponse parseTotals(const std::string& payload);
+    static CloseResponse parseClose(const std::string& payload);
+    static PreAuthResponse parsePreAuth(const std::string& payload);
+    static VasResponse parseVas(const std::string& payload);
+};
+
+}  // namespace margelo::nitro::ecr17