Handling Timeouts in ECR-Integrated Terminal

Overview

When integrating your Electronic Cash Register (ECR) with the Maya Terminal, it’s important to handle timeouts correctly. Timeouts occur when a transaction or communication step takes longer than expected, potentially leaving the system in an inconsistent state.

In ECR integration, there are two main types of timeouts to be aware of:

• Maya Terminal Timeout
• Merchant ECR Plugin Timeout

This guide explains both how to differentiate them and what to do when they occur.

Maya Terminal Timeouts

The Maya Terminal operates with two key timeout thresholds that determine how long a transaction remains active before it is automatically terminated:

• ECR App Timeout: ~6 minutes per transaction
• Maya ONE App Timeout: 60 seconds by default

What’s Included in the Timeout Window

The total timeout duration covers the entire transaction flow, including:

• Customer interaction with the terminal (card tap, PIN entry, wallet scan, etc.)
• Transmission of the payment request to Maya’s backend
• Response handling (approved, declined, or error)
• Receipt printing
• Error recovery steps such as reversals or administrative tasks (e.g., paper replacement)

What Happens When a Timeout is Reached

• The transaction fails.
• The merchant must re-initiate the transaction from the ECR to send a new request to the Maya Terminal.

Developer Tip: Always design the Merchant ECR Plugin to respect the terminal’s 6-minute processing window.

Merchant ECR Plugin Timeout

The Merchant ECR Plugin also needs to enforce its own timeout rules to maintain synchronization with the Maya Terminal.

• ACK Handling:
  • The ECR Plugin must send an ACK (Acknowledgement) within 3 seconds after receiving a message from the Maya Terminal.
  • If no ACK is sent, the terminal may assume communication is lost.
• Recovery with Check Line (CHECK):
  • If the plugin fails to respond in time, use the CHECK command to re-establish the connection.
  • Best practice: Retry Check Line up to 3 times before attempting another SALE request.
• Transaction Status Recovery:
  • If unsure whether a transaction succeeded or failed, call the Get Transaction by merchantRefNo to verify the latest status.
  • This recovery step only works if you included a merchantRefNo in the original SALE request.

What happens when this timeout is mishandled?

• The Maya Terminal and ECR Plugin may become out of sync.
• Duplicate charges or missing records could occur if retries are not handled properly.

How to Differentiate Timeouts

FAQs

Q: What if both the terminal and plugin time out at the same time?

A: Prioritize re-synchronization using CHECK. Then check the transaction status with Get Transaction by merchantRefNo before retrying.

Q: Why is the terminal timeout longer (6 minutes) than the plugin timeout (3 seconds)?

Answer:

• The terminal must allow time for customer actions and backend processing.
• The plugin timeout is about communication reliability—ensuring the terminal knows the plugin is responsive.

Q: How do I avoid duplicate charges if I retry?

A: Always call Get Transaction / Transaction Details before pushing a retry. This prevents resubmitting an already successful transaction.

Q: Do I need to configure the terminal timeout manually?

A: No. The 6-minute limit is built into Maya’s payment applications. You only need to handle it properly in your ECR integration logic.

Next Steps

• Ensure your ECR Plugin is programmed to:
  • Send ACK within 3 seconds.
  • Use CHECK (up to 3 retries) if connection issues occur.
  • Re-query transaction status before retrying.
• Respect the Maya Terminal’s 6-minute transaction timeout window.
• Implement clear error handling and user prompts in your ECR to guide merchants on what to do when a timeout occurs.