TruModule is the component built into a customer transaction environment that is responsible for presenting a TruRating question, capturing the customer's response, together with a summary of the transaction data, and delivering it all to the TruRating application service (TruService).

Outline

TruModule must meet the following requirements:

Requirement Id Objective Description
TMOD_REQ_01 Connect to TruService The TruService application is responsible for providing the TruModule with the data it needs to run, and receiving the results at the end of each transaction. TruModule must, therefore, maintain a connection with TruService in order to achieve this, including the correct formatting and parsing of messages. TruModule must automatically re-connect to TruService if connectivity is lost.
TMOD_REQ_02 Confirm and maintain activation status TruModule on startup must retrieve the activation status from TruService and must then operate based on the activation status returned. TruModule must re-confirm the activation status periodically with TruService based on the ‘time to live’ value sent by TruService.
TMOD_REQ_03 Present a question on the PED TruModule must be able to present a TruRating question on the PED and to capture the response provided by the consumer. The question returned from the TruService will be formatted to match the display requirements of the device - based on various properties such as the device type and firmware version, declared with a question request.
TMOD_REQ_04 Present a rating acknowledgment message Following the completion of the question (1AQ1KR) command, the TruModule should display the appropriate acknowledgment message received from TruService on the PED. The message chosen will depend on whether the consumer provided a rating or not.
TMOD_REQ_05 Fail gracefully If TruService is unavailable or does not respond within 250ms, TruModule should return control to the controlling application to ensure any POS or payment activity is not blocked.
TMOD_REQ_06 Capture POS events and data Events may be sent from the POS system directly or via the payment application and propagated to TruModule. The TruModule must be able to use these events to trigger a question, (as configured) and forward the event data to TruService.
TMOD_REQ_07 Cancel the question prior to card payment processing If the question is still present when a payment request is made, when the transaction completes or when the payment device is required for another service, then the TruModule is responsible for clearing it to allow payment to proceed uninterrupted. In the case where a question is present when the customer or attendant wish to tap or swipe a card in order to trigger a card event, the question must first be cleared manually by hitting a numeric key or the cancel key.
TMOD_REQ_08 Deliver a receipt message to the POS / Payment application TruRating provides a message to be added to the receipt to back up the rating question, and occasionally record a prize code. If the question was asked during dwell time, then this message should be returned to the POS to include on the customer till receipt. If the question was asked in response to a payment event, then the message may be added as a custom field to the transaction response dataset. The nature of the receipt message depends on whether the consumer provided a rating or not. TruService, therefore provides two versions of the receipt message (normally returned with the question delivery). TruModule needs to select the appropriate version and return it to the POS/payment application
TMOD_REQ_09 Capture transaction data The rating collected must be associated with a set of transaction data, including the amount and result. The full set is available in the TruService interface specification.
TMOD_REQ_10 Relay PED capabilities to TruService TruService formats questions and acknowledgments based on terminal capabilities, such as screen height or width and whether the font used is mono spaced or proportional.
TMOD_REQ_11 Load core TruRating runtime configuration * PartnerId - Assigned by TruRating
* MerchantId - Assigned by PSP or Merchant
* TerminalId - Assigned by PSP or PED Estate Owner
* SessionId - Assigned by POS Application or payment application (depending on configured question scenario)
* TruService API endpoint address - Assigned by Merchant
* Configured question scenario - Assigned by Merchant
TMOD_REQ_12 Support TLA In environments where the activation of TruRating is being done via Terminal Led Activation (TLA) then TruModule must incorporate support for TLA as defined within the TruRating specifications.

Detail

A TruModule implementation will implement a subset of the following functional requirements. Some of these functional requirements are mandated for any implementation while others are optional depending upon the type of implementation and the level of features to be supported. Each major functional requirement is listed below along with a short summary as to whether or not the requirement is mandated (M) for all implementations of TrtuModule or optional (O).

Dwell Time Extend rating (O)

When to implement?

This requirement should be implemented in situations where the TruRating question is required to appear during dwell time, including the ability to delay the end of dwell time to allow the customer time to rate. An implementation of TruRating must implement at least one trigger type, but is not limited to a single trigger.

