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.
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:
*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).
| 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.
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:
Note:
Currently, the following values are supported:
- #initialized - terminal can pass this value to notify TMS that the terminal has been initialized.
- #ininjection – terminal can pass this value to notify TMS that the certificate has been signed.
- #provisioned - terminal can pass this value to notify TMS that the terminal is initialized and ready for activation by a merchant.
- #active - terminal can pass this value to notify TMS that the terminal has been registered and activated.
- #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:
- hashtag symbol (#) should be passed as URL-encoded value, otherwise the operation will get failed. See integration notes for more information.
- such statuses as #initialized and #ininjection are used for Sunmi terminals only. The #provisioned status is used both for Sunmi and Ingeniko terminals.
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:
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.
- 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.
The following table is Services menu, which is available at F1 -> 7 button in Ingenico and 1 -> 7 button in Verifone terminal menus.
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 | ||
|---|---|---|---|---|
| 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 |
| F3 | 3 | - | - | Credit |
| 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 |
|---|---|---|---|
| 1 | Run merchant-info | x | x |
| 2 | Run log-state | x | |
| 3 | Run get-credentials | x | x |
| 4 | Run get-parameters | x | x |
| 5 | Run get-update | x | x |
| 6 | Run get-time | x | x |
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.
The rest of TMS API operations are run manually. To learn in which cases such operations can be run, see the table below.
| Operation | Frequency | Description |
|---|---|---|
| Get Parameters | Runs every hour (e.g. at 9:00; 10:00, 11:00, etc) and when a terminal gets restarted. | Retrieves terminal parameters from the server. |
| 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 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 when a terminal gets restarted and with each void if macValue is invalid. The key is received in response automatically after processing every 200 transactions or earlier if a response notifying about a new key is retrieved from a processor. |
Retrieves MAC key. |
| Runs when a terminal gets restarted. The key is received in response automatically every 18 months. |
Retrieves 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. |
Profile Data
The merchant-info request will provide a complete list of 'processor MID' and 'processor TID' associated with the given profile. This feature was added to check all MIDs and TIDs configured for the industries of this profile. This list is transmitted in the ‘profileData’ field using JSON format. Each MID and TID pair is stored as separate objects grouped by industry.
Example of ‘profileData’ in JSON format:
[
{
"configurations": [
{
"merchantId": "290000111",
"industry": "retail",
"terminalId": "12345678901"
},
{
"merchantId": "290007000",
"industry": "moto",
"terminalId": "29000700002"
},
{
"merchantId": "2900070003",
"industry": "ecommerce",
"terminalId": "290007000023"
}
],
"type": "cards-realtime/elavon-eu"
}
]
Example of ‘profileData’ in JSON format:
[
{
"configurations": [
{
"merchantId": "290000111",
"industry": "retail",
"terminalId": "12345678901"
},
{
"merchantId": "290007000",
"industry": "moto",
"terminalId": "29000700002"
},
{
"merchantId": "2900070003",
"industry": "ecommerce",
"terminalId": "290007000023"
}
],
"type": "cards-realtime/elavon-eu"
}
]
Copyright ©
TidyPay. All Rights Reserved.
All Logos and Trademarks used or mentioned on this page are copyrighted property of their respective owners and are used for display purposes only.