Home > Guides

Guide Contents

Terminal Update Guide v1.3

Added on:  07/25/18     Updated on:  03/01/22
Table of Contents

Introduction


The purpose of this guide is to familiarize users with terminal update process, all system mechanisms involved in this process and any possible issues related to the terminal update.


Intended Audience


This guide is intended for the users that deal with issues around terminal fulfillment, processing and update.

Overview


For operating, terminals use terminal application, which gets uploaded during the fulfillment process. You should keep this application up-to-date to receive new features, enhancements and bug fixes. For this purpose, the process of a terminal update is used. It includes three separate processes: uploading of the terminal application by a fulfillment center, an update of the terminal application of an operating terminal, and terminal recovery for cases when the update didn’t go smoothly.

For better understanding of the terminal update process at the different phases, you can learn the terminology below:

ТMS


Since a significant number of terminals are located remotely, there is a need for both remote and centralized terminal management. For this purpose, the Terminal Management System (TMS) is used. The TMS is a module within the gateway that allows a user to control and manage processes in a terminal. Examples include (but are not limited to), initializing parameters, recording logs, and updating general configurations such as EMV configurations, encryption keys (not all keys can be updated) and terminal software (operating system and payment application).

Installation Application (in conjunction with an Agent Code)


After a terminal is delivered to a merchant, it must be initialized. For this to occur, an installation application is necessary. This application carries out the initialization process of the new, factory-assembled terminals and terminals that have been reset. Specifically, the installation application allows for the upload of a set of basic parameters, configurations, encryption keys, an OS, and the payment application to the TMS. To perform the upload, the terminal must be authorized within the TMS. For authorization, a username and password are required. During terminal registration, with the help of an agent code, an authorization of the terminal is performed via the username and password. The agent code is an identifier of the agent under whose account the initial authorization is performed during the installation process in a fulfillment center.

Third Party Payment Application


The terminal manufacturer provides a base OS. Typically, its functionality is not advanced enough to perform transaction processing. For that reason, most manufacturers offer their own payment applications. Unlike the base OS, these applications are not mandatory. Thus, an alternative payment application, or so-called third-party payment application, may be used instead. This application is the implementation of the payment behavior or business logic. It has access to the peripherals (card readers, PIN pad, etc.) as well as implementing the necessary logic of the payment application – such as transaction processing, tokenization, encryption, etc. – while interacting with the gateway. If no third-party payment application is installed, the terminal fails to process payments.

Update Version


Not all terminals should be updated simultaneously because there is a chance that the latest version of an update may contain bugs or shortcomings, which can negatively impact terminal efficiency. Additional reasons for not updating all terminals at once include various terminals having different versions of updates already installed, some terminals being deactivated for a period of time, or having been in transit. For those reasons, different terminals may have various builds of the application installed. To understand which functionality a particular terminal possesses, it is necessary to track which version is installed on each terminal. To help simplify this process, each application build is assigned its version (code) - update version.

After the terminal is switched on, it sends a ping request to check the Internet connection. Once the connection is established, the terminal calls a get-update function to check the available terminal updates. If the terminal fails to connect to the Internet within 60 seconds, the following message is displayed on the terminal screen: "Internet not detected"
The message will disappear once the connection is restored and a new attempt to check the available updates will be performed.

If the Internet connection is not restored, the next processing stage will start.



Update Profile


During the terminal update, it is complicated and inconvenient to integrate the settings of each particular terminal. To optimize this process, the terminals are divided into groups with similar/repeated characteristics. With regard to these characteristics, a corresponding terminal update of the application is uploaded. The update for a particular group of terminals is required for:
  • terminals of the same model or manufacturer (Ingenico, Verifone);
  • a specific terminal application version that differs dramatically from the others;
  • merchants belonging to the same business type but differing dramatically from the others.

To update terminals of the same group, an update profile is used. The profile is a series of settings required for a particular group of terminals. Based on these settings, the terminal application is uploaded to the terminal. The profile defines which version (in what form and with what parameters) is going to be installed on the particular group of terminals. In other words, the update profile allows the user to combine the settings required for a particular group of terminals and manage multiple processes related to the terminal update.

Repository


To perform a terminal update, the required files are uploaded to the terminal. For security reasons, and in order to unify and organize the uploading process of these files remotely, files must be uploaded from a single location called a repository. A repository is a vault for files that are uploaded to the terminal during the updates. Terminal update files are downloaded from a local computer and, subsequently, to the repository. From the repository, the files are uploaded to the terminals via TMS API.