Requirements

  1. Trigger the rating process during basket scanning:
    • Where POS events are being passed to TruService then TruService can notify the availability of a question in response to a POS event - thus triggering the rating process
    • Where POS events are not being passed to TruService then a POS or middleware application would use the first item added to the basket or some other key event that indicates a new transaction has started as the trigger
  2. Delay the cancellation of the rating question at the end of dwell time for a configurable number of seconds as defined by TruService.

Rate on Payment Request (O)

When to implement?

This requirement should be implemented in situations where the TruRating question is required to appear at the start of card payment. An implementation of TruRating must implement at least one trigger type, but is not limited to a single trigger.

Requirements

  1. Trigger the rating process at the point at which a card payment is about to commence, but ahead of the customer being asked to or / actually presenting their card
  2. For POS applications and middleware applications implementing TruModule, this would generally be ahead of issuing the card payment request to the Payment application
  3. For Payment applications, this is generally at the point of receipt of the payment request from the POS or middleware application

Rating at Amount Finalised (O)

When to implement?

This requirement should be implemented in situations where the TruRating question is required to appear at the point at which the transaction or amount finalised has been confirmed. An implementation of TruRating must implement at least one trigger type, but is not limited to a single trigger.

Requirements

  1. Trigger the rating process at the point at which a card payment is about to commence and the merchant or customer has finalised the amount following the completion of any payment specific activities which may affect the tender amount (loyalty, gratuity, other adjustments)
  2. The rating process is done ahead of the customer presenting their card

Rating at Card Presentation (O)

When to implement?

This requirement should be implemented in situations where the TruRating question is required to appear at the point at which the customer has presented their payment card. An implementation of TruRating must implement at least one trigger type, but is not limited to a single trigger.

Requirements

  1. Trigger the rating process at the point at which a payment card payment has been presented
    • For MSR this is at point of card swipe, but before card is processed
    • For EMV contact, this is the point at which card is inserted, but before card is processed
    • For contactless, this is the point at which card has been presented and processed successfully

Rating at Pre Approval (O)

When to implement?

This requirement should be implemented in situations where the TruRating question is required to appear at the point at which the customer has presented their payment card, their card has been processed and authorised successfully and the customer is just about to be told that their payment has been approved. An implementation of TruRating must implement at least one trigger type, but is not limited to a single trigger.

Requirements

  1. Trigger the rating process at the point at which a payment card payment has been processed successfully but
    • ahead of the customer being told that their payment has been authorised
    • ahead of them being asked to remove their card (for contact cards)
    • ahead of the payment receipt being printed
  2. Rating is not collected if payment is cancelled, declined or another non-success scenario
  3. TruModule can send Transaction information for failed payment in this situation to TruService even though question has not been asked

HTTP connection to TruService (O)

When to implement?

All implementations of TruModule will ideally support both HTTP & HTTPS connectivity with TruService as it offers the most flexible deployment options. However, if TruService will always be deployed locally to an implementation of TruModule (i.e. within same LAN or private WAN) then a standard HTTP connection is acceptable.

Requirements

  1. Establish an outbound connection to TruService using an HTTP connection
  2. Provide a request & response message interface using the HTTP connection in-line with the TruService schema
  3. Provide connection resilience in-line with non-functional requirements
  4. Support clean connection shutdown

HTTPS connection to TruService (O)

When to implement?

All implementations of TruModule will ideally support both HTTP & HTTPS connectivity with TruService as it offers the most flexible deployment options. If TruSevice is going to be deployed remotely from an implementation of TruModule, especially outside of a partner or merchants private network then an HTTPS connection is required. If TruService will be provided by TruRating on a Software as a Service (SaaS) basis then an HTTPS connection is mandated.

Requirements

  1. Establish an outbound connection to TruService using an HTTPS connection
  2. Sign the message payload and append authentication headers in-line with the TruRating MAC specification.
  3. Provide a request & response message interface using the HTTPS connection in-line with the TruService schema
  4. Provide connection resilience in-line with non-functional requirements
  5. Support clean connection shutdown

Internal question trigger support (O)

When to implement?

All implementations of TruModule that implement one or more of the card payment related triggers would implement this requirement as it drives the rating process. An implementation of TruModule that is only supporting the Dwell Time Extend trigger and will be submitting POS events to TruService in realtime can utilise the TruService question trigger support feature (see below) as an alternative to internal question trigger support.

