**momentPay** **Transaction Switch / Middleware** Current System — Feature List Prepared for: RFP 52-2026 System: jpos-main (Java / jPOS Q2 Framework) June 2026 # 1\. System Overview The momentPay Transaction Switch (jpos-main) is the central financial transaction middleware built on the open-source jPOS Q2 framework. Written in Java, it sits between POS terminals and bank acquirers, providing ISO 8583 message parsing, transaction routing, TID/MID mapping, rules-engine evaluation, acquirer translation, reversal management, receipt generation, key exchange, and persistent transaction lifecycle management. The Q2 service container enables hot-deployment and XML-driven service configuration. The switch currently supports two acquirers: YSP and Fiserv, each with their own message format translators and SSL-encrypted socket channels. It exposes two ISO 8583 TCP listeners (port 19000 NCC protocol, port 19001 NAC protocol) to POS terminals. # 2\. Supported Transaction Types ## 2.1 Financial Transactions | | | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Feature** | **Description** | | **Sale** | Real-time online purchase (MTI 0200, DE3=000000). Debits cardholder account. Supports all card entry modes: EMV chip, contactless/NFC, magnetic stripe, and manual key entry. Returns approval code and JSON receipt in DE-63. | | **Sale with Tip** | Sale transaction with an additional tip/gratuity amount included in DE-54. Both base amount and tip are forwarded to the acquirer; receipt displays both amounts. | | **Pre-Authorization** | Places a temporary hold on cardholder funds without completing capture (MTI 0100). Used for hotel/car rental scenarios where the final amount is unknown at time of authorisation. | | **Auth-Completion (Capture)** | Completes a pre-authorization by capturing the actual transaction amount (MTI 0220 with DE3 other than 200000/020000). Forwards as financial advice to the acquirer. | | **Refund** | Credits funds back to cardholder account (MTI 0220, DE3=200000). Treated as an independent transaction — does not require the original transaction to be in the database. Mapped to MTI 0200 for YSP acquirer. | | **Void Sale** | Cancels a previously completed Sale or Refund within the same batch (MTI 0200, DE3=020000). Looks up original transaction by order number or STAN; sends MTI 0220 with DE-90 to the acquirer. | | **Void Pre-Authorization** | Cancels an open pre-authorization before capture (MTI 0200, DE3=020000). Original transaction located and cancelled via acquirer financial advice. | | **Void Auth-Completion** | Cancels a previously captured pre-authorization (MTI 0200, DE3=020000). Original capture transaction reversed at the acquirer. | | **Batch Upload** | Batch data upload (MTI 0320): middleware clones the request, clears sensitive fields (DE-2, DE-14, DE-35, DE-55), and returns RC=00 immediately without a bank call. | | **Batch Close (Settlement)** | Batch close/settlement (MTI 0500): middleware clones the request, sets RC=00, clears DE-63, and returns immediately without a bank call. | ## 2.2 Management Transactions | | | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Feature** | **Description** | | **Logon / Network Echo** | Terminal logon (MTI 0800 with absent/empty DE3): middleware echoes the request immediately without a bank call, confirming the terminal-switch TCP connection is live. | | **TMK Key Exchange** | Terminal Master Key exchange (MTI 0800, DE3=810000). Middleware translates to YSP format (DE3=991380) and sends to bank. Encrypted TMK returned in DE-62, relayed to terminal in DE-63. | | **PIN/IPEK Key Exchange** | PIN Initial PIN Encryption Key exchange (MTI 0800, DE3=811000). Middleware sends DE3=990280 to YSP with DE53 (KSN). IPEK for DUKPT PIN encryption returned to terminal. | | **Logoff** | Terminal logoff (MTI 0820, DE3=910000). Handled by management transaction processor to cleanly close the terminal session. | ## 2.3 Reversal Transactions | | | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Feature** | **Description** | | **Automatic Reversal — Acquirer Timeout** | If the acquirer does not respond within the configured timeout (SocketTimeoutException), the middleware immediately returns DE39=83 to the POS terminal and asynchronously sends MTI 0400 to the acquirer to reverse the transaction. | | **Automatic Reversal — Connection Loss** | If the acquirer returns a null response (connection lost after request was sent), the middleware initiates MTI 0400 reversal to protect the cardholder from an unknown transaction outcome. | | **Automatic Reversal — Database Error** | If a database error occurs after the bank has approved a transaction but before the middleware can persist the result, an automatic reversal is triggered to prevent a double-charge scenario. | | **Startup Orphan Cleanup** | On application startup, the middleware identifies all pos\_temp\_transaction records older than 5 minutes (transactions in-flight when the middleware was last restarted) and initiates reversals for each. | | **POS-Initiated Reversal** | POS terminals may explicitly send MTI 0400 to cancel a transaction whose outcome they are unsure of. Middleware looks up the transaction state and takes the appropriate action. | # 3\. Transaction Routing & Processing | | | | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Feature** | **Description** | | **MTI-Based Message Dispatch** | BeanShell entry script (serversimulator.bsh) dispatches incoming ISO 8583 messages by MTI: 0100/0200/0220/0400/0800 go through TransactionRouter; 0500/0320 are handled inline with immediate responses. | | **Terminal-to-Acquirer TID/MID Mapping** | TransactionRouter looks up the incoming POS Terminal ID (DE-41) in the database, finds the mapped bank TID and MID, and substitutes them before forwarding to the acquirer. Original POS TID/MID are restored in the response to the terminal. | | **Terminal Registration Validation** | Every incoming transaction request is validated against the terminal database. If DE-41 is not registered, DE39=76 is returned immediately without contacting the acquirer. | | **Terminal Busy Guard** | If a terminal already has an active in-progress transaction (record in pos\_temp\_transaction), new requests are rejected with DE39=81 (terminal busy) until the active transaction completes. | | **Pending Reversal Guard** | If a pending reversal exists for a terminal, new financial transaction requests are rejected with DE39=80 until the reversal is resolved. | | **Multi-Acquirer Routing** | JposAcquirerTranslatorFactory selects the correct acquirer translator (YSP or Fiserv) based on the terminal's acquirer configuration. Each acquirer has independent message format translation and SSL channel. | | **Transaction Pre-Processing** | Before the bank call, the middleware performs terminal state checks, clears stale reversals and temporary transactions, and creates a pos\_temp\_transaction record for the in-flight transaction. | | **Transaction Post-Processing** | After the bank response, approved transactions are promoted from pos\_temp\_transaction to pos\_transaction; declined transactions move to pos\_failed\_transaction. Partial approval (DE39=10 or 11) is treated as success. | | **Acquirer Translator Abstraction** | JposAcquirerTranslator interface provides toMessage() (POS→acquirer format) and fromMessage() (acquirer→POS format) methods. New acquirer integrations can be added by implementing this interface. | | **TPDU Header Handling** | YSP acquirer communication requires a TPDU (Transaction Protocol Data Unit) prefix on each ISO 8583 message. YspChannel builds and strips TPDU headers transparently. | | **Response Code Normalisation** | AcquirerResponse mapping table normalises acquirer-specific response codes to standard ISO 8583 DE-39 codes returned to the POS terminal. | # 4\. ISO 8583 Protocol Support | | | | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Feature** | **Description** | | **Full ISO 8583 Message Handling** | ISOMsg class holds all fields (DE-2 through DE-128). Double-bitmap support for extended field range. Field presence indicated by primary and extended bitmaps. | | **Multiple Field Encodings** | Support for all ISO 8583 field encoding types: BCD (Binary-Coded Decimal), ASCII, EBCDIC, Binary, and Hex. Corresponding interpreters (AsciiInterpreter, BCDInterpreter, BinaryInterpreter, HEXInterpreter) applied per field. | | **Variable-Length Field Prefixers** | LLVAR (2-digit length prefix), LLLVAR (3-digit length prefix), and LLLLLVAR formats supported for variable-length fields (card number, EMV data, private data, etc.). | | **GenericPackager** | XML-defined packager configuration (GenericPackager) for each acquirer's field layout; no hardcoded field definitions — adding or modifying fields requires only XML changes. | | **NCC Channel Support** | NCCChannel (Network Control Centre) ISO 8583 framing on port 19000 for POS terminal communication (standard framing with 2-byte length prefix). | | **NAC Channel Support** | NACChannel (Network Access Controller) ISO 8583 framing on port 19001 as an alternative POS terminal communication channel. | | **Non-SSL Channel** | 13\_non\_ssl.xml deploys a non-SSL channel for internal testing and simulator connectivity without certificate requirements. | | **SSL/TLS Channel Encryption** | All acquirer-facing channels (YspChannel, FiservChannel) use SSL/TLS sockets with configurable keystore, truststore, and client certificate authentication for secure bank communication. | | **Field 55 — EMV Data Passthrough** | EMV TLV-encoded ICC data (DE-55) from the POS terminal is forwarded to the acquirer unchanged. Issuer script and EMV response data returned by the acquirer in DE-55 are passed back to the terminal. | | **Field 52 / 53 — PIN Security** | PIN block (DE-52) and DUKPT Key Serial Number (DE-53, 20-digit KSN) are forwarded from POS to acquirer unchanged. PIN data is never logged or stored at any point in the middleware. | | **Field 90 — Original Data Elements** | Reversal and void messages include DE-90 (Original Data Elements) containing the original MTI, STAN, date, and time in BCD F42 format to uniquely identify the transaction being reversed. | | **Field 60 — Bank Transaction Details** | Responses include DE-60 with a JSON payload containing bank-side transaction details: bank STAN, bank TID/MID, RRN, batch number, date, time, response code, and response message. | # 5\. Card Entry Mode Support | | | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Feature** | **Description** | | **EMV Chip (Contact)** | DE22=051: Full EMV contact chip card processing. EMV TLV data in DE-55 forwarded to acquirer for online authorisation. Issuer scripts returned via DE-55 to the terminal. | | **Contactless / NFC** | DE22=071: Contactless EMV card and mobile wallet transactions (Tap-to-Pay). Card scheme identified from EMV AID tag 84 in DE-55 for receipt display. | | **Magnetic Stripe** | DE22=090: Track 2 data in DE-35 for legacy magnetic stripe card acceptance. Supported as fallback mode. | | **Magnetic Stripe with PIN** | DE22=021: Magnetic stripe combined with online PIN entry. DE-52 PIN block and DE-53 KSN present. | | **Manual Key Entry** | DE22=011: Manual card number (PAN) and expiry date entry for card-not-present or imprinter fallback. No Track 2 data. | | **Chip Fallback to Swipe** | DE22=800: Fallback entry mode when chip card reading fails and the terminal falls back to magnetic stripe reading. | # 6\. Business Rules Engine Integration | | | | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Feature** | **Description** | | **Per-Transaction Rules Evaluation** | Before every financial transaction is forwarded to the acquirer, the middleware makes an HTTP POST call to the external rules engine with transaction metadata (TID, MID, amount, STAN, currency). | | **Allow / Decline Decision** | If the rules engine returns RULES\_DECISION=DECLINE, the middleware rejects the transaction immediately without contacting the bank and returns a declined response to the POS terminal. | | **Merchant Metadata Retrieval** | Rules engine response provides merchant name, merchant address, merchant logo URL, receipt footer message, and footer description — all used in receipt generation. | | **Receipt Generation Flag** | RULES\_MODEL\_NAME\_ENABLED flag from the rules engine controls whether a JSON receipt is generated and placed in DE-63 for each transaction. | | **Fail-Open Mode** | If the rules engine is unreachable (timeout or error), the middleware defaults to ALLOW (fail-open), ensuring transactions continue processing without disruption. | | **Configurable Timeout & Retry** | Rules engine call timeout is 500ms with 1 retry, preventing slow rules engine responses from delaying transaction processing beyond acceptable limits. | # 7\. Receipt Generation | | | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Feature** | **Description** | | **JSON Receipt in DE-63** | ReceiptGenerator produces a structured JSON document placed in DE-63 of the response, containing all data the POS terminal needs to print a complete receipt without additional parsing. | | **Merchant Logo** | Receipt header includes a logo image element with URL sourced from the rules engine response (RULES\_HEADER\_LOGO) or falls back to a configurable default logo URL. | | **Merchant Name & Address** | Merchant name and address from the rules engine response are word-wrapped to 38 characters per line and included in the receipt header. | | **TID / MID Display** | Receipt shows Bank TID and Bank MID (from BankTerminalId/BankMerchantId metadata). For declined transactions before bank response, falls back to device-provided TID/MID. | | **Date / Time** | Transaction date (from DE-13, MMDD format) and time (from DE-12, HHMMSS format) displayed as a dual field on the receipt. | | **Card Scheme & Entry Mode** | Card scheme (Visa, Mastercard, UnionPay, etc.) identified from EMV AID tag 84 or PAN BIN range. Entry mode label (CHIP, CONTACTLESS, SWIPE, MANUAL) derived from DE-22. | | **Transaction Type** | Transaction type displayed in bold: Sale, Sale-Tip, Pre-Auth, Auth-Completion, Refund, Void — derived from MTI + DE-3 combination. | | **Masked PAN** | Cardholder PAN displayed as \*\*\*\*\*\*\*\*\*\*\*\*NNNN (last 4 digits only) on the receipt for PCI DSS compliance. | | **Batch Number / Receipt Number** | Dual field showing batch number (from BankBatchNumber metadata) and receipt number (STAN from bank, falling back to DE-11). | | **Amount Display** | Transaction amount displayed centered and bold in large font (AED xx.xx format) — the most visually prominent element on the receipt. | | **Approval Code** | For approved transactions, displays 'APPROVAL CODE: NNNNNN' and an account message ('PLEASE DEBIT MY ACCOUNT' for debits, 'PLEASE CREDIT MY ACCOUNT' for refunds). | | **CVM (Cardholder Verification)** | Cardholder verification method displayed: 'PIN Verified' (when DE-52 present), 'Signature Required' (from EMV tag 9F34 CVM Results), or 'No CVM'. Optional signature line for physical signature. | | **EMV Marker** | For approved chip card transactions, an EMV marker element is included in the receipt, parsed from TLV tags (AID, TVR, TSI, CID, AC from DE-55). | | **App Version Footer** | Application version from DE-56 JSON (Version key) displayed in the receipt footer along with footer message and description from rules engine. | | **Declined Receipt** | When RULES\_MODEL\_NAME\_ENABLED=true and the transaction is declined (by acquirer or rules engine), a declined receipt is still generated with status 'MW - DECLINED- Tran not Permitted'. | | **No Receipt for Reversals/Key Exchange** | Receipt generation is explicitly skipped for reversal (MTI 0400) and key exchange (MTI 0800) messages — DE-63 is cleared in these responses. | # 8\. Reversal Management | | | | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Feature** | **Description** | | **Automatic Reversal Initiation** | Middleware automatically initiates MTI 0400 reversal to the acquirer in four scenarios: acquirer timeout (SocketTimeoutException), null acquirer response, database error post-bank-approval, and orphaned temp transactions on startup. | | **Immediate POS Response on Timeout** | When an auto-reversal is triggered due to acquirer timeout, DE39=83 (ACQUIRER\_TIMED\_OUT) is returned to the POS terminal immediately. The reversal to the bank proceeds asynchronously and does not block the terminal. | | **Reversal Status Lifecycle** | Each reversal is tracked through a complete status lifecycle: PENDING → SENT → COMPLETED (success) or FAILED → RETRY\_SCHEDULED → (repeat) or MAX\_RETRIES\_EXCEEDED → MANUAL\_REVIEW. | | **Retry Logic with Configurable Limits** | Failed reversals are automatically retried up to 3 times with a 60-second interval between attempts. All parameters (max retries, delay, timeout) are configurable. | | **MANUAL\_REVIEW Escalation** | After 3 failed reversal attempts, status is set to MAX\_RETRIES\_EXCEEDED / MANUAL\_REVIEW and a CRITICAL alert is logged for operations team intervention. No further automatic retries are scheduled. | | **Idempotent Reversal Processing** | If a POS terminal sends a duplicate MTI 0400 for an already-completed reversal, the middleware returns DE39=00 immediately without sending another message to the acquirer. | | **POS-Initiated Reversal State Machine** | For POS-initiated reversals, middleware applies a 5-state lookup (pos\_transaction\_reversal → pos\_failed\_transaction → pos\_temp\_transaction → pos\_transaction → not found) to determine the correct action. | | **Reversal for Declined Original** | If the POS sends MTI 0400 for a transaction that was already declined (in pos\_failed\_transaction), the middleware returns DE39=00 immediately — no funds were debited, so no bank reversal is needed. | | **Atomic Reversal Cleanup** | When a reversal succeeds, the pos\_temp\_transaction record is deleted and the pos\_transaction\_reversal status is updated to COMPLETED atomically in a single database transaction to prevent partial state. | | **Orphaned Transaction Cleanup on Startup** | On startup (@PostConstruct), the middleware scans for pos\_temp\_transaction records older than 5 minutes and initiates reversals for each — recovering from crashes or restarts without leaving unresolved transactions. | | **DE-90 Original Data Elements** | Reversal messages include DE-90 in BCD F42 format containing: original MTI (4 digits), original STAN (6 digits), original date (4 digits), original time (6 digits), and 11 zero-pad digits per ISO 8583 spec. | | **Reversal Metrics & Monitoring** | ReversalMetrics service tracks reversal counts, success/failure rates, and CRITICAL alerts for operations dashboards; stale terminal states trigger alerts before new transactions are accepted. | # 9\. Security & Key Management | | | | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Feature** | **Description** | | **DUKPT PIN Encryption** | Derived Unique Key Per Transaction (DUKPT) PIN encryption supported end-to-end. POS terminal sends DE-52 (encrypted PIN block) and DE-53 (20-digit KSN) which are forwarded unchanged to the acquirer. | | **Terminal Master Key (TMK) Exchange** | Middleware facilitates TMK download from the bank acquirer to the POS terminal via MTI 0800 (DE3=810000). The encrypted TMK key block is delivered via DE-62/DE-63 to the terminal. | | **PIN/IPEK Key Exchange** | Middleware facilitates PIN Initial PIN Encryption Key (IPEK) download from the bank to the POS terminal via MTI 0800 (DE3=811000). IPEK enables DUKPT PIN encryption on the terminal. | | **SSL/TLS Acquirer Connections** | All connections to acquirer banks (YSP, Fiserv) are encrypted using TLS with configurable keystore and truststore for mutual certificate authentication. | | **PAN Masking in Logs** | PAN (DE-2) is masked in all log output (476134XXXXXX0047 format) so no full card numbers appear in log files, meeting PCI DSS logging requirements. | | **PIN Data Non-Persistence** | PIN block (DE-52) is never stored in any database table or log file. It is forwarded to the acquirer and discarded immediately after the transaction completes. | | **Encrypted PAN Storage for Reversals** | For automatic reversals, the original PAN and expiry date are stored in encrypted form in pos\_transaction\_reversal and decrypted only when constructing the reversal MTI 0400 message. | | **Cryptographic Security Module (SM) Interface** | SMAdapter interface provides hardware security module (HSM) abstraction for cryptographic operations including DES key management, PIN encryption, MAC calculation, and ARQC verification via BouncyCastle. | | **Key Scheme Support** | Support for multiple key schemes (SecureDESKey, SecureKeyBlock) and key exportability levels via the security package, aligned with PCI HSM standards. | # 10\. Transaction Lifecycle & Database | | | | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Feature** | **Description** | | **pos\_temp\_transaction (In-Flight)** | Every financial transaction creates a pos\_temp\_transaction record before contacting the acquirer. This record is the authoritative indicator of a transaction in progress and drives terminal busy / reversal checks. | | **pos\_transaction (Approved)** | On acquirer approval (DE39=00, 10, or 11), the temp record is promoted to pos\_transaction with all transaction details, bank response codes, batch number, and closure status (default: OPEN). | | **pos\_failed\_transaction (Declined)** | On acquirer decline or rules engine decline, the temp record is moved to pos\_failed\_transaction recording the failure reason, response code, and original request data. | | **pos\_transaction\_reversal (Reversal Tracking)** | All reversal records tracked in pos\_transaction\_reversal with: original STAN, reason for reversal, retry count, status lifecycle, timestamps, and encrypted original card data for re-use in reversal messages. | | **STAN Counter Management** | Per-acquirer-terminal STAN (System Trace Audit Number) counters maintained in acquirer\_terminal\_stan table with atomic increment to ensure unique, sequential STANs for each acquirer terminal. | | **Batch Number Management** | Per-acquirer-terminal batch numbers maintained in acquirer\_terminal\_batch table. Batch number included in DE-62 of requests and de-tracked in pos\_transaction for settlement reconciliation. | | **Terminal State Table** | acquirer\_terminal\_state tracks the current state of each terminal (idle, busy, reversal-pending) for concurrent request handling and terminal-busy enforcement. | | **ISO Message Field Audit Trail** | pos\_terminal\_data stores every ISO 8583 message's key fields (DE-41, DE-42, DE-4, DE-11, DE-39, etc.) for forensic audit, chargeback research, and regulatory reporting. | | **Acquirer Response Code Mapping** | acquirer\_response table maps acquirer-specific raw response codes to standard ISO 8583 DE-39 response codes and human-readable messages returned to the terminal. | | **Parent Transaction Linking** | parent\_txn\_id soft foreign key on all three transaction tables links a Void or Reversal transaction back to the original Sale it references, enabling full transaction chain reconstruction. | | **Transaction Closure Status** | pos\_transaction.closure\_status field (default OPEN) tracks whether a transaction has been included in a settlement batch, enabling unsettled transaction reporting. | | **Flyway Database Migrations** | All schema changes managed via Flyway SQL migration scripts in db/migration/. Migration history is versioned and applied automatically on startup, ensuring consistent schema across environments. | # 11\. Q2 Service Container | | | | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Feature** | **Description** | | **Q2 XML Service Deployment** | Q2 container scans the deploy/ directory for XML service descriptors at startup. Services are deployed by placing, and undeployed by removing, XML files — enabling zero-downtime service changes. | | **QServer — NCC Channel (Port 19000)** | Primary POS terminal listener on TCP port 19000 using NCCChannel (2-byte length-prefix framing). Accepts connections from Newland/Morefun terminal devices. | | **QServer — NAC Channel (Port 19001)** | Secondary POS terminal listener on TCP port 19001 using NACChannel framing, supporting terminals using the alternative NAC protocol variant. | | **Non-SSL Development Channel** | Additional non-SSL listener (13\_non\_ssl.xml) for internal testing and simulator connectivity without certificate overhead. | | **YSP Connection Multiplexer (MUX)** | 30\_ysp\_mux.xml deploys a connection multiplexer for the YSP acquirer channel, managing a pool of persistent SSL connections and routing outbound messages efficiently. | | **YSP Channel Worker** | 31\_ysp\_channel\_worker.xml runs the background worker thread managing the lifecycle of YSP acquirer connections, reconnection on drop, and keepalive messaging. | | **YSP Network Management** | 50\_ysp\_network\_mgmt.xml handles YSP network management messages (echo/heartbeat to the acquirer) to keep the SSL connection alive and detect link-level failures. | | **System Monitor** | 99\_sysmon.xml deploys the Q2 system monitor providing runtime health metrics: memory usage, thread count, transaction rate, and service status via the Q2 management interface. | | **Logger Service** | 00\_logger.xml configures the centralized Q2 logging service with configurable log channels (file, console, rotated files). All ISO 8583 messages logged with PAN masking. | | **BeanShell Server** | 11\_bshserver.xml deploys the BeanShell scripting server and the serversimulator.bsh entry-point script, enabling live script updates without service restart. | | **Q2 CLI Mode** | Interactive Q2 command-line interface (./bin/q2 --cli) for runtime service management, log viewing, and diagnostic commands without requiring system restart. | | **Hot-Deploy / Undeploy** | Individual services can be deployed or undeployed at runtime by adding/removing XML descriptor files from the deploy/ directory, enabling rolling updates with minimal downtime. | # 12\. Acquirer Integrations | | | | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Feature** | **Description** | | **YSP Acquirer (Primary)** | Full YSP acquirer integration via JposYspTranslator: toMessage() maps POS ISO 8583 fields to YSP-specific format including processing code remapping, TPDU construction, DE-24 NII setting, and RRN generation. | | **Fiserv Acquirer** | Fiserv acquirer integration via JposFiservTranslator: translates POS messages to Fiserv's proprietary ISO 8583 variant and maps responses back to the standard format returned to terminals. | | **Acquirer Translator Factory** | JposAcquirerTranslatorFactory selects the correct translator at runtime based on the acquirer\_terminal.acquirer\_id mapping — new acquirers can be onboarded by adding a new translator and XML config. | | **Per-Acquirer SSL Configuration** | Each acquirer connection record (acquirer\_connection) stores its own IP, port, SSL flag, keystore, truststore, and TPDU prefix — enabling independent SSL certificate management per acquirer. | | **YSP Processing Code Remapping** | YSP uses different processing codes than the POS standard. JposYspTranslator remaps: Sale 000000 → YSP codes, Refund 200000 → 0200 MTI, Void 020000 → 0220+DE90, Key Exchange 810000/811000 → 991380/990280. | | **RRN Generation** | Retrieval Reference Number (DE-37) generated by the middleware in YDDDHHSSSSSS format (year + day-of-year + hour + STAN) ensuring globally unique transaction references for bank reconciliation. | # 13\. Monitoring, Diagnostics & Operations | | | | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Feature** | **Description** | | **Transaction Rate Monitoring** | Q2 system monitor tracks real-time transaction throughput (transactions per second) and reports via the monitoring interface for operations team visibility. | | **Reversal Metrics** | ReversalMetrics service tracks: total reversals initiated, reversals by trigger type (timeout, connection loss, DB error, startup), success rate, average retry count, and pending MANUAL\_REVIEW count. | | **CRITICAL Alert Logging** | Operations team is alerted via CRITICAL log entries when reversals exceed maximum retries, when terminal state is inconsistent, and when database errors occur during transaction completion. | | **Terminal Busy Detection** | Stale temp transactions (older than 45 seconds) trigger automatic cleanup and terminal unblock, with alerting if the cleanup itself encounters errors. | | **Bank Response Latency Logging** | Bank request duration is logged in milliseconds for every acquirer call, enabling latency trend analysis and SLA monitoring. | | **Q2 NameRegistrar** | Q2 NameRegistrar provides a global service registry for locating services (channels, MUXes, processors) by name at runtime, enabling dynamic service wiring without hard-coded dependencies. | | **BeanShell Diagnostic Scripts** | BeanShell scripting server (11\_bshserver.xml) allows operations staff to run diagnostic Groovy/BSH scripts against live services — query in-flight transactions, inspect registrar, force close connections. | | **Distribution Packaging** | Gradle tasks (./gradlew dist, ./gradlew zip) produce deployment archives (jpos-{VERSION}.tar.gz) containing all JARs, configuration, and deploy/ descriptors ready for Linux server deployment. | | **Release Packaging Automation** | Release skill produces full and upgrade tar.gz packages: full package (all files + full Flyway schema) for fresh installs; upgrade package (changed files + new migration scripts only) for in-place upgrades. | # 14\. Feature Summary The table below provides a high-level count of documented features by domain area. | | | | | -------------------------------------------- | ----------------- | --------- | | **Domain** | **Feature Count** | **Notes** | | **2. Supported Transaction Types** | 19 | | | **3. Transaction Routing & Processing** | 11 | | | **4. ISO 8583 Protocol Support** | 12 | | | **5. Card Entry Mode Support** | 6 | | | **6. Rules Engine Integration** | 6 | | | **7. Receipt Generation** | 16 | | | **8. Reversal Management** | 12 | | | **9. Security & Key Management** | 9 | | | **10. Transaction Lifecycle & Database** | 12 | | | **11. Q2 Service Container** | 12 | | | **12. Acquirer Integrations** | 6 | | | **13. Monitoring, Diagnostics & Operations** | 9 | | | **TOTAL** | **130** | |