1. What is Linkly MPOS?
Linkly MPOS is a powerful payment solution designed to enable POS applications to run directly on Android-based payment terminals. It allows these applications to seamlessly process transactions by communicating locally with the Linkly Payment App running on the same device.
2. How does it work?
- The MPOS Application sends an HTTP transaction request (amount, type, etc.) to the Linkly Payment App.
- The Linkly Payment App prompts the customer to pay by tapping, inserting, or swiping their card.
- The Linkly Payment App securely sends payment details to the Payment Processor. The Payment Processor communicates with the customer’s bank to approve or decline the transaction.
- The Payment Processor sends the result (approved or declined) back to the Linkly Payment App. The Linkly Payment App shares the outcome with the MPOS Application.
- The MPOS Application retrieves the receipt (digital or printed) from the Linkly Payment App. The transaction is logged, and any post-payment actions (e.g., loyalty points) are triggered.
- If an error occurs (e.g., card declined or network issue), the Linkly Payment App notifies the MPOS Application to handle it appropriately.
3. Why should I choose MPOS?
The Linkly Android ecosystem empowers third-party developers to build innovative POS applications directly on the terminal.
With our seamless interface, you can design applications that act as the terminal’s front end, while securely delegating payment processing to the Linkly payment app—ensuring a smooth and efficient transaction experience.
4. What Are the Requirements to Integrate to Linkly MPOS?
- Expertise in building sociable, high quality Android applications
- Collaboration with an acquirer for application signing in production.
- Compatibility limited to PAX devices supported by the acquirer
5. What Are the Linkly Apps?
Linkly Apps are Android applications that facilitate communication between a POS system and payment terminals. These include:
- Linkly payment app: The main application that is responsible for managing the payment with the bank host.
- Linkly Sec app: App that manages the security protocols between apps.
- Launcher App: Provides a user interface for accessing the POS App and Linkly apps.
- Connect App: App that manages requests between the POS app and Linkly Payment app.
- Res App: Resource app that manages POS app permissions, bank host configuration, and POS App foreground capability.
6. Where do I begin?
6.1 Review MPOS API documentation:
6.2 Get an Android Debug Terminal for Offline Development:
If you are working with one of our partner acquirers, you can request them for a supported Android Debug Terminal or get one from the device manufacturer.
At this stage, we only support the following terminals to ensure the shortest go-to-market turnaround time:
| Device Type | Android Version |
| PAX A920 | 7 |
| PAX A920pro | 8, 10 |
| PAX A77 | 8 |
| PAX A910S | 10 |
| PAX A80 | 10 |
Note: A77 terminals do not have an integrated printer. The MPOS integrator must manage external printers or over-the-air receipts.
Refer to Android Setup Guide v2.0.pdf. This document is targeted toward PAX hardware, but the steps are similar to any Android device with Linkly Connect App.
6.3 Get the Linkly Apps
- Initiate Contact: Email posintegration@linkly.com.au introducing yourself, and if applicable, the merchant and acquirer you are supporting.
- Terminal Setup: Include the device model and serial number of any development terminals you have so we can remotely load our Offline software suite. Note that Linkly only supports terminals in the Linkly container therefore you must remove the devices from all other containers.
6.4 Do we need credentials for MPOS?
No, credentials are not required for MPOS integrations.
7. POS software setup
7.1 I don't have an MPOS app.
Linkly TestMPOS App
Linkly provides the TestMPOS app which runs on the Android terminal for demoing purposes. This will be provided upon request along with the rest of the Linkly Apps in offline demo mode.
Test with an API Client
To test with an API Client, such as Postman, you need to ensure the following.
- You have the Android Debug Terminal’s IP address as you need to enter it in the API endpoint.
- The port number to be entered in the API endpoint is 8000.
- Your Android Debug Terminal and your Machine running your API Client application is connected to the same network.
- Your API request is formatted correctly as per the MPOS specification.
- API endpoint format:
http://{{terminal_ip}}:8000/v1/sessions/{{session_id}}/transaction
Example:
http://192.168.10.10:8000/v1/sessions/1f4852ba-1b31-46db-bec1-85bfa35258be/transaction
7.2 I have an MPOS App.
If you are beginning to, or, already have a MPOS App and want to integrate it with Linkly MPOS, it's crucial to first test the API methods using an API client like Postman before making any changes to your MPOS software. This allows you to:
- Understand how the API works, including authentication, requests, and responses.
- Identify potential issues early, ensuring a smoother integration process.
- Validate functionality before implementing changes in your POS system.
Testing beforehand helps prevent errors and streamlines the development process.
Integrate the API with your POS
Refer to the API specifications and ensure your POS integration follows our guidelines and best practices.
8. How to make our MPOS app appear as the main display?
To make your MPOS app the front-end application, Linkly will need to whitelist the MPOS application in the Res App. The Res App whitelisting can only be done after your MPOS app is accredited with Linkly.
9. Is the Linkly Launcher App mandatory?
The Linkly Launcher is mandatory as it manages the permissions and interactions between all Linkly apps and the POS app.
10. Error recovery methods and best practices?
Transaction Status:
The Transaction Status API method is used in scenarios where confirmation or validation of the last payment is required, such as during error recovery, troubleshooting, or customer queries.
Exponential Back-off Logic:
Exponential backoff is a technique used to reduce added strain on already overloaded servers, networks, or infrastructure. It refers to the process of increasing the delay between each subsequent request, starting with a short delay and working up to a longer delay if the error condition continues. We request that if you get a response from our servers that may indicate overloading that you employ basic exponential backoff in your recovery attempts.
- Warning: When using retries Backoff should retry for up to 3 minutes maximum before returning an error to the operator. Please note that if you do not get either an HTTP 200 or a 404 during recovery, you CANNOT know for sure whether the transaction was successful.
- Tip: The backoff periods should be slightly randomised for better results: eg. start with 1000ms (+/- 500ms), then double it each time (+/- 500ms): eg. 640ms, 1620ms, 2890ms, etc. Backoff can continue until a set maximum number of retries or 3 minutes (total) has passed, whereon the POS may fail, returning control to the operator.
11. Can we access the device hardware and API?
APIs to device hardware are managed and provided by the device manufacturer. You will need to contact the device manufacturer to request APIs. Linkly cannot provide these.
12. How to access the device settings?
To access the device settings, you will need to enter the password: pax9876@@.
Note that the password is case sensitive.
13. Does the Accreditation cover test cases on Hardware API?
No. The POS Vendor must test and ensure all logic added to control hardware elements is working as per their expectations. Any issues encountered will need to be raised directly with the device manufacturer.
14. How do we get a Res App?
The POS integrations team will provide the Res App post accreditation.
15. Going to Production?
To go to production, your MPOS app will need to be deployed with an Acquirer, and Linkly will need to provide you with a Res App. This application allows your MPOS app to function as the front-end app and makes it accessible via the Linkly Launcher.
To proceed with building the Res App, we will require the following, post-accreditation:
- The name of the Acquirer you will be partnering.
- The package (APK) name of your MPOS app.
- Your company logo.
Once received, we’ll prepare your Res App and submit it to your Acquirer who can then deploy it to your Production devices for PVT.
16. MPOS Surcharging
MPOS Surcharging is configured via Linkly TMS update and applies to Sandbox environments only. To enable Surcharging, please send an email to posintegrations@linkly.com.au.
You won’t have to modify the transaction request object to facilitate surcharging. However, If a surcharge is applied, the following tags will appear in the Purchase Analysis Data (PAD) section of the transaction response:
• The SUR tag will be present in the purchaseAnalysisData TransactionEvent, and will contain the value of the surcharge applied in cents.
• The AMT tag will be present in the purchaseAnalysisData TransactionEvent, and will contain the total value of the sale (e.g. purchase amount + surcharge)