In some situations, there may be a requirement or opportunity to provide TruRating with some information about the customer or the customers transaction that is not accommodated within the core of the TruService schema. This information would be provided to TruRating in addition to the standard transactional information being collected. An example might be a flag to indicate if the transacting customer is a loyalty customer, another example might a POS specific or merchant specific customer type identifier. The result being that TruRating can provide enhanced analytics and custom reports to merchants or partners based on this additional information.

Given that the range of data potentially available will vary significantly between partners and merchants the TruRating schema supports a free format string field that allows TruModule to present this type of data w to TruService within a RequestCustomer object which is one of the child objects of POSEvent and POSEventList.

To support some degree of conformance across implementations, whilst avoiding frequent changes to the TruService schema a simple TLV (Tag, Length, Value) structure has been created and is documented below along with examples on its application and usage

NOTE: No personal data relating to the customer will be shared with TruRating through this interface.

Structure and Pre-Defined TAG List

A field separator of ‘#’ is used to make the TVL data more human readable.

Field Length Description
TAG Variable A pre-defined or pre-agreed identifier for the data being submitted to TruService. This is provided as a free format string. See below for current list of pre-defined tags
LENGTH Variable The number of bytes in the VALUE field that contains the data element related to the tag, expressed as a Non-negative integer
VALUE Defined by LENGTH The data for the tag expressed as a UTF-8 encoded text string except in situations where TAG indicates a binary field, in which case the value is expressed as an array of 2-byte hex values (i.e. 3031323334)

Where two or more pieces of data are being submitted to TruService then a single concatenated string will be used.

Recognised TAG Types

TAG Identifier TAG Name TAG Type Description
1001 Loyaly Customer Indicator Boolean A boolean indicator that informs TruRating if the customer providing the rating is a loyalty customer or not. Accepted boolean values are: “Yes/No”, “True/False”, “Y/N”, “T/F”
1002 Loyalty Customer Type UTF-8 String A merchant or partner specific identifier for the loyalty customer type. This might indicate what type of loyalty card as customer has or the customer loyalty scheme level (Bronze, Silver Gold member)
1003 Hashed Loyalty Card UTF-8 String A SHA-256 hash of the customers loyalty card
1020 Customer Type UTF-8 String A merchant or partner specific identifier for the customer type that has been determined through some mechanism other than a customer loyalty programme
1021 Customer Demographic UTF-8 String A merchant or partner specific identifier for customer demographic

NOTE: Please contact the TruRating technical team to discuss adding support for additional tags.


Some examples of usage:

Example Description TLV Data
1 Customer is a loyalty card holder and has Gold status 1001#1#Y#1002#4#GOLD
2 Customer is not loyalty card holder but has been identified by the POS system that they are a Premier shopper 1001#2#No#1020#7#Premier

An example of an instance of POSEventList with customer data included:

<?xml version="1.0" encoding="UTF-8"?>
<Request PartnerId="1" MerchantId="2" TerminalId="3" SessionId="2349572348" xmlns="http://docs.trurating.com/schema/truservice/v210.xsd">
    <StartTransaction AttendantType="ATTENDED" OperatorId="James" SalesPersonId="Toby" TillType="STANDARD" />
    <Item  Quantity="1" Description="A description" RetailAmount="1000" SellingAmount="1000" Sku="a stock keeping unit" UnitMeasurement="KG" Operation="ADD">
      <Barcode Type="SYMBOLOGY"><![CDATA[asdfjansdkjfnaskjdfnaksjdnfkjasdnfkjasndkjansfdkjansdkjfnaskjdfnkj]]></Barcode>
    <EndTilling SubTotalAmount="1000"/>
    <EndTransaction />
    <Customer Type="Customer">1001#1#Y#1002#4#GOLD</Customer>