Distributing Applications and Setting Up Payment Terminals
This guide provides comprehensive instructions for deploying Rapyd payment applications and configuring payment terminals. It covers the end-to-end process for setting up both test and production environments to ensure your devices are ready for transaction processing.
Using the Hardware Manufacturer’s Terminal Management System
To manage your device fleet efficiently, you will utilize the manufacturer's Terminal Management System (TMS). This centralized platform enables you to push applications, update configurations, and monitor the health of your payment terminals remotely.
The Max Store
The Max Store is a terminal management system used for PAX and Sunmi payment terminals. It is not developed by Rapyd; it is provided by PAX and widely used across the industry to manage PAX terminals as well as devices from other manufacturers.
As part of the Rapyd integration, you will receive access to the Max Store. Detailed documentation and operational guides are available online once access to the Rapyd Max Store has been granted.
If you operate your own Max Store environment, Rapyd can also publish its payment applications directly to your store.
This guide does not aim to cover all Max Store capabilities. Instead, it focuses specifically on Rapyd-related functionality and the process of distributing applications to payment terminals.
What You Can Do with the Max Store
Through the Max Store, you can:
Update the terminal operating system
Push and update applications to terminals
Push and update encryption keys
Create automation groups to push applications & keys seamlessly to terminals
Restart terminals
View terminal location
Send messages to terminals
Access remote desktop functionality (with merchant permission) to connect to the terminals remotely
Monitor internet connectivity
Lock terminals
View system metrics such as memory, CPU, and battery usage
And more
Max Store API Capabilities and Parameters
The Max Store also provides an API, allowing developers to manage terminals programmatically without logging into the PAX Store interface.
Through the API, you can:
Register terminals
Activate terminals
Push applications and configuration parameters to terminals
Move terminals between merchants or resellers
Query for app status and versions
Restart terminals
And more
Using the API, it is possible to fully configure a terminal without manually accessing the PAX Store interface. For more information, refer to the Pax Store repository.
Max Store Parameters for the Rapyd Core App: For more information on the parameters that can you can push, see Core Parameters.
Setting Up a Standalone Test Terminal
There is only one “template” available for the Rapyd Core app. This simplifies the setup process for terminals.
Add the terminal to your account in the Max Store using the “+ TERMINAL” function.
Once created, click on the terminal.
Push the Rapyd app application (APK) to the terminal using the “Push Task” operation in the Max Store.
No parameters to be configured at this stage.
This is the standalone Rapyd application.
Push the Rapyd core application (APK) to the terminal using the “Push Task” operation in the Max Store.
A configuration template will appear, allowing you to customize parameters.
Enter the Test TID (also called physical TID or Soft TID) provided by Rapyd in the template. The test TID needs to be requested from your account manager.
Enter the following Test MID (also called sub MID or merchant ID): 800574917121001
Review and adjust any additional parameters in the INITIAL CONFIG section as needed.
For more information on the parameters and their definitions, see Core Parameters.
In the OVERRIDE CONFIG section:
Change Host primary and Host secondary in the PAYMENT SWITCH CONFIGURATION section to target one of the test environments:
terminal.test.valitor.com, port 443 is DEV
terminal.test.valitor.com, port 4434 is UAT
terminal.test.valitor.com, port 444 is CERT
Save the template and push the app to the terminal
Common Issues
Invalid MAC Error
This error may occur if:
You are testing from a country that has not previously been enabled for Rapyd test terminals.
The HostPrimary parameter is not pointing to the correct test URL.
If you suspect a country restriction, please contact Rapyd so we can enable it for test usage.
Setting Up a Standalone Production Terminal
The key difference when setting up a production device is that you must first generate the credentials (TID and MID) for each payment terminal by querying the Rapyd API pairing endpoint. You can find the documentation for this process at Rapyd API Pairing Endpoint.
Add the terminal to your account in the Max Store using the “+ TERMINAL” function.
Once created, click on the terminal.
Push the Rapyd app application (APK) to the terminal using the “Push Task” operation in the Max Store.
No parameters to be configured at this stage.
This is the standalone Rapyd application.
Push the Rapyd core application (APK) to the terminal using the “Push Task” operation in the Max Store.
A configuration template will appear, allowing you to customize parameters.
Enter the physical TID (also called Soft TID, or TID) received from the Pair Payment Device API endpoint after pairing the prod terminal to the Rapyd platform.
Enter the MID ( also called sub MID or merchant ID) received from the Pair Payment Device API endpoint after pairing the prod terminal to the Rapyd platform.
Review and adjust any additional parameters in the INITIAL CONFIG section as needed.
For more information on the parameters and their definitions, see Core Parameters.
In the OVERRIDE CONFIG section:
Change Host primary and Host secondary to target one of the test environments:
Host Primary terminal.valitor.com:443
Host Secondary pay.tnsi.eu.com:46366
Using Rapyd’s Partner Portal - QR Code scanning
To simplify the terminal setup process for merchants and partners, Rapyd provides an alternative terminal provisioning method through its QR code solution.
When using the Rapyd QR code setup, the first step is to download the Rapyd Onboarding App to the terminals you plan to deploy. This is done via the Max Store. The process can be automated so that any terminal coming online automatically downloads the onboarding application.
The onboarding app is a temporary installer that provisions the required Rapyd applications on PAX or Sunmi devices for each merchant.
After the onboarding app has been installed, generate a QR code for your merchant by following the instructions in Adding a Payment Device to Your Account
After scanning the QR code with the terminal:
The Rapyd Standalone App and Rapyd Core App are automatically downloaded
A default configuration is applied
All required parameters for transaction processing are set
If the default configuration does not fully meet your requirements, you can return to the Max Store and push the Rapyd Core app again with additional or updated parameters (for example, adding your logo or modifying configuration settings).