Build your Merchant Electronic Cash Register Plugin
How Maya ECR Integration Works
The Electronic Cash Register (ECR) is a bridging application between the merchant Point-of-Sale (POS) system and the Maya Terminal payment applications. This streamlines integrating the POS transaction and initializing the customer’s payment through the Maya Terminal.
Connectivity
Maya's ECR integration is possible with the following terminals: Sunmi P2 or PAX A920. Your POS and ECR hardware connects to the Maya Terminal, using a USB port or an RS-232 cable (for PAX Terminals). The Maya Terminal uses internet connectivity via sim card data, wireless network, or Local Area Network/LAN (if using L290 cradle); to communicate the transaction requests to the Maya’s Payment Processors.
For PAX A920 that uses a cradle, the cradle only supports LAN connectivity. In cases that LAN is not used, the cradle will act as a charging port connected to the merchant POS (via USB). The Maya Terminal internet connection will be via sim card data or wireless network.
Supported Maya Terminals
In terms of developing the Merchant ECR Plugin, the API integration specifications are the same for both terminals, like the messaging format, requests, and responses. Regardless if you are using Sunmi P2 or PAX A920, even if you swap from one terminal to another, the Maya ECR Integration should work.
Take note for development and integration:
- Only PAX A920 has “wireless” ECR capability, wherein the terminal can be lifted and given to the customer, with the use of the L920 cradle dock.
- Only PAX A920 can support custom ads or image display on the Maya Terminal.
- Only Sunmi P2 supports Pre-authorization via Maya ECR Integration.
- Sunmi and PAX has different USB drivers.
Stay tuned for future feature updates for the Maya Terminals.
Before you integrate
At this point, you should have the following:
- Completed your Maya Business Manager
setup.
- Ordered and has received the Maya Terminals
- Reviewed and understood the terminal guides.
Reach out to your designated Maya Relationship Manager or email [email protected]
Before the Maya Terminals can be integrated with an Electronic Cash Register, the following pre-requisites should be prepared:
Click here to view full details
- The Maya Terminal Kit (PAX A920 or Sunmi P2)
- USB Data Cable
- Installed Maya Terminal Applications:
- ECR App
- ONE App
- QR Pay (For PAX Terminals Only)
- (OPTIONAL) L920 Cradle - for PAX Terminals
- Host Computer with any of the support Operating Systems: Windows, Linux, and macOS
- Latest Maya ECR API/Interface Specifications
- ECR UAT Test Cases
- (OPTIONAL) Maya Electronic Cash Register Tool (Recommended for simulation and debugging only): remote-serial-pay.py
- (OPTIONAL) USB Drivers with installation guide:
- Windows - PAX or Sunmi
- Linux - PAX
Sign the Non Disclosure Agreement (NDA) with Maya to acquire the integration kit, via reaching out to your designated Maya Relationship Manager or email [email protected]
Setup and Develop
1 Review ECR Specifications and Develop your own Merchant ECR Plugin
The Transaction Flows
There are two (2) types of transaction system flows, asynchronous and synchronous. The following illustrates the sequence of the transaction, starting from the transaction initiation from the merchant’s POS system integrated to the Electronic Cash Register, and the Maya Terminal.
Asynchronous System Flow
Click here to view full details
In the Asynchronous system flow, there are two (2) independent events happening within the transaction, which are the transaction request confirmation, and the transaction payment. The transactions that use this type of flow are:
- Sale
- Balance Inquiry
Asynchronous transaction flow
- The Merchant POS device initiates either a sale or balance inquiry to the Merchant’s ECR Plugin.
- The Merchant ECR Plugin initiates the transaction by sending the JSON transaction request to the Maya Terminal.
- The Maya terminal sends the "Confirm Message", ACK, back to the Merchant ECR Plugin immediately.
- The Maya terminal will forward the transaction to Maya’s payment processor.
- Maya’s Payment Processor will validate the request and forward it to its respective acquirer hosts, for transaction processing.
- Return transaction response to Maya terminal.
- Maya terminal sends the transaction result and details back to the Merchant’s ECR Plugin.
- Merchant ECR Plugin sends the "Confirm Message", ACK, to the Maya terminal immediately, within the three (3) second transaction result message. If the Maya terminal is still waiting for the ACK, but your ECR sends another SALE, the transaction request will be an error.
Refer to System Timeout
Synchronous System Flow
Click here to view full details
In the Synchronous system flow, events with the transaction happen in sequence. The transactions that use this type of flow are:
- Check Line
- Get Transaction
- Reprint
- Void
- Settlement
Synchronous transaction flow
- The Merchant POS device initiates either of the following transactions: Check line, get transaction, reprint, void, or settlement, to the Merchant ECR Plugin.
- The Merchant ECR Plugin initiates the transaction by sending the JSON transaction request to the Maya Terminal.
- The Maya terminal will forward the transaction to Maya’s payment processor.
- Maya’s Payment Processor will validate the request and forward it to its respective acquirer hosts, for transaction processing.
- Return transaction response to Maya terminal.
- Maya terminal sends the transaction result and details back to the Merchant ECR Plugin.
System Timeout
During the development and integration, there are two (2) types of system timeouts that should be considered: the Maya Terminal and the Merchant ECR Plugin.
Maya Terminal Timeout
Click here to view full details
Payment applications installed in the Maya terminals can process transactions within the estimated time of 6 minutes. It includes customer interaction with the terminal, sending requests, receiving responses, and printing receipts. It also provides error cases such as sending reversals and other administrative functions in the middle of the transaction (e.g. thermal paper replacement).
The estimated processing time shall be considered by Merchant ECR Plugins connected to the Maya terminal. Once the transaction exceeds the estimated time, the user must re-transact via the ECR to push the request to the Maya terminal.
Merchant ECR Plugin Timeout
Click here to view full details
The Merchant ECR Plugin should handle the timeout limit.
- For instances of timeout, and Merchant ECR Plugin is unable to respond ACK to the Maya terminal, you may use CHECKLINE, to sync the connection before trying again.
- Send the ACK within 3 seconds. If the Merchant ECR Plugin is not able to send within the time, use the CHECKLINE command (3x) until successful before sending the next SALE request.
- Then you may use CHECKLINE again to sync.
- To view the status of the transaction, you may use Get Transaction / Transaction Details
Maya's ECR Interface Specifications
The ECR Interface Specification document describes the interface between the Merchant’s Electronic Cash Register Plugin and the Maya Terminal. This includes the package format and serialization, tender types, and transaction request parameters.
To request for a copy of the latest ECR Interface Specifications document, reach out to your designated Maya Relationship Manager or email [email protected]
2 Connect Maya Terminal to the Host Computer
Step 1: Connect Maya Terminal to Host PC via USB port
Click here to view full details
Using the provided USB cable from the Maya Terminal kit, connect the Maya Terminal to the host computer via a USB port.
For Maya PAX A920 Terminal (with L920 cradle)
- On the Maya Terminal, open Settings in ECR app, switch Connection Type to any of the following:
- L920-RS232 - uses RS232 cable with RJ45 type end connected to the L920 cradle
- L920-USB SLAVE - uses USB cable with the USB-A end connected to the L920 cradle
- Restart the ECR app
- When ECR app is reopened, click Scan to Pair and scan the L920’s barcode located at the back of the cradle.
Step 2: Run the Maya Terminal ECR Application
Click here to view full details
On the Maya Terminal, run the ECR Application. The notification should be “ECR Started / Connected to USB”.
Connection status via bar (left) and Connection status in Sunmi app main screen (right)
Step 3: Creation of Serial Ports
Click here to view full details
- For Windows
- Check Device Manager. The data COM is the one without the Daemon. In the example below, use COM11.
- For Linux / Unix / OSX
- Via the command line, check the
/dev/
- Via the command line, check the
When the cable connected to the Host PC is removed, the COM Port will be reassigned. It is advisable to set a fixed/default port to avoid this scenario. Refer to Terminal Troubleshooting guide
3 (Optional) Simulate transactions via the ECR Tool
While your team is ongoing on the development of your Merhant ECR Plugin, you may use the Electronic Cash Register Tool, to simulate transaction requests and responses. This simulator can be used on either a Sandbox Maya Demo Terminal or the Production Maya Terminals deployed to your stores.
During your development phase, you may use a Sandbox Maya Demo Terminal. Reach out to your designated Maya Relationship Manager or email [email protected]
- Sandbox Maya Demo Terminal
- Sandbox terminal test tools
- Sandbox Maya application and account.
Go Live
1 Integrate and test with a Production Maya Terminal
Once your ECR software application is done, set up your Electronic Cash Register and connect the Maya Terminal. Follow the same process of setting up and configuring the host computer and Maya Terminal/s.
2 Prepare your Test Cases
You may create additional testing scenarios based on the functionality and features of your ECR software application. Within the provided ECR Integration Kit, refer to the file “Maya ECR Partner UAT Test Cases”. This shows the test cases that should be performed and submitted to Maya.
3 Perform Live Transactions
- Submit your sign-off and email accomplished Maya ECR Partner UAT Test Cases to your designated Maya Relationship Manager.
- Set up your Maya Business Manager. (Maya Manager 1.0 Production .if you are using the legacy Maya Manager) account.
- Be ready for your Post Production Testing. Once launched in production, prepare the following:
- For initiating transactions: Download the Maya App .(For Pay with Maya) and/or use real cards.
- Production launch of your Merchant ECR Plugin for all Merchant POS.
- For initiating transactions: Download the Maya App
If you wish to test live transactions in Production, no test cards will be provided. You will need to use real cards and e-wallet accounts. Transactions performed will incur real charges.
Updated about 1 year ago