Requirements

  1. Trigger rating process using internal events/solution activity when the following triggers are being supported:
    • Payment Request
    • Amount finalised
    • Card presentation
    • Pre-Approval
    • Dwell time (with dwell time extend) where POS Events are not supported

TruService question trigger support (O)

When to implement?

Where TruModule is supporting the Dwell Time Extend trigger and will pass POS events to TruService (minimum of Start Transaction, End Tilling & End Transaction) in realtime then TruService will notify TruModule when a question should be asked, enabling TruModule to fetch and present the question. TruService question trigger support allows for TruModule to be told when a question is available and allows TruService to determine when to trigger the questions, based on the POS events. This, for example, allows basket content driven question support.

Requirements

  1. Trigger rating process upon notification from TruService that a question is available in a response to a POS Event that has been issued

Retrieve question (RequestQuestion) (M)

When to implement?

All implementations of TruModule must implement this requirement, regardless of trigger type(s) being supported.

Requirements

  1. Request a question using the RequestQuestion command as follows:
    • If pre-fetch is being used - at start-up, upon activation or completion of a payment.
    • If pre-fetch is not used - at point a question trigger has occurred
  2. Generate the RequestQuestion request in-line with the TruService schema
  3. Populate request with the required trigger, device and language data
  4. Send the request to TruService and wait for the response
  5. Receive the TruService response
  6. Interpret and act on the response (a question may or may not be returned)
  7. Utilise the data provided in the response (question text, language options, acknowledgement and receipt text, timeout settings) when performing the rating and associated activities

Deliver rating (RequestRating) (M)

When to implement?

All implementations of TruModule must implement this requirement, regardless of trigger type(s) being supported.

Requirements

  1. At point a question has been delivered and response received, generate the RequestRating request in-line with the TruService schema
  2. Populate request with the applicable rating data
  3. Send the request to TruService and wait for the response
  4. Receive the TruService response
  5. Interpret and act on the response

NOTE: Rating can be delivered later in the transaction or payment processing and can be contained the RequestTransaction message in a single delivery to TruService when transaction or payment has completed.

Deliver transaction result (RequestTransaction) (M)

When to implement?

All implementations of TruModule must implement this requirement, regardless of trigger type(s) being supported.

Requirements

  1. At point a transaction or payment has completed generate the RequestTransaction request in-line with the TruService schema
  2. Populate request with the applicable transaction data
  3. Send the request to TruService and wait for the response
  4. Receive the TruService response
  5. Interpret and act on the response

NOTE: Transaction message can be incorporated into the RequestRating message and delivered as a single message to TruService

POS Event delivery support (O)

When to implement?

This requirement should be implemented in all situations where TruModule has access to a suitable set of POS events as this will enrich the TruRating offering to merchants and enhance the data analytics that TruRating provides. It must be implemented in situations where TruModule relies on TruService to trigger the rating question and in this situation the POS events need to be sent in realtime - as opposed to batch after the fact.

Requirements

  1. Generate the following POS Events in-line with the TruService schema, in sync with the equivalent transaction activity:
    • RequestPOSStartTransaction
    • RequestPOSStartTilling
    • RequestPOSEndTilling
    • RequestPOSEndTransaction
    • RequestPOSReceiptData
  2. Events will be generated from data held locally or received via external interface(s)
  3. Send the events to TruService singularly or in batch as per the TruService schema:
    • RequestPOSEvent
    • RequestPOSEventList
  4. Wait for and receive the TruService responses to these events
  5. Act on the TruService response to receipt of a POS Event in-line with the rest of the section

Basket Data delivery support (O)

When to implement?

This requirement should be implemented in all situations where TruModule has access to POS basket data as this will enrich the TruRating offering to merchants and enhance the data analytics that TruRating provides.

Requirements

  1. Generate the following POS basket data events in-line with the TruService schema, in sync with the equivalent transaction activity:
    • RequestPOSItem
    • RequestPOSItemDiscount
  2. Events will be generated using the relevant POS transaction data
  3. Send the events to TruService singularly or in batch as per the TruService schema: 3.1. RequestPOSEvent 3.2. RequestPOSEventList
  4. Wait for and receive the TruService responses to these events
  5. Act on the TruService response to receipt of a POS Event in-line with the rest of the section

Display question & get rating (M)

When to implement?

