Using the ECR Simulator Tool

Overview

The Electronic Cash Register (ECR) Simulator Tool, also known as remote-serial-pay.py, is a Python-based test utility used to simulate ECR transactions between your Electronic Cash Register (ECR) and Maya Terminals.

It allows developers to test and validate ECR integrations without building a complete ECR plugin, making it ideal for early development, debugging, and verifying transaction flows.

This tool is compatible with both Sunmi P2 and PAX A920 terminals and supports standard transaction types such as CHECK, SALE, VOID, and SETTLE.

The ECR Simulator is intended only for testing and simulation. The actual production ECR Plugin used in your stores must be developed and maintained by your team.

By the end of this guide, you’ll be able to:

• Set up the ECR Simulator Tool on your host computer
• Execute test transactions with Maya Terminals
• Understand supported parameters and commands
• Troubleshoot basic simulator issues

Before You Begin

Obtain the Simulator Script

The ECR Simulator Tool (remote-serial-pay.py) is included in the ECR Integration Kit provided after successful onboarding with Maya. You can find it in the /ECR Tools directory of your kit.

If you don’t have the latest integration kit:

• Contact your Maya Relationship Manager, or
• Email [email protected] to request access.

Setting up the Simulator Tool

Step 1: Install Python

The ECR Simulator Tool requires Python 3.6 or higher. Install Python depending on your operating system.

Windows

• Download the latest Python installer from python.org/downloads.
• During setup, check “Add Python to PATH” before clicking Install Now.
• Verify installation by running python --version or py --version in the command line.

macOS

You can install Python using Homebrew or the official installer:

• Option 1 (Recommended): Install via Homebrew by running brew install python in the command line
• Option 2: Download and install Python from python.org/downloads

Verify installation by running python3 --version in the command line.

Linux

Install Python using your system’s package manager or Homebrew for Linux.

• Option 1: Using APT (Ubuntu/Debian)

sudo apt update
sudo apt install python3 python3-pip

• Option 2: Using Homebrew (Linuxbrew):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install python

Verify installation by running python3 --version in the command line.

Step 2: Install Dependencies

The simulator requires the following Python libraries:

• pycrc (or pythoncrc) – for checksum generation
• pyserial – for serial communication

Install both using pip install pythoncrc pyserial

Using the ECR Simulator Tool

Know the Simulator Parameters

Basic Parameters

Sample Run:

python remote-serial-pay.py -t /dev/cu.usbmodem1423 -c SALE --amount 1000 --debug --subscribe

In this command:

• -t /dev/cu.usbmodem1423 - specifies the target serial port used to connect to the terminal.
• -c SALE - defines the transaction type to be executed. In this case, a SALE transaction.
• --amount 1000 - sets the transaction amount to 1000 (in the terminal’s default currency).
• --debug - enables debug mode, allowing detailed logs and request/response traces for troubleshooting.
• --subscribe - activates live event monitoring, displaying real-time updates from the Terminal (e.g., transaction status or ECR events).

Tip: Use --debug and --subscribe during testing to validate communication between the ECR and terminal in real time. Disable these flags in production to reduce log noise.

Utility parameters

• -h or --help: displays help info
  Python

  python remote-serial-pay.py --help
  

• --list: Lists all available serial ports in the Host PC
  Python

  python remote-serial-pay.py --list
  

Supported Transaction Types (-c)

CHECK

• Used to verify connectivity between the host and the terminal
• ECR app responds with ACK

Sample Syntax:

python remote-serial-pay.py -t COM11 -c CHECK

SALE

• Use this command to simulate a sale transaction
• Use the --amount parameter to define the test transaction amount
• Optional:
  • Add --subscribe to monitor the transaction
  • Add -d or --debug to enable debug mode

Sample Syntax (Basic):

python remote-serial-pay.py -t /dev/cu.usbmodem1423 -c SALE --amount 1000 --debug

Sample Syntax (with Monitoring):

