Understanding Errors in ECR Integration

Overview

When integrating an Electronic Cash Register (ECR) with the Maya Terminal, occasional issues or errors may occur. These can stem from various points in the integration: hardware, software, or communication layers.

Common sources of issues include:

Hardware or peripheral malfunctions (e.g., cable, USB, or terminal issues)
Misconfiguration in application setup or terminal parameters
Network or communication interruptions between the ECR and the terminal
Timeouts or transaction flow disruptions

Understanding how to identify, categorize, and resolve these errors ensures a reliable and user-friendly payment experience.

This guide consolidates common problem types, root causes, and recommended actions to help developers troubleshoot effectively and restore transaction flow quickly.

Identifying the Symptoms

Errors in an ECR-integrated setup can occur in any component of the system, either on the ECR, Maya Terminal, or network.

You can identify the issue by observing the symptoms displayed on the device or by reviewing the logs in your system.

Typical areas where issues arise include:

Hardware-related issues: USB connection, cable, terminal type
Software-related issues: operating system, driver, application, or firmware incompatibility

Both the ECR and the terminal will show corresponding prompts or error messages indicating where the problem originated.

Common Causes of Errors

Errors during ECR integration generally fall into three main categories.

1. Integration Problems

Integration problems occur when the ECR application is not properly configured or sends invalid requests to the terminal.

Common Causes:

Missing required fields in requests
Invalid parameter types (e.g., non-numeric amounts, invalid currency codes)
Errors opening or maintaining USB/COM connections

High-level Resolution:

Review your integration setup and field mapping.
Verify all configuration parameters align with the Maya ECR Specifications.
Confirm credentials, port configurations, and hardware connectivity.

To troubleshoot the ECR integration, refer to Troubleshooting ECR Integration

2. System Errors

Caused by communication failures, timeouts, or downtime on Maya services.

Common Causes:

Timeout or disconnection between ECR and terminal
The issuer or acquirer system is inoperative
“General Error” or system crash leading to incomplete transactions

High-level Resolution:

Check network connectivity and retry logic.
Ensure the ECR and terminal service processes are running.
Reconcile transactions using backend logs.
Refer to Handling Timeouts in ECR-Integrated Terminal for timeout handling strategies.

3. Declines

When a payment transaction is rejected, the Maya Terminal sends a decline response to the connected ECR system with a command status R for Rejected.

Possible Sources:

Issuer Declines – due to account restrictions, invalid card details, expired card, or insufficient funds.
Acquirer Declines – due to merchant configuration, terminal setup, or communication problems.

Resolution:

If the decline is valid (e.g., insufficient funds, expired card), advise the customer to contact their issuing bank or use another card.

Refer to these pages for detailed decline code lists:

Initial Checks for Developers

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

1. 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.
To install the drivers manually, refer to ECR Integration Setup [link].

2. Check Communication Services

Launch the ECR App on the Maya Terminal.
Wait 30–60 seconds for service initialization.
If unresponsive, restart both the ECR App and Maya ONE App.

3. Validate App Version and Configuration

Ensure both apps are up-to-date.
If multiple payment apps are installed (e.g., GCash, WeChat), confirm each is configured properly.
Request OTA (Over-the-Air) updates from Maya Business Support if needed.

4. Confirm Merchant and Network Setup

Verify Merchant ID (MID) and Terminal ID (TID) are active.
Check that the terminal is online and peripherals are connected.

Review Logs and Responses

Analyze ECR logs for request/response pairs.
Track the latest command status (refer to Understanding the ECR Command Statuses [link]):
- P – Processing
- A – Approved
- R – Rejected
- V – Voided
- C – Canceled
Match timestamps with Maya Business Manager reports.

FAQs

Q: The error appears on the Maya Terminal. What should I do?

A: Read and understand the error prompt:

If the error was due to connectivity or integration error, refer to Troubleshooting ECR Integration
If the error was due to the device-specific functionality, refer to Terminal Hardware Concerns

Q: The ECR cannot detect the terminal.

A: Do the initial checks to isolate the root cause:

Confirm that both devices are on
Verify that both devices are connected via USB or network
Check whether the required drivers were installed correctly
For detailed troubleshooting, refer to Troubleshooting ECR Integration

Q: How do I capture ECR logs?

A: Export request/response logs with timestamps and transaction IDs. Provide them during escalation.

Q: What if I encounter a timeout?

A: The ECR Plugin must respond with ACK to the terminal. Use the CHECK command up to three (3) times before retrying a new sale. Refer to Handling Timeouts in ECR-Integrated Terminal

Q: Where can I access ECR specifications and drivers?

A: All installation files and documentation are provided by your Maya Relationship Manager to your authorized representative.

Next Steps

When encountering problems or errors in an ECR-integrated terminal setup, follow these steps to identify and resolve the issue efficiently:

Perform Initial Checks
- Verify connectivity, configuration, and device recognition.
- Ensure both the ECR and terminal apps are running and up-to-date.
Observe Error Messages or Symptoms
- Note any on-screen prompts or error codes displayed on either the ECR or terminal.
Identify the Problem
- For Configuration or Integration Issues: Review your setup and refer to the Troubleshooting ECR Integration
- For Timeouts or Communication Failures: Refer to the Handling Timeouts in ECR-Integrated Terminal guide.
- For Declined Transactions (Command Status: R or Rejected): Check the Maya Terminal display for the specific error message, then refer to the Maya ONE App Decline Codes pages for detailed causes and resolutions.
Record and Log Details
- Capture timestamps, transaction IDs, error codes, and relevant log entries for traceability.
Contact Maya Business Support

Provide the following information for faster resolution:

Terminal Type (Sunmi/PAX)
Merchant ID (MID) and Terminal ID (TID)
Error message or code
Relevant log excerpts