Segment


There is a need to update terminals that belong to a particular group. This is done to avoid cases where a malfunction occurs on numerous terminals, which, subsequently, may necessitate costly repairs. For example, an update is issued for the update profile used for mobile and desktop terminals. This update is released to fix a bug present in the mobile terminals only. In this particular case, all mobile terminals (a problem group) are segregated into a separate sub-group (a segment) within the update profile. This sub-group of terminals is uploaded with specific versions of the update. Thus, the segment allows for the updating of only those terminals belonging to it.

Terminal Level


When a new update is released, there is always a risk that the updated terminals may start to malfunction. Additionally, various merchants utilize terminals differently because, among other factors, the way the terminals are used is dependent on the platform managing them and their behavior. For that reason, there is a need to assign a terminal with a particular level indicating which wave of the update the terminal will belong to and the level of risk tolerance the terminal owner has in case a malfunction occurs. This level is referred to as a terminal level. There are three terminal levels - Beta, Alpha, and Release.
Beta - a level assigned to the terminals of merchants with high tolerance levels for a potential malfunction in order to determine serious and evident bugs. Alpha - a level assigned to a majority of merchants’ terminals to determine minor bugs and monitor how the update functions in the broader environment. Release - a final level to which the rest of the terminals receiving an update belong to.

Activity Log (in conjunction with Diagnostics Log)


When there is an issue with a remote terminal, it is necessary to determine the problem. For this to happen, it is required to know what the settings of the terminal are and what steps preceded the malfunction. After that, remote debugging must be performed. To analyze and locate the problem remotely, activity and diagnostics logs are used.
Activity logs store the information of all the activities of the terminal and record all operations performed by it. Diagnostics logs store all characteristics data (memory, number of hard drives, peripherals’ performance, etc.), applications uploaded to the terminal, and data regarding the physical condition of the terminal. The TMS allows users to review all operations performed by the terminal before the failure occurred.

Recovery


Sometimes, issues related to the management of a remote terminal may occur. For example, when the process of a terminal update fails, or certain parameters cannot be changed. In other words, control of the terminal is lost. In this particular case, a recovery of the terminal can be performed. The recovery function performs a complete reset of the terminal and restores the ability to manage it remotely. After the recovery is complete, the terminal update can be continued, and parameters can be changed.

Base Version


When the recovery process is activated, a terminal is rolled back to the most stable version (the last version functioning trouble-free for an extended period of time in the production environment). This version is supposed to facilitate the proper operation of the terminal and potentially download new updates. Typically, it is called a base version. The base version of the application is uploaded to the new (factory) terminals by the fulfillment center. After that, in cases of recovered terminals, new updates can be installed based on this version.


Installation Instruction


These instructions are meant for the fulfillment center associated with fulfilling terminals prior to sending them to merchants. The process below describes how to make the terminals ready for use. It includes the following steps:

  1. Driver Installation
  2. LLT Installation
  3. OS (SDK) Version Verification
  4. Terminal Reset
  5. OS (SDK) Upload
  6. System Application (Tellium) Upload
  7. KIA Application Upload
  8. Injection Keys Upload
  9. System EMV Files Upload
  10. Payment Application Upload

Make sure that you have received an installation package along with these instructions.

Driver Installation


The driver is needed for a workstation to detect a terminal when it is connected via a USB cable.

To install the driver, follow these steps:

1) Locate and run the 01 - IngenicoUSBDrivers_2.60_setup.exe file. 2) Choose an installation folder for the driver.
3) Locate the Product ID (PID) dropdown menu. Select ID “0028” in the first dropdown (constant value for Telium) and your terminal model in the second dropdown. Enter “124” (constant value) in the Virtual COM Port section for both dropdowns.



4) Disable the “Uninstall Microsoft Usbser drivers(s)” checkbox.



5) Verify the folder where the driver will be installed and start the installation process.



6) Click “Finish” to complete installation.


LLT Installation


LLT is needed for the software to be loaded onto the terminal. The current version of LLT is v5.5.0 for Windows 10, and v4.5.1 for Windows 7.

To install LLT, follow the steps below:

1) Locate and run the 02 - LLT_Setup.exe file. 2) Review the guide for LLT installation and configuration guidance, and start working with terminals.

