TruModule is the component of a payment or POS application that connects to TruService in order to provide TruRating services at a point of sale (POS).
TruModule is designed and developed by the developers of the parent application.
To ensure that the development of TruModule is as straight forward as possible, along with the specifications, TruRating provides a set of example implementations in different languages that may be used as required.
The core requirements of a TruModule implementation are:
Support the XML over HTTP message connections to TruService, including forwarding any POS event messages that may be available from the payment application’s POS interface
Listen for trigger events or API calls within the POS/payment system and invoke a TruRating question in response to a specified question trigger (e.g. when payment or refund transaction occurs, when basket scanning commences, etc)
Connect to TruService to request a question, acknowledgement & receipt text in either a single or multiple languages
Use the Payment Application’s driver for the PIN entry device (PED) to ask the question (1AQ1KR) and afterwards to display an acknowledgement on the PED
Where multiple languages are supported provide a means to either intelligently select the correct language for the customer or provide a mechanism to allow the customer to select or change language. More information can be found in the multilanguage specification
Capture the rating returned and associate it with details of the transaction and any other data (such as basket data) received from the POS where supported
Deliver this rating record to TruService
Pass any TruRating receipt text back to the Payment Application/POS for inclusion on the customer receipt
Periodic status checking & activation support when Terminal Led Activation is supported
Follow guidance provided on communicating with TruService that can be found here
The full set of functional requirements for TruModule are listed in the TruModule specification.
Partner ID (PID), Merchant ID (MID) & Terminal ID (TID)
All communication between TruModule and TruService requires these three elements to be exchanged. These elements are used by TruModule to identify the partner, the merchant outlet and to identify the terminal or POS within the outlet. In turn these elements are used by TruRating to ensure that the correct rating questions are asked and that the rating & transactions that are received from TruModule appear correctly on the merchant dahboard and our reports.
Partner ID (PID)
- The Partner ID (PID) is issued by TruRating to each partner during the integration phase
- The PID is always unique to each partner
- The PID is a numeric value (e.g. 1234)
- In some situations a partner may be issued with multiple Id’s in situations where a greater dgree of merchant seperation is requested
Merchant ID (MID)
- The Merchant ID (MID) is defined or managed by TruModule, it is not supplied by TruRating
- MID should primarily be alphanumeric
- It can use some special characters – most notably the dash (-)
- If at all possible all other special characters should be avoided, including: Exclamantion Mark, Single Quote, Double Quote, Hash, Dollar, Percentage, Ampersand, Braces, Brackets, Greater/Less Than, Plus, Comma, Forward Slash, Backslash, Colon, Semi-Colon, Equals, Question Mark, Square Brackets, Tilde
- The MID must be unique across all merchants and outlets that share the same PID. Often the store number is used to create the MID and where the store number is not unique across all merchants it’s combined with the merchant name or a shorthand version of the first line of the outlet address to make it unique
Terminal ID (TID)
- The Terminal ID (TID) is defined or managed by TruModule, it is not supplied by TruRating
- The TID is expected to be an alphanumeric identifier for the payment terminal or POS within the outlet that is processing the rating
- As with the MID, special characters should be avoided
- The TID must be unique within a single outlet
Please contact the TruRating technical team with any questions relating to these identifiers, especially where exceptions on the guidance around MID and TID formatting is needed.