naps_flutter 2.0.0

A Flutter SDK for integrating NAPS SUNMI P2 payment terminals using the M2M TLV protocol via TCP/IP and Serial.

2.0.0

Conformance pass against the NAPS PAY SUNMI P2 M2M TLV v1.1 specification. Contains breaking API changes; see README for the new shapes.

Wire format (correctness)

• Tag 010 is no longer truncated at 999 bytes. LENGTH is a 3-character field, so the terminal saturates it and keeps writing. Every receipt was losing its last few lines. The true extent is now recovered from the DP structure.
• DP is parsed by declared length, not by splitting on *. Line text legitimately contains asterisks (masked PANs, rules of stars); splitting first fabricated one segment per asterisk and destroyed the real line.
• TLV and DP LENGTH count characters (runes). Confirmed against the NAPS v1.1 specification: LENGTH is a character count for the transmitted VALUE across all TLV tags and DP sub-tags. Counting bytes caused readers to stop short on non-ASCII characters, truncating French receipts at accented lines (e.g., N° Commerçant, Opération réussie).
• Fields after the receipt DP terminator are captured. The terminal can place tags—such as response code 013 (CR) or timestamps (014, 015)—after the receipt. The parser now consumes trailing tags rather than halting at ?, ensuring approved payments with trailing CRs are correctly recognized.
• Partial frames are never delivered. A NAPS frame carries no length prefix or delimiter. Completion is decided by the message envelope, the DP terminator, and detection of the next frame's tag 001 or settle window.
• Raw socket chunks are no longer UTF-8 decoded. A multi-byte character split across a TCP segment threw and tore down the connection mid-transaction.
• Back-to-back frames in one buffer no longer merge.
• Receipt line text is no longer trimmed; padding is how the terminal aligns a 24-column line.

Transaction safety

• NapsResultSource.approvedNotConfirmed — an approval whose confirmation did not complete now returns the full payment context (NS, STAN, amount, masked PAN, expiry, merchant receipt) instead of a bare error. A non-000 TM 102 is reported here too, rather than as a plain decline.
• Strict NS correlation restored. Validates that the terminal echoes the request sequence number (NS) per NAPS specification sections III.2.3.1–III.2.3.6.
• NapsSequenceStore — NS is now supplied by an injectable, persistable store. Previously an SDK constructed per transaction reissued the same NS every time.
• onApproved is bounded by approvedCallbackTimeout and its errors are reported on the result rather than thrown, so nothing a host does in the callback can delay or fail the confirmation of an approved card.
• confirmationElapsed and confirmationWindowExceeded expose the terminal's 40-second budget.
• NapsFailureReason replaces string-matching on exception text.

Diagnostics

• NapsFrameLog — connections emit the actual wire frame, as hex and as a TLV summary, with tags 007 (NCAR) and 016 (NPRT) masked before the callback can see them.
• NapsFrameLog.bufferedAfter — reports unconsumed buffer bytes when a frame is dispatched, distinguishing parser issues from network delays.
• Synthetic SDK conditions no longer masquerade as terminal response codes; a protocol mismatch reports sdkError with an empty CR.

API changes

• networkTest(), getDuplicate(), getTotals(), getPrintInfo(), referencingOrder() and resetEpt() return NapsOperationResult instead of bool/null.
• NapsConnection gains transportDescription; connections take onFrame.
• NapsReceipt.parseBytes is the primary parser; parse(String) delegates.
• TlvElement exposes byteLength alongside length (character count).
• NapsSdk validates NCAI and exposes NapsSdk.posIdIssue for setup screens.
• Serial baud rate is configurable.

1.0.0

• Initial stable release of the NAPS Flutter SDK for SUNMI P2.
• Full support for TCP/IP and Serial connectivity.
• Implementation of M2M TLV protocol (Payment, Confirmation, Cancellation, Duplicates, Totals).