OS (SDK) Version Verification


There can be situations when a terminal automatically switches to LLT mode when it is turned on. This means that the terminal does not have SDK installed. If this is your case, skip this section and go to the "OS (SDK) load" section.

Verify that the terminal is in LLT mode.



To verify the SDK version, follow these steps:

1. If your terminal model is iCTXXX, iPPXXX or iWLXXX, press the “F” button when the terminal is in standby mode.



If your terminal model is iSCXXX, press the “+” button when the terminal is in standby mode.



2. Select the “0-Telium Manager” menu option on the terminal screen or press “0” on the terminal keyboard.



3. If your terminal model is iCTXXX, iSCXXX or iWLXXX, select "1-Consultation" on the terminal screen or press 1 on the terminal keyboard. If your terminal model is iPPXXX, select "2-Consultation" on the terminal screen or press 2 on the terminal keyboard.


4. If your terminal model is iCTXXX, iSCXXX or iPPXXX, select "4-Configuration" on the terminal screen or press 4 on the terminal keyboard.


If your terminal model is iWLXXX, select "2-Configuration"on the terminal screen or press 2 on the terminal keyboard.
5. Select "2-Software" on the terminal screen or press 2 on the terminal keyboard.



6. Select "1-Application" on the terminal screen or press 1 on the terminal keyboard.
This step is not available for the iPPXXX model, so if you have this model, go to "step 7".


7. Select "4-Telium SDK" on the terminal screen or press 4 on the terminal keyboard.



8. Review the information about SDK on the “Telium SDK” menu.




Terminal Reset Procedure


There are situations when the SDK version loaded onto the terminal is not compatible with the version of the payment application. In this case, you must reboot the terminal to its factory settings and clear all its contents, including the SDK.

To reset the terminal, follow these steps:

1) Make sure the terminal is turned on.
2) For iCTXXX, iPPXXX, iCMP, iSMP, iWL250 models, reboot the terminal by pressing the "-" and the yellow button.
For iSCXXX models, reboot the terminal by pressing '-' (for iSC250) or '#' (for iSC480) and the yellow button.
3) Press and hold the “F1” button as soon as the terminal starts rebooting until you see "*" symbol on the terminal screen.
4) For iCTXXX, iPPXXX, iCMP, and iSMP models, press the following sequence of buttons - "F4", "F2", "F3". When you press each button, a new "*" symbol will appear on the terminal screen.
For iWL250 models, press the following sequence of buttons - "F4", "Down", "Up". When you press each button, a new "*" symbol will appear on the terminal screen.
For iSCXXX models, press the following sequence of buttons - "3", "4", "6". When you press each button, a new "*" symbol will appear on the terminal screen.
Please note: The buttons will need to be pressed quickly!
5) Once the sequence of buttons is pressed properly, the terminal will reboot and automatically switch to LLT mode.
6) If the terminal does not automatically switch to LLT, repeat steps 1-4.


OS (SDK) Loading


To load the SDK onto the terminal, follow the steps below:

1) Verify that the terminal is plugged in and connected to the workstation.
2) Disable the firewall on the workstation, as it conflicts with LLT.
3) Unzip the file 05-OS.zip into the corresponding folder on the computer. 4) Launch the previously installed LLT application.



5) Double click the left mouse button on the terminal icon in the bottom right corner of the screen to connect to the terminal.



6) If the connection to the terminal has been established, you will see a list of files.



7) Open the "05-OS\1-OS" folder on the left side of the menu and "Manager\SWAP" on the right side of the menu. Drag the file from the left section into the SWAP folder on your computer.



Please note, the file extension will depend on your terminal model. The file is a descriptor which is associated with several physical files. This means that when you drag this file to the terminal section, you will see how it loads several files associated with it.

8) Double click the left mouse button on the terminal icon in the bottom right corner of the screen to disconnect the terminal from the workstation and finish loading SDK.



The terminal will reboot when the SDK has been loaded. Once rebooted, the terminal will display a language selection menu - English or Francais. Select English and press OK for each setting that will be asked for on the terminal screen. Ultimately, you will be taken to the main screen with the “LOAD AN APPLICATION” prompt.




Telium System Application (TSA) Loading


The Telium System Application (TSA) is required to work with encryption libraries.