python remote-serial-pay.py -t /dev/cu.usbmodem1423 -c SALE --amount 1000 --debug --subscribe

Sample Response:

REQUEST: {
 "dataType": "trans",
 "data": {
 "amt": "1000",
 "cmd": "sale",
 "detail": "Y"
 }
}
RAW REQUEST
0000004E7B226461746154797065223A20227472616E73222C202264617461223A207B22616D74223A2022313030302
22C2022636D64223A202273616C65222C202264657461696C223A202259227D7DCE4A
RAW RESPONSE 000000147B226461746154797065223A2261636B227DFA22
RESPONSE: {
 "dataType": "ack"
}
RAW RESPONSE
000001E97B2264617461223A7B22616964223A224130303030303030303331303130222C22617070223A22564953412
054455354222C22617463223A2230304532222C2261757468436F6465223A22303239323233222C2262617463684E6F
223A22303030303032222C226361726454797065223A2256495341222C22656E7465724D6F6465223A2254222C22656
E7465724D6F6465436F6465223A22303731222C226D65726368616E744964223A22454653313030303031313439222C
226E6F5369676E223A2259222C2270616E223A222A2A2A2A2A2A2A2A2A2A2A2A30303638222C227265666572656E636
54E6F223A22383332353036303830313330222C22726573706F6E7365436F6465223A223030222C22726573706F6E73
6554657874223A2254786E204163636570746564222C22737461747573223A2241222C22737474223A2259222C22746
5726D696E616C4964223A223132333435363738222C22747369223A2230303030222C22747672223A22303030303030
30303030222C2274786E44617465223A223230313831313231222C2274786E4964223A22303030303230222C2274786
E54696D65223A2231343038222C2274786E54797065223A2273616C65222C22616D74223A2231303030227D2C226461
746154797065223A227472616E73227D73C0

When live event monitoring is set, or the --subscribe flag is added during run, you will receive a REQUEST payload during transaction updates:

REQUEST {
 "data": {
 "aid": "A0000000031010",
 "app": "VISA TEST",
 "atc": "00E2",
 "authCode": "029223",
 "batchNo": "000002",
 "cardType": "VISA",
 "enterMode": "T",
 "enterModeCode": "071",
 "merchantId": "EFS100001149",
 "noSign": "Y",
 "pan": "************0068",
 "referenceNo": "832506080130",
 "responseCode": "00",
 "responseText": "Txn Accepted",
 "status": "A",
 "stt": "Y",
 "terminalId": "12345678",
 "tsi": "0000",
 "tvr": "0000000000",
 "txnDate": "20181121",
 "txnId": "000020",
 "txnTime": "1408",
 "txnType": "sale",
 "amt": "1000"
 },
 "dataType": "trans"
}
RESPONSE {
 "dataType": "ACK"
}
RAW RESPONSE 000000477B2264617461223A7B2274786E54797065223A2273616C65222C22737461747573223A22494E5055545F43415244227D2C226461746154797065223A22737461747573227D3172
STATUS {
  "data": {
    "txnType": "sale",
    "status": "INPUT_CARD"
  },
  "dataType": "status"
}
RAW RESPONSE 000000457B2264617461223A7B2274786E54797065223A2273616C65222C22737461747573223A22454D565F50524F43227D2C226461746154797065223A22737461747573227D7773
STATUS {
  "data": {
    "txnType": "sale",
    "status": "EMV_PROC"
  },
  "dataType": "status"
}
RAW RESPONSE 0000004A7B2264617461223A7B2274786E54797065223A2273616C65222C22737461747573223A225052494E545F52454345495054227D2C226461746154797065223A22737461747573227D48C3
STATUS {
  "data": {
    "txnType": "sale",
    "status": "PRINT_RECEIPT"
  },
  "dataType": "status"
}

VOID

• Use this command to simulate voiding a transaction
• Use the --txnId parameter to specify the transaction ID (or the txnId value on the successful SALE response)
• Optional: Add -d or --debug to enable debug mode

Sample Syntax:

python remote-serial-pay.py -t /dev/cu.usbmodem1423 --debug -c VOID --txnId 22

Sample Response:

REQUEST: {
 "dataType": "trans",
 "data": {
 "txnId": "22",
 "cmd": "void"
 }
}
RAW REQUEST
0000003F7B226461746154797065223A20227472616E73222C202264617461223A207B2274786E4964223A202232322
22C2022636D64223A2022766F6964227D7DEF03
RAW RESPONSE 000000147B226461746154797065223A2261636B227DFA22
RESPONSE: {
 "dataType": "ack"
}

SETTLE

• Use this command to simulate a settlement of transactions
• Optional: Add -d or --debug to enable debug mode

Sample Syntax:

python remote-serial-pay.py -t /dev/cu.usbmodem1423 --debug -c SETTLE

Sample Response:

REQUEST: {
 "dataType": "trans",
 "data": {
 "cmd": "settle"
 }
}
RAW REQUEST
000000327B226461746154797065223A20227472616E73222C202264617461223A207B22636D64223A2022736574746
C65227D7DDF62
RAW RESPONSE
000000967B2264617461223A7B2262617463684E6F223A22303030303033222C22726573706F6E7365436F6465223A2
23030222C22726573706F6E736554657874223A2254786E204163636570746564222C22737461747573223A2241222C
2274786E54797065223A22736574746C65222C22626174636855706C6F6164223A224E227D2C2264617461547970652
23A227472616E73227DF56A
RESPONSE: {
 "data": {
 "batchNo": "000003",
 "responseCode": "00",
 "responseText": "Txn Accepted",
 "status": "A",
 "txnType": "settle",
 "batchUpload": "N"
 },
 "dataType": "trans"
}

Troubleshooting the ECR Simulator Tool

Before escalating or deep-diving into logs, perform these baseline checks:

1. Verify Python Dependencies

• For CRC errors, reinstall the dependency using pip install pythoncrc

2. Verify Terminal Connectivity

• Confirm the Sunmi or PAX terminal is connected via USB or network.
• Check if the terminal appears in Device Manager (for COM-based setups).
• If not detected, reinstall drivers or reconnect the device.
• Refer to Preparation for ECR Integration

3. Try Transacting Directly to the Maya Terminal

• Check that the terminal is online and peripherals are connected.
• Try to transact directly to the terminal, without using the ECR Simulator tool

Refer also to Understanding Errors in ECR Integration page for troubleshooting ECR Integration.

FAQs

Q: Can I use the simulator in production?

A: No. It’s strictly for testing and validation in UAT or development environments.

Q: Does the simulator require internet access?

A: No. It communicates locally over a serial connection (USB/RS232).

Q: Can I modify the simulator script?

A: Yes, but only for debugging or extending local tests. Do not alter it for production use.

Q: When running commands on the remote-serial-pay.py, I’m getting an error ModuleNotFoundError: No module named ‘pycrc’.

A: This error indicates that one or more required Python dependencies are missing.
Please verify the following:

• Ensure that all required dependencies (pythoncrc, pyserial) are installed. You can reinstall the dependencies using pip install pycrc pyserial
• Confirm that you are using the latest version of the ECR Simulator tool (remote-serial-pay.py). Reach out to your Maya Relationship Manager to request the most recent version of the script and integration kit.

Q: When running commands on remote-serial-pay.py (for example, a SALE command), there is no ACK response returned.

A: This issue can occur due to several possible causes. Check the following:

• Ensure that the PAX/Sunmi USB driver is properly installed on your host machine.
• Confirm that you have selected the correct serial (COM) port for communication.
• Verify that the ECR app is installed and running on the Maya Terminal.

You can check connection status on the terminal, it should display “ECR Started / Connected to USB” when properly paired.

Next Steps

• Review the ECR Interface Specifications to understand transaction protocols and message formats.
• Validate your integration using Maya ECR Test Cases.
• Once verified, coordinate with your Maya Relationship Manager to begin pilot testing and move toward production.