TMS APIs



Integration Notes


Contactless Mode  

EMV cards can be processed using both ICC (integrated card circuit) and contactless technology. When a card is processed via ICC, it is physically inserted into a terminal. In the second case, it is processed by a tap.

When both ICC and contactless technologies are available in the context of a transaction and supported by a terminal and a card, the following issue may arise: card data can be read by a contactless antenna, even when ICC transaction is intended to be made. This happens due to the close placement of an ICC-reader to the reception zone of a contactless card reader. To avoid such situations, when a transaction is processed and both ICC and contactless modes are available to a card holder, the system supports a special mechanism that controls whether the contactless mode is enabled or not. When a cardholder wants to process a transaction as contactless, the respective mode can be activated by pressing 0 button on a terminal keypad while running an operation. In this mode, built-in contactless antenna gets activated and reads card data once a payment card is brought into antenna zone. To deactivate contactless mode, 0 button has to be pressed once again.

Note that if terminal entry mode is submitted within API request as contactless or as contactless and manual, the contactless mode will be activated on a terminal automatically.

Cross-reference Fields  

The system provides an ability to specify values that can be used for cross-referencing of entities between the gateway and a submitter’s system. The fields that can be provided by an integrated external system are listed below:







Entity Field Name Description
Ticket ticketNumber* Identifier of a ticket assigned by a POS system.
ticketId* Identifier of a ticket generated by a terminal.
Item itemNumber* Identifier of a item assigned by a POS system.
itemId* Identifier of a item generated by a terminal.


*Fields ticketNumber/ticketId and itemNumber/itemId can be used subsequently as a reference in the operations designed to update tickets (close-ticket) and update items (update-item, remove-item).

Get Resource Response  

The content of the response for get-resource operation is the content of the files that terminal attempts to download from the TMS. To help you with the download process, the following HTTP headers will be set:
  • Status-Code, most common values: 200 – resource was found and content can be read or 404 – resource was not found;
  • Content-Type - identifies the content type of the file being served;
  • Content-Length - identifies the length of the file delivered.

Password Encoding  