To load TSA onto the terminal, follow these steps:
1) Verify that the terminal is plugged in and connected to the workstation.
2) Disable the firewall on the workstation, as it conflicts with LLT.
3) Launch LLT.
4) Unzip the file 06 - TSA.zip into the corresponding folder on your computer. 5) Turn on LLT mode on the terminal by choosing one of the following options:
a. Simultaneously press the Yellow button and “.” button in order to restart the terminal, and then immediately hold down the “Up” button.
b. Reconnect the terminal to the power supply in order to restart the terminal, and then immediately hold down the “Up” button.

6) Double click the left mouse button on the terminal icon in the bottom right corner of the screen to connect to the terminal.



7) If the connection to the terminal has been established, you will see a list of files.



8) Open the 06 - 2-TSA\2-TSA\SWAP folder on the left side of the menu and "Manager \ SWAP" on the right side of the menu. Drag the file from the left section into the SWAP folder on your computer.


Please note, the file extension will depend on your terminal model. The file is a descriptor that is associated with several physical files. This means that when you drag this file to the terminal section, you will see how it loads several files associated with it.

9) Double click the left mouse button on the terminal icon in the bottom right corner of the screen to disconnect the terminal from the workstation and finish loading TSA.



The terminal will reboot when the TSA has been loaded. After reboot, you will see a “TSA System Application” message on the terminal screen.




Injection Keys Loading


To activate Key Injection Mode, follow these steps:

1) After the terminal has rebooted, the “Key Injection” message will appear on the terminal screen. Select “2-COM PORT: USB” on the terminal screen or press “2” on the keyboard to switch to the USB connection.



2) Select “1-START KEY INJECTION” on the terminal screen or press “1” on the keyboard.



3) Press the green button on the terminal to activate Key Injection Mode.


Start the injection process on your workstation:

1. Unzip the 08 - TestUtility.zip file into the corresponding folder on the computer. The unzipped folder will have the following files: TestUtility.exe, PIN-DKPT.ini, PIN-DKPT.txt. 2. Run TestUtility.exe on your computer.



3. Select “File” -> “Open commands” in the top left menu.


4. Select the file "PIN-DKPT.ini" from the list.
5. Select "File" -> "Open script" in the top left menu.


6. Select the file "PIN-DKPT.ini" from the list.
7. Select “Device” -> “RS232” in the top left menu.


8. Change the COM port to the one through which the terminal is connected. Leave the rest of the settings as they are.



9. Click on the “Start” button to execute the script.



10. Review the Output window for the communication logging between the KIA and the terminal as necessary.

The terminal itself will restart once the process is completed.


To verify Key Injection, follow the below steps:

1. If your terminal model is iCTXXX, iPPXXX or iWLXXX, press the “F” button when the terminal is in standby mode.



If your terminal model is iSCXXX, press the “+” button when the terminal is in standby mode.



2. Select “1-TSA” on the terminal screen or press “1” on the keyboard. The “TSA” menu will appear on the terminal screen:



3. Select “4-DUKPT KSN” on the terminal screen or press “4” on the keyboard. The “DUKPT KSN” menu will appear on the terminal screen:



If the key was loaded onto the terminal, you will see its value in the corresponding slot. If the key is not present, you will see the "NO KEY" message.

4. To return to the TSA menu, press CANCEL, or wait one minute for the terminal to automatically return to the TSA menu.


EMV System Files Loading


To load EMV system files onto a terminal with an up-to-date SDK version, follow the below steps.

1) Verify that the terminal is plugged in and connected to the workstation.
2) Disable the firewall on the workstation, as it conflicts with LLT.
3) Launch LLT.
4) Unzip the file 09 - EMV.zip into the corresponding folder on your computer. 5) Double click the left mouse button on the terminal icon in the bottom right corner of the screen to connect to the terminal.



6) If the connection to the terminal has been established, you will see a list of files.



7) Open the "09 – EMV\4-EMV\SWAP" folder on the left side of the menu and "Manager \ SWAP" on the right side of the menu. Drag the file from the left section into the SWAP folder on your computer.



Please note, the file extension will depend on your terminal model. The file is a descriptor that is associated with several physical files. This means that when you drag this file to the terminal section, you will see how it loads several files associated with it.

8) Double click the left mouse button on the terminal icon in the bottom right corner of the screen to disconnect the terminal from the workstation and finish loading EMV files.



The terminal will reboot once the EMV system files have been loaded.


Terminal Application Loading


