1. What is Linkly Cloud?
Linkly Cloud is a wireless solution that connects a Point of Sale (POS) system to a payment terminal, acting as a bridge to forward API requests and responses. While it offers a streamlined and simple integration, its features are more limited compared to other Linkly solutions. This makes it particularly well-suited for small businesses with lower transaction volumes that require basic transaction processing capabilities. Linkly Cloud provides a cost-effective and efficient solution for businesses that don’t need the extensive functionality of more complex systems, ensuring seamless payment processing with minimal setup and maintenance.
2. How does it work?
- The POS system sends a JSON-formatted request (amount, payment method, merchant details) via HTTPS to Linkly Cloud.
- Linkly Cloud forwards the request to a payment terminal.
- The customer taps, inserts, or swipes their card on the terminal.
- Linkly Cloud securely routes the transaction to the bank for approval.
- The bank verifies funds, checks for fraud, and returns an approval or decline response.
- The POS receives the final transaction response.
- If approved, the POS can finalise the sale and proceed to additional functions (printing receipts, refunding)
- If declined, the POS can prompt for another payment.
3. Why should I choose Cloud?
Benefits include:
- Platform-Agnostic: Works across multiple operating systems, including Windows, macOS, Linux, and mobile platforms.
- Ease of Maintenance: Centralised updates and management reduce local maintenance efforts.
- Accessibility: Accessible from anywhere with an internet connection.
4. Where do I begin?
4.1 Review Cloud API documentation:
4.2 Request Linkly Cloud Sandbox Account:
Email the following details to posintegrations@linkly.com.au
4.3 Terminal setup - Android terminal
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.
4.4 Terminal setup - Ingenico Move 5000 terminal
Click here for instructions on setting up Ingenico Move 5000 for Cloud.
4.5 I don't have a physical terminal
Get Linkly Virtual Pin Pad
Download and install the Linkly Test Harness for Offline Development mode.
Refer Linkly Cloud Test Harness.pdf
Configuration instructions for Virtual Pin Pad in Cloud:
Steps to Enable Cloud Mode on VPP
| Step | Action |
| 1 | Click FUNC |
| 2 | Enter 7410 on the keypad |
| 3 | Click OK |
| 4 | On TERMINAL CONFIGURATION, click 0 on the keypad |
| 5 | On CLOUD MODE, click 1 on the keypad |
| 6 | Click OK |
| 7 | Click CANCEL to go back to the home screen |
Steps to GET/RESET Cloud Pair Code:
| Step | Action |
| 1 | Click FUNC |
| 2 | Enter 8880 on the keypad |
| 3 | Click OK |
| 4 | Click OK |
Disable Virtual Pin Pad Auto Approve
The VPP features transaction simulations using the cent value of the amount. For example, you can trigger Pin Pad signature prompts by transacting $10.08. This feature is controlled by a toggle called Auto Approve and its purpose is to allow all transactions to approve regardless of the cent value in the amount field.
If it’s required to simulate “approved” transactions with different cent values, please enable Auto Approve.
However, for your accreditation test cases and simulating signature prompts and declines, please ensure Auto Approve is disabled to avoid incorrect results.
Auto Approve Settings:
| Auto Approve ENABLE | Auto Approve DISABLE |
| FUNC 7410 OK, 1, CLEAR, OK, CANCEL | FUNC 7410 OK, 1, CLEAR, CLEAR, CANCEL to return to the main screen |
4.6 POS software setup
I don't have a POS software?
Linkly IPTestPOS
You can use the Linkly's IPTestPOS, which is a test POS software used for demonstration purposes. Please refer to Linkly Cloud Test Harness.pdf (Step 4.5) for instructions.
I have a POS Software?
Test Cloud with an API client
If you already have POS software and want to integrate it with Linkly Cloud, it's crucial to first test the API methods using an API client like Postman before making any changes to your POS 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.
5. Difference between Cloud Sync and Async?
The Linkly Cloud API offers two integration modes for connecting Point of Sale systems with payment processing services: Synchronous (Sync) Mode and Asynchronous (Async) Mode. The differences are explained here: Async vs Sync
Synchronous (Sync) Mode:
Operation:
- In this mode, the POS sends a transaction request and waits for the operation to complete before receiving a response.
Characteristics:
- The POS remains idle during the transaction process, awaiting the final result.
- Limited feedback is provided during the transaction; the POS typically receives only the final success or failure status.
- Suitable for simpler implementations where immediate feedback is not critical.
Asynchronous (Async) Mode:
Operation:
- The POS initiates a transaction and continues with other tasks, receiving updates and the final result through callbacks or notifications.
Characteristics:
- Allows the POS to handle multiple tasks concurrently, improving efficiency.
- Provides real-time feedback and status updates throughout the transaction process, enhancing user experience.
- Requires the POS to manage asynchronous responses and may involve more complex implementation.
- Linkly recommends using the Asynchronous Mode for its enhanced functionality, better user experience, and closer alignment with other Linkly implementations.
Which Cloud integration should we choose and why?
Choose based on transaction volume and latency requirements.
-
Async is the preferred integration type as it sends terminal events to the POS in real time providing the merchant more visibility and control over the transaction.
-
Sync has limited feature support and does not provide real time transaction processing details to the POS.
6. Linkly Cloud operations in Sandbox and Production?
Sandbox is used for testing and does not process real transactions. Linkly will provide test API credentials which can be used for Authentication. The POS must use the Sandbox specific API endpoints for testing/offline development.
Production handles live transactions with Production API credentials. The credentials are provided directly to the merchant when they are onboarded through an acquirer.
7. Why do we need Cloud credentials?
They are required for API authentication to pair the pinpad to the POS. Once paired, the POS can use the Secret to get AuthTokens for transactions.
8. POSID and POSVendorID in the AuthToken request?
Unique identifiers for your POS system and vendor. Linkly uses them for tracking and validation.
https://www.linkly.com.au/apidoc/REST/#auth-token-request
9. How does PairCode, Secret, and AuthToken work?
The validity of the Secret is tied to the validity of the Pair code. If the Pair code has changed/reset, the POS will need to be re-pair to the pinpad using the Cloud API credentials, along with a new Paircode from the pinpad. The Pairing process will create a new Secret, which must be used to create a new AuthTokens. The new AuthTokens must be sent in the header for every API request.
10. Why do we have to create our own UUIDs?
UUIDs uniquely identify transactions for tracking and error recovery. These are created and stored by the POS to track the transaction end to end.
11. Does Linkly Provide a Test Harness for Cloud?
Linkly provides a test harness for integration testing. The test harness can replicate scenarios like successful transactions, declined transactions, and error conditions. The Test Harness can be downloaded from the Linkly Website and it includes:
- Cloud Sandbox account
- The Virtual Pin Pad
- IP Test POS software.
12. Triggering transaction simulations/errors in Cloud?
Transaction simulations and error testing is done by setting the cent value of a transaction amount to a specific value. Linkly recognises these values and triggers the corresponding transaction flow/error from the predefined Response codes and Error Lists.
For example: If you configure the amount as $10.50, Linkly will return a “SYSTEM ERROR” response. If you set it to $10.08, it will trigger a Signature Verification flow.
13. Is There an SDK for Cloud?
Currently no SDKs are available for Cloud.
14. How Can We Get a Physical Test Device for UAT?
Linkly cannot provide physical test devices. Please request devices from your acquirer.
15. List of Sandbox vs Production API Endpoints?
Linkly provides separate endpoints for Sandbox (testing) and Production environments.
- Sandbox: Used for development and testing. Transactions in this environment are simulated.
-
Production: Used for live transactions.
16. Error Recovery Best Practices:
16.1 Transaction Status
- The Transaction Status API method is typically used in scenarios where confirmation or validation of the last payment is required, such as during error recovery, troubleshooting, or customer queries.
16.2 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.
17. How Can We Get Linkly Cloud Logs?
During POS development and integration, please contact posintegrations@linkly.com.au and provide the Cloud ID requesting for Cloud logs.
18. Cloud Surcharging
Cloud Surcharging is configured on Linkly's end and applied per Cloud username. This applies to both Production and Sandbox environments. To enable Cloud Surcharging, please send an email to posintegrations@linkly.com.au with your Cloud username along with your request.
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)