If passwords, as well as other fields, contain special characters (#, @, % etc.), the value of the fiels must be URL encoded.
For example, if the password is: 'Pa$$word', the URL encoded version of this password should be: Pa%24%24word.
For more information please read this article.

System Message  

For cases when it is necessary to pass control information from a terminal to the TMS, systemMessage field is used.

Currently, the following values are supported:
  • #provisioned - terminal can pass this value to notify TMS that primary initialization process of a terminal has been completed.
  • #restart - terminal can pass this value to notify TMS that a registered terminal has performed an unplanned restart. The format of this message is the following: #restart(yyyyMMddHHmm,U), where yyyyMMddHHmm is a date and time of restart, and U indicates that restart was unplanned.

Note that hashtag symbol (#) should be passed as URL-encoded value, otherwise the operation will get failed. See integration notes for more information.

TMS parameters  

Terminal application behavior is controlled by a series of parameters, which are managed by the TMS. The terminal parameters get synchronized with the terminal both automatically and manually:
  • automatic synchronization occurs on the regular basis (every hour) by calling get-configuration operation;
  • manual synchronization occurs when the Parameters menu is opened on the terminal.

When the terminal is used, a user can review or manage the TMS parameters via the Parameters menu. Some parameters cannot be changed due to being set as read-only at the TMS level. Such parameters are sent to the terminal with @@ prefix included and cannot be modified at the terminal level.

To access the menu, manager PIN is required. In case if terminal services (such as get-credentials, get-time, get-parameters, get-update) are needed to access, administrator PIN is required.

See the following table to review a full list of the terminal parameters.

Terminal Code  

When provisioning terminals in the portal, you have the ability to enter a 3-digit, numerical terminal code. This terminal code is passed in all API requests to identify the transaction’s target device. As such, it’s important that these terminal codes be tracked within your system. If you do not enter a terminal code, one will be assigned automatically. Each terminal will have a sticker which displays the terminal’s key, a numerical identifier which is comprised of the concatenated account code and terminal code. When a terminal arrives at its destination, the recipient should have the ability to register the device within your software, using the terminal code or key. We recommend that you enter the terminal in your database when you first provision it, making sure to include the terminal code and its related account code. This will allow you to associate the terminal with its recipient upon registration.

Terminal Hot Keys  

Terminals of ICT, IPP, IWL, ISC Touch (Ingenico) and MX915, MX925 (VeriFone) models have special function buttons. They can be used to simplify an interaction with the terminal. You can use tables below as the reference to understand how the buttons are programmed in any of the terminal modes. Also, with these hot keys, you can quickly access a particular function that you need by pressing keys on the terminal keypad, as opposed to making selections within the terminal menus, which might be more time consuming.
Note: F1->[number] implies subsequent pressing of the key. For example, F1->7->1 means F1 is followed by 7, and 7 is followed by 1 on the terminal keypad.

Ingenico/Verifone
























Button Cloud Standalone Attached
(Ingenico Only)
Ingenico Verifone #
F1 1 0 - Sale -
1 - Credit -
2 - Void
3 - Clear Batch
4 - Capture
5 - Close Batch -
6 - Balance Inquiry
7 Services
8 Parameters
9 Diagnostic
F2 2 - - Sale Fetch
F3 3 - - Credit Fetch
F4 4 - - Void
F->Recovery
Note: System PIN
is required to
gain access to
Telium system
menu and Recovery
menu item.
0+-<
pressed
simultaneously

Note: Combination
must be held
for 7 seconds.
- Recovery -

Services

The following table is Services menu, which is available at F1 -> 7 button in Ingenico and 1 -> 7 button in Verifone terminal menus.
Button Menu Services Cloud Standalone Attached
1 Run merchant-info x x x
2 Run log-state x
3 Run get-credentials x x x
4 Run get-parameters x x x
5 Run get-update x x x
6 Run get-time x x x

Supported Terminals and Technical Standards  

Terminal characteristics may vary depending on a terminal model. Some of the terminal standards for Ingenico and Verifone terminals are listed below.

Ingenico




Model Resolution Chars per Line Connectivity Color Display Touch Screen Receipt Printer ICC* NFC**
iCT220 128x64 20 Ethernet x x
iPP320 128x64 20 Ethernet x x
iCMP 128x64 20 Bluetooth x x
iSMP 128x64 20 Bluetooth x x
iSMP4 320x240 30 Bluetooth/Wi-Fi x x x
iCT250 320x240 30 Ethernet x x x x
iPP350 320x240 30 Ethernet x x x x
iWL252 320x240 30 Bluetooth/Wi-Fi*** x x x x
iSC250 480x272 35 Ethernet x x x x
iSC480 640x480 35 Ethernet x x x x

Verifone



Model Resolution Chars per Line Connectivity Color Display Touch Screen Receipt Printer ICC* NFC**
MX915 480x272 35 Ethernet x x x x
MX925 800x480 35 Ethernet x x x x
*ICC (integrated circuit) - functionality, required for contact EMV processing.
**NFC - functionality, required for contactless EMV processing, proximity payments, Apple Pay and Android Pay.
***iWL252 is connected to a base through Bluetooth/Wi-Fi, however, a base is connected through Ethernet.

Operations Frequency  

Unlike other APIs, operations of the TMS API get executed mostly automatically. To learn how often and at what time automatic operations are run, see the table below. Note that the given time corresponds to the terminal time.

Operation Frequency Description
Get Credentials Runs every 5th day of the month at 04:15 АМ. Changes a terminal password (requests are submitted simultaneously).
Log Credentials
Get Configuration Runs every hour (e.g. at 9:00; 10:00, 11:00, etc) and when a terminal gets restarted. Retrieves terminal parameters and EMV (contact/contactless) configurations.
Get Time Runs at 3:20 АМ and when a terminal gets restarted. Retrieves server time to synchronize it with a time of a terminal.
Get Update Runs at 4:00 АМ and when a terminal gets restarted. Checks whether new terminal updates are available.
Log Diagnostics Runs at 4:30 АМ and when a terminal gets restarted. Sends terminal diagnostics information to the server.
Upload Log Runs during diagnostics and when a terminal gets turned on or restarted. Uploads a terminal log to the server.
Log State Runs when a terminal gets turned on or restarted. Sends various information to the server (notifications about provisioned terminals, planned/unplanned restarts, etc).
Get Key Runs during transaction processing, when there is a response notifying about a new key and when a terminal gets restarted. Retrieves a MAC/P2PE key.
The rest of TMS API operations are run manually. To learn in which cases such operations can be run, see the table below.
Operation When can be run Description
Activate Terminal During a terminal’s activation. Activates a terminal.
Set Parameters After modification of terminal parameters on a terminal. Saves changes done via a terminal on the server.
Get Resource During the update. Retrieves a particular resource during the update process.
Log Update State During the update. Logs data associated with the update.