In this step, we are going to load the terminal application onto the terminal.
Please note, if you are using a Mockup terminal, a specially-modified application needs to be loaded onto the terminal. To receive such an application, please contact Gateway Support.

To load the SDK onto the terminal, follow these steps:

1) Verify that the terminal is plugged in and connected to the workstation.
2) Disable the firewall on the workstation, as it conflicts with LLT.
3) Unzip the file "10 - Uniread Application.zip" into the corresponding folder on the computer.
4) Launch the previously installed LLT application.
5) Turn on LLT mode on the terminal by choosing one of the following options:
a. Simultaneously press the Yellow button and “.” button in order to restart the terminal, and then immediately hold down the “Up” button.
b. Reconnect the terminal to the power supply in order to restart the terminal, and then immediately hold down the “Up” button.
6) Double click the left mouse button on the terminal icon in the bottom right corner of the screen to connect to the terminal.



7) If the connection to the terminal has been established, you will see a list of files.



8) Open the "10 – UniRead Application\SWAP" folder on the left side of the menu and "Manager \ SWAP" on the right side of the menu. Drag the file from the left section into the SWAP folder on your computer.



Please note, the file extension will depend on your terminal model. The file is a descriptor that is associated with several physical files. This means that when you drag this file to the terminal section, you will see how it loads several files associated with it.

9) Click the left mouse button twice on the terminal icon in the bottom right corner of the screen to disconnect the terminal from the workstation and finish loading the terminal application.

10) The terminal will reboot once the SDK has been loaded. Wait for the “Software Installation” window will to appear on the terminal screen. This will indicate that the installation application has begun installing the terminal application.



11) Enter the 3-digit Agent Code and press the green button on the terminal keyboard.



12) Enter the 6-digit password (when you press each button, a new "*" symbol will appear) and press the green button on the terminal keyboard.



13) Enter the terminal key (up to 16 digits) and press the green button on the terminal keyboard.



14) Once done, you will see a set of messages appear on the terminal screen:
- Running get-credentials...
- Done get-credentials.
- Running log-credentials...
- Done log-credentials.
- Running get-parameters...
- Done get-parameters.




15) If the terminal update is successful, you will see the “Success. The terminal will now restart” message.



If the update was unsuccessful, you will see one of the error codes.
16) Once rebooted, the terminal will begin the process of checking for additional updates. You will see the messages on the screen in the following order:
- Processing check update...
- Getting the updates...
- Getting update… etc.





17) The terminal will display the “Success. The terminal will now restart” message when the download is complete. The updates download process may occur several times.



18) Once the update is completed, the terminal will display the “Complete provisioning? Terminal key [] will be locked” message.



19) Click on the “OK” button to assign the earlier specified terminal key to the terminal.
Please note, when you press the “Cancel” button, the terminal will restart and return to the TSA Application screen, after which you will have to install the software again!

20) Once the provisioning process is complete, the terminal will display the “Please enter activation code (sent via email)” message. The terminal is ready for use and will be activated when the merchant enters the activation code.


Terminal Update


As a Terminal Processing Issues Manager, be sure that you have familiarized yourself with the following terms described above:
Repository Update version Update profile Update mode SDK

When working with terminals, all tasks related to transaction processing are executed by a payment application, while a manufacturer application executes the tasks related to the general terminal operation. Both a manufacturer and the gateway regularly release terminal updates, which include new features, enhancements for existing features, and fixes for bugs.

Terminal Applications


During the fulfillment process, a terminal gets an installation package uploaded. This package includes several applications. These applications are classified as manually uploaded, such as an installation application, and are automatically uploaded following the installation application, such as update, administration, recovery and processing applications. All applications must be signed. The applications are stored in files. The names of the files are numeric values consisting of a fixed code assigned by Ingenico and the terminal application version. For example, 8522570328.AGN, where 8522570 is the code assigned by Ingenico and "328" is the version of the application. In the application description below, a terminal application version is mentioned as xxx.
The list of the terminal applications looks as follows:

Installation application - executes a terminal’s initialization. Stored in the 8522620xxx.AGN file.
After being uploaded to the terminal with an installed OS, the application behaves as follows:

  1. Verifies whether the INSTALL.TAR archive is available allowing to perform terminal update.
  2. Creates internal folders used for file storage during the terminal operation.
  3. Creates a backup copy of the installation package for a recovery procedure. The copy is stored in the RUPDATE.TAR file on the E_RECOVERY disk. This file is used for storage of the relevant terminal applications and is updated during the terminal update.
  4. Unpacks the installation archive and installs the Update and Administration applications.
  5. After a user enters an agent code, agent password, and a terminal key, submits an API call to the TMS server.
  6. Removes itself from the terminal and resets it.

