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.
|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:
|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"> <PosEventList> <StartTransaction AttendantType="ATTENDED" OperatorId="James" SalesPersonId="Toby" TillType="STANDARD" /> <StartTilling/> <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> </Item> <EndTilling SubTotalAmount="1000"/> <EndTransaction /> <Customer Type="Customer">1001#1#Y#1002#4#GOLD</Customer> </PosEventList> </Request>