TSI is the term used to identify the interface that TruService exposes to TruModule instances.

TruService is accessed over an HTTP, or HTTPS connection using TLS, normally on port 443.

Message exchanges with TruService always follow a Request / Response pattern – where the Request is always sent by TruModule.

Each message exchanged is provided with a message authentication code (MAC) that verifies the origin of the message. Instructions for the generation of the MAC are available through the TruRating developer portal.

Messages are formatted in Xml. Xsd schema files are provided by TruRating to facilitate development, validate the output and provide the full specification for the messages elements.

TSI message types

All messages sent to TruService are contained within a Request parent element that contains a set of mandatory data attributes that TruService uses to identify the origin of the message. This data includes:

Attribute Description
PartnerId The partner ID of the originating system that is running this TruRating implementation
MerchantId The Id of the merchant outlet running the TruRating application. This may or may not be the same as the acquirer MID - it must simply be a value known to the merchant (so that it can be registered with TruRating) and available to TruModule.
TerminalId The Id of the payment terminal or point of sale system running TruModule. This may or may not be the same as the acquirer TID - it must simply be a unique value (within the merchant outlet) available to TruModule.
SessionId A unique value (for this TerminalId) that identifies this customer transaction

Within each Request Id are sub elements that are relevant to the request being made. Some of the key sub element types include:

Messages relating to activation (TLA) and activation control

Element type Description
Query Requests the activation status and activation code of the TruRating application for this merchant outlet.

NOTE: Activation via TLA requires support for TruService schema 2.3.0 or above. Activation through a deprecated mechanism (Merchant Led Activation) is still supported via version 2.2.0 of the TruService schema for existing integrations only.

Messages relating to questions and ratings

Element type Description
Question Requests a question. Must provide device capabilities and language requirements
Rating Delivers a rating record. A transaction record may be a sub-element of this rating.
Transaction Delivers a transaction record independently of a rating record.
PosEvent Forwards an event notification that has been received from the POS.

A typical TSI message exchange

Samples of the TSI XML messages are provided here.

The message exchanges that occur during a typical transaction follow the pattern illustrated below.
(Clicking on any message links to the relevant section that describes it).

  • Module requests a question from TruService ;
  • TruService responds with a question ;
  • TruModule sends a Rating and Transaction Details ;
  • TruService responds with a simple acknowledgment.
Typical message exchange
Typical TSI message exchange during a customer transaction that includes a TruRating question

XML message sequence

The sequence of elements sent to TruService is important, the following tables indicate the possible sequencing combinations:

The Transaction element must be the last element sent to TruService in any given session. If this element isn’t received or received in the wrong order, dataloss may occur.

N.B. “Max Requests” denotes the maximum number of requests of a particular type that will be accepted by TruService in a given session. If the limit is exceeded, an error will occur. n denotes unlimited.

TSI 2.0.0

Element type Ordinal Max Requests
Question 1 1
Rating 2 1
Transaction 3 1
Element type Ordinal Max requests
Question 1 1
Rating + Transaction 2 1

TSI 2.1.0

Element type Ordinal Max requests
PosEvent 1 n
Question 2 1
PosEvent 3 n
Rating 4 1
PosEvent 5 n
Transaction 6 1
Element type Ordinal Max requests
PosEvent 1 n
Question 2 1
PosEvent 3 n
Rating + Transaction 4 1
Element type Ordinal Max requests
Question 1 1
PosEventList 2 1
Rating 3 1
Transaction 4 1
Element type Ordinal Max requests
Question 1 1
PosEventList 2 1
Rating + Transaction 3 1

TSI 2.2.0

** Same as TSI 2.1.0 except with the following additions

Element type Ordinal Max requests
Query 1 1
Element type Ordinal Max requests
Activate 1 1
Element type Ordinal Max requests
Lookup 1 1

TSI 2.3.0

** Same as TSI 2.1.0 except with the following additions

Element type Ordinal Max requests
Query 1 1
Feedback