Update application - executes submission of get-update request. Stored in the 8522600xxx.AGN file.
After being uploaded to the terminal, the application behaves as follows:
  1. Archives the files of a current update prior to the update process and unpacks the archive during the recovery process.
  2. After a list of the update tasks is received, passes application management to the Administration application. If the list of the update tasks was initially empty, passes application management to the Processing application.

Administration application - executes files upload from a repository to a terminal, executes terminal updates, and sends terminal logs to the TMS server. Stored in the 8522590xxx.AGN file.
After being uploaded to the terminal, the application behaves as follows:
  1. Copies unreachable files to the disks. Obsolete files with the same names are overridden.
  2. Forms a RAM disk to prepare the installation of the executive files and libraries.
  3. Calls the system function to start the installation of the executive files.
  4. If the previous steps are performed successfully, sends terminal logs to the TMS server and passes application management to the Update application. If an error occurred during the previous steps, follows the same procedure, but the application management is passed to the Update application with the status indicating that update rollback is required. If there are any issues with the executive files, which cause a conflict between the versions of the applications, a recovery of the terminals must be performed.

Recovery application - executes recovery. Stored in the 8522610xxx.AGN file.
After being uploaded to the terminal, the application behaves as follows:
  1. Unpacks the RUPDATE.TAR archive.
  2. Forms the installation package.
  3. Resets a terminal.

Processing application - executes transaction processing and all associated processes, runs scheduled services, manages terminal parameters, etc. Stored in the 8522570xxx.AGN file. Available only when a terminal is updated.


Terminal Application Update Steps


Terminals are updated automatically. However, to allow for a terminal to be updated, you should follow a list of preliminary steps to set a series of necessary configurations.

The procedure of the terminal application update is as follows:

  1. Create a repository.
  2. Prepare a terminal update.
  3. Upload the update to the repository.
  4. Create an update profile.
  5. Assign a terminal update version to the profile.
  6. Assign the update profile to the terminal.

To allow for this procedure, follow these steps:

1. Before creating a repository, prepare the files that must be uploaded to it. To guarantee its integrity and successful identification, every file must be preceded with a hash (#) symbol. Use the MD5 algorithm for this.

Below are the files and pattern names that must be included in the base update:
8522570315.AGN - current terminal application version; PCLOUD.CRT - certificate for the cloud server; PGATEWAY.CRT - certificate for the gateway server; PTERMINAL.KEY - key for the terminal’s internal certificate; PEMV.PAR - configuration used for processing contact EMV transactions; PCLESS.PAR - configuration used for processing contactless EMV transactions; PDISPLAY.PAR - description of the terminal parameters menu; XBUTTONS.TAR - archive with colored button images; XIMAGES.TAR - archive with images shown on the idle screen; XRSAPUB.KEY - RSA public key used for card data encryption when submitted to the server. This key is used either for encrypting data internally via P2PE or externally via TransArmor. This file is optional.
2. For the prepared update files to be uploaded to a terminal, they must be preliminarily uploaded to a repository. The repository is created once for each portfolio. To learn how to create a repository, review this tutorial.
3. To assign and upload the terminal update to the group of terminals with identical settings or features, create an update profile or a segment under an existing profile if the update must be uploaded to one or several specific terminals within one feature group. To learn how to create an update profile, review this tutorial.
4. Assign the update profile to the terminal. To learn how to assign the update profile to the terminal, review this tutorial.
5. Upload the update to the repository created in step 2. To learn how to upload the update, review this tutorial.
6. Assign an update version to the update profile. To learn how to assign the update version to the update profile, review this tutorial.
After all the steps above are complete, the update is available for downloading by the terminal. This process is performed automatically via the get-update API call, which is submitted daily at 4 am. After the request is submitted, the TMS server returns a response, which consists of the files that have been prepared for uploading via the update profile. After all, files are downloaded successfully, the terminal sends a summary log, and the update is recorded within the system. The process is identical for every terminal update.
During the update process, there can be situations that require additional actions. Below you can find examples of these situations and the ways to resolve them.


Complementary Update Tasks


Assigning Segment for a Terminal Group

Sometimes there is a need to fix a particular feature for a specific group of terminals that have already been updated (for example, issues with processing EMV contactless transactions). In this case, it is necessary to separate this group. For this scenario, you must isolate terminals in a sub-group, or so-called, segment. Thus, you will avoid causing issues with a larger number of terminals after the fix is applied, and, therefore, higher expenses on debugging. When terminals are segmented, assign and upload one particular update version.

To learn how to assign a particular segment to a terminal, review this tutorial.

SDK Update


A terminal manufacturer, such as Ingenico, provides an OS based on its SDK. Occasionally, the manufacturer releases necessary updates for the SDK to improve and fix possible issues with terminal operation.

The process of an SDK update is similar to the process of updating the payment application. Use a current update profile to perform the SDK update. At the moment, the version of SDK on Ingenico terminals is 9.32.3.

Urgent Terminal Update


There can be situations when a terminal needs to upload an available update sooner than it is scheduled (at 4:00 АМ). For urgent updates to a terminal, perform a restart. When the terminal is turned on, it will check whether a new update is available. If any, the terminal will upload the update as described above.

Rollback of a Terminal to the Previous Update Version


Sometimes, after a new terminal update is uploaded, issues with the terminal operation can emerge. One of the solutions to resolving these issues is a rollback of the terminal update to the version, under which the terminal last operated correctly. This can only be done for the payment application as the SDK can’t be rolled back. Additionally, if it is necessary to make a rollback to the version that has a segment assigned, you must assign a segmented update profile prior to the rollback.
To learn how to perform terminal update rollback, review this tutorial.

Appendix 1 - QA Procedures for Terminals


After a terminal is updated, you should test its functionality following recommended procedures. Review the QA procedures in this appendix.

Recovery Procedure


As a Terminal Processing Issues Manager, be sure that you have familiarized yourself with the following terms described above:
Recovery Base version Payment application TMS Agent code Activity & Diagnostics logs

In some cases, remote management of a terminal is not possible due to some issues. For example, there is no possibility to change terminal parameters or upload a terminal update. To fix these kinds of issues, a procedure allowing users to reset the terminal and roll it back to a base version of a terminal application is used. The base version is uploaded to the terminal during the fulfillment process, and is guaranteed to be stable. For this reason, the rollback to this version ensures that the terminal will have connectivity. When connectivity is restored and the terminal can be managed, it is possible to upload a relevant update. The process of rolling back to the base version is called recovery. During the recovery process, all applications are removed from the terminal and a new update profile is set and uploaded.

Before making the decision to recover a terminal, try to identify what the issue is by yourself to make sure that recovery is actually necessary. To do that, analyze the activity and diagnostics logs to obtain information about the terminal’s activity over a certain period of time prior to losing connection with the TMS server. If neither the activity or diagnostics logs help identify the issue, you can run remote debugging.
To learn how to locate terminal logs, review this tutorial.

Perform terminal recovery following these steps:

1. Change the status of the terminal to “In Fulfillment” via the user interface. To learn how to change terminal’s status, review this tutorial.
2. Verify terminal’s profile is set correctly via the user interface. To learn how to verify terminal’s parameters. review this tutorial.
3. Access the system menu of the terminal. To access the menu, press either F or + buttons.

4. Enter system PIN. As a rule, the format of the PIN is a current date (DdMm) in reverse order (dDmM). For examples, if the current date is July 10th (07/10), the PIN is “0170”.



5. In the opened menu, select Recovery.


6. Enter a passcode and press the OK button. To get the passcode, contact gateway support.


7. If all steps have been executed correctly, the recovery process will run. After recovery is completed, a corresponding message will be shown on the terminal’s screen.



8. After recovery, the terminal will be restarted. Once this is complete, enter the values below to connect the terminal to the TMS server and download the latest update:
  • Agent code (requested from support).
  • Agent password (requested from support).
  • Terminal Key (the combination of MID and TID available at the user interface).

9. When the terminal is updated, you can see the message "Terminal will be locked" on the terminal’s screen. Once you see the message, press the OK button.

10. Enter a new activation code and press OK. The activation code is generated automatically when the terminal passes “In Fulfillment” status and is available under the terminal details on the Terminal perspective.
Copyright © United Thinkers. (UniPay - Payment Gateway Software)
All Logos and Trademarks used or mentioned on this page are copyrighted property of their respective owners and are used for display purposes only.