All implementations of TruModule must implement this requirement, regardless of trigger type(s) being supported.

Requirements

  1. At the point a TruRating triggers occurs, if TruRating is active and a question is available then interact with the PED to:
    • Perform the 1AQ1KR command - using provided question text in correct language
    • Wait for the response to the 1AQ1KR command
    • Ensure the question remains on the device until a response is received or rating question is cancelled
  2. Utilise the information provided by TruService in response to the RequestQuestion command
    • Question text
    • Timeout values

Display rating acknowledgement (M)

When to implement?

All implementations of TruModule must implement this requirement, regardless of trigger type(s) being supported.

Requirements

  1. When a rating question has been delivered and a response received (valid response or skip) interact with the PED either directly or via a payment application to:
    • Display the relevant acknowledgement message onto the PED for the defined amount of time in the relevant language
    • Clear the PED display as required after the defined amount of time
  2. Utilise the information provided by TruService in response to the RequestQuestion command

Cancel rating question (M)

When to implement?

All implementations of TruModule must implement this requirement, regardless of trigger type(s) being supported.

Requirements

  1. When a rating question has been displayed but no response received at the point of timeout then interact with the PED either directly or via the Payment application to clear the rating question from the device
  2. Where TruService notifies TruModule to clear the display then interact with the PED either directly or via the Payment application to clear the rating question from the device
  3. The PED should be returned to a ready state
  4. The rating data delivered to TruService should indicate that a timeout occurred

NOTE: The point of timeout varies based on which rating trigger type was used and the timeout defined by TruService.

Query for Status (M)

When to implement?

All implementations of TruModule must implement this requirement, regardless of trigger type(s) being supported.

Requirements

  1. TruModule must maintain the state of whether it is active or not, i.e. asking questions and delivering ratings and transactions
  2. TruModule must query for status at initial start-up.
  3. TruModule should re-query for status after the TimeToLive (in seconds) has elapsed. TruModule should only re-query before the next request to TruService is made.
  4. Where the device that executes TruModule provides a secure Merchant only user interface, the status of TruModule should be presented to the Merchant

Activation (O)

When to implement?

All implementations of TruModule that are supporting Terminal Led Activation (TLA) must meet this requirement..

Requirements

  1. Activation is performed for the most part by the merchant on the TruRating website. To tie the Terminal into the user account created on the web (without directly asking for Merchant ID and Terminal ID), TruRating sends an Activation Code to the Terminal.
  2. The payment terminal needs a TruRating menu item, which will be designed in accordance with the look and feel of the rest of the payment application menus.
  3. The TruRating menu item when triggered will perform a Query request message

TruRating receipt text support (M)

When to implement?

All implementations of TruModule must implement this requirement, regardless of trigger type(s) being supported.

Requirements

  1. Select the correct TruRating receipt text from the choice supplied when the question is returned by TruService to use based on the result of the rating activity:
    • No rating question asked - no receipt text
    • Question asked, no rating given - negative receipt text
    • Question asked, rating given - positive receipt text
  2. Make the receipt text available to the POS or Payment application for incorporation into the till receipt or EFT receipt - based on the type of integration and rating trigger used

Configuration Control (M)

When to implement?

All implementations of TruModule must implement this requirement. The requirements described here are provided as a guide since the exact requirements and implementation will be specific to each implementation of TruModule.

Requirements

  1. The implementation of TruModule should incorporate any configurable options support in a flexible manner
  2. An end merchant should be able to re-configure their TruRating experience within the limits of the features supported by TruModule with minimal impact in terms of time, cost and impact on other services
  3. The implementation must allow TruRating to be easily disabled and removed from the regular transaction flow in the event of a major issue occurring within a merchant environment. This will provide support teams with a simple way of removing TruRating as part of the problem determination process.

Priority Message Handling (M)

When to implement?

All implementations of TruModule must implement this requirement.

Requirements

  1. TruRating sends down a Priority indicator in the Screen and Receipt nodes of the Question Response. This priority indicator can be used to indicate a Treat or Prize has been won by the customer.
  2. If the priority indicator is set there may be a longer than default time to display the acknowledgement, the TruService display time cannot be overridden at this time (so the user clearly sees that they have won a prize)
  3. If the priority indicator is set the Customer Receipt must be printed (as it will contain an award code).
Feedback