Overview
The ECR integration with Maya Terminal requires the implementation of asynchronous and synchronous flow. These two flow types define how the Electronic Cash Register (ECR), ECR App, and Maya ONE App communicate and process transactions.
Understanding which flow applies is essential for correctly handling responses, confirmations, and transaction results in your integration.
Command or Transaction Types
Transaction types determine the kind of request initiated by the ECR and define whether the flow will be asynchronous or synchronous.
| Command/Transaction Type | Description | Flow Type |
|---|---|---|
| Sale | Perform a sale transaction | Asynchronous |
| Balance Inquiry | Request to check account balance | Asynchronous |
| Check Line | Verify connectivity between the host and the terminal | Synchronous |
| Get Transaction | Retrieve transaction details | Synchronous |
| Reprint | Reprint the last or specific receipt | Synchronous |
| Void | Cancel a successful sale transaction | Synchronous |
| Settlement | Perform end-of-day settlement of transactions | Synchronous |
ECR-Integrated Flows
Asynchronous Flow
In an asynchronous flow, two independent events occur during the transaction:
- Transaction Request Confirmation – The ECR App immediately acknowledges that the transaction request was received.
- Transaction Payment Response – The actual payment processing and final response follow later once the Maya Payments host completes the transaction.
This approach ensures that time-sensitive actions (like acknowledging receipt) are not delayed by external processing time.
Asynchronous flows are used when the transaction requires real-time payment authorization or card network processing, such as:
- Sale
- Balance Inquiry
- The User initiates the transaction request in the ECR.
- The ECR Plugin sends a JSON-formatted transaction request to the ECR App.
- The ECR App responds immediately with an
ACK(Acknowledgment) to confirm receipt of the request. - The ECR App forwards the transaction request to the Maya ONE App for processing.
- The Maya ONE App sends the transaction request to the Maya.
- Maya processes the transaction (validates and applies business rules).
- Maya returns the final transaction response (approved or declined).
- The Maya ONE App forwards the transaction result back to the ECR App.
- The ECR App sends the transaction details (status, reference, amount, etc.) to the ECR Plugin.
- The ECR App sends an
ACKto confirm that the transaction details were received.
Synchronous Flow
In a synchronous flow, all transaction events happen sequentially. The ECR waits for each step to complete before proceeding to the next.
This flow type is used for non-payment operations or transactions that do not require asynchronous confirmation, such as:
- Check Line
- Get Transaction
- Reprint
- Void
- Settlement
Synchronous flows ensure that the ECR receives an immediate and final response for every request.
- The User initiates the transaction request in the ECR.
- The ECR Plugin sends a JSON-formatted transaction request to the ECR App.
- The ECR App forwards the transaction request to the Maya ONE App.
- The Maya ONE App sends the transaction details to the Maya.
- Maya processes the request (e.g., verifies data, retrieves records, or performs reconciliation).
- Maya returns the transaction response (success, failure, or data result).
- The Maya ONE App sends the final response back to the ECR App.
- The ECR App forwards the transaction details to the ECR Plugin for display or receipt printing.
- The ECR then notifies the User.
Key Differences Summary
| Aspect | Asynchronous Flow | Synchronous Flow |
|---|---|---|
| Process Timing | Request acknowledgment and final response occur separately | The entire process happens in sequence |
| Used For | Sale, Balance Inquiry | Check Line, Get Transaction, Reprint, Void, Settlement |
| ECR Handling | Must handle separate ACK and final response | Waits for the complete transaction result |
| User Impact | The user may see “Processing” before the final result | User gets immediate feedback |
| Common Use Case | Real-time payment authorization | Data retrieval or transaction management |
FAQs
Q: How do I know if my transaction should use asynchronous flow?
A: Use asynchronous flow for any transaction involving payment authorization or real-time card validation (e.g., Sale, Balance Inquiry).
Q: What if the ECR doesn’t receive the final response?
A: The ECR should handle timeouts and retry logic by checking the transaction status via the Get Transaction command (synchronous).
Q: Can I switch between synchronous and asynchronous modes dynamically?
A: Yes. The flow depends on the type of command or transaction. Your integration logic should detect the type and route accordingly.
Next Steps
Now that you’re familiar with the asynchronous and synchronous flows for ECR Integration, proceed with the following:
- Review the setup guide and prepare your environment. To start the ECR integration, see Preparation for ECR Integration.
- Ensure your ECR Plugin correctly handles both asynchronous and synchronous transaction flows, including message acknowledgments, response handling, and timeout management.