Overview
This is the documentation for building TruModule, the component that brings TruRating's point-of-sale rating capability into a payment application, POS application, or self-checkout system.
At a high level, the integration model is:
- TruModule runs in the partner build or merchant platform and sends TruService Interface (TSI) messages.
- TruService responds with question, display, event, and status data.
- The payment device or point-of-sale environment determines which rendering mode is available.
Key definitions
| Term | Definition |
|---|---|
| TruRating | The feedback platform that supplies questions, receives ratings and transaction context, and turns the results into reporting for merchants. |
| Partner | The organization that builds and operates TruModule. Depending on the integration this can be a payment provider or acquirer, a POS/ECR vendor, a third-party middleware or professional-services integrator, or the merchant building in-house. "Partner" throughout these docs means whoever owns the build, which is not always the merchant. |
| TruModule | The partner-built component inside the payment, POS, self-checkout, or middleware environment. It sends TSI messages to TruService and renders the returned customer experience. |
| TruService | The TruRating service endpoint that receives TruModule messages, decides whether a question should be shown, returns display content, and accepts ratings, transaction data, and POS event data. |
| TruService Interface (TSI) | The XML-over-HTTPS protocol and schema used between TruModule and TruService. New in-store builds should target TSI v2.5.0. |
| Technical Scope of Work (TSOW) | The agreed scope document for a TruModule build. It defines what will be built and is used as the baseline for accreditation. |
| Solutions Architect (SA) | The TruRating technical contact who helps scope the integration, reviews screen flows and message behavior, and supports accreditation. |
| Trigger point | The point in the customer journey where TruModule asks TruService for a question, such as payment request, amount finalized, card presentation, pre-approval, or dwell-time extension. |
| Accreditation | TruRating's structured sign-off process, covering screen design, protocol/message behavior, and user acceptance testing against the agreed TSOW. |
Where TruModule can run
It's easy to picture TruModule as "code on a payment terminal", but that's only the most common case. TruModule is a logical component: it can run wherever the partner build can reach both the trigger event and a device to render on, and its logic and its user experience can live in different places.
| TruModule runs in… | UX is rendered on… | Typical setting |
|---|---|---|
| The payment terminal application | The terminal (PED) screen | Classic countertop PED |
| The POS / ECR application | A customer-facing POS display, cashier screen, or attached PED | Integrated POS estates |
| Middleware or a store server | Whichever device the middleware drives: PED, tablet, or self-checkout screen | Estates with a middleware layer coordinating POS and payment |
| A payment gateway or the cloud path | The terminal, tablet, or consumer device reached through the gateway | Gateway-routed estates and some mPOS |
| Split across tiers | e.g. logic in middleware/gateway, rendering on a consumer device, tablet, mPOS, or self-checkout | Builds that divide responsibility between systems |
The rendering surface is just as flexible: a keypad PED, a touch POS display, a tablet, an mPOS handset, a consumer device, or a self-checkout screen. TruModule declares the target device's capabilities in each question request and TruService formats its response to match (see Rendering Modes). If your architecture doesn't map cleanly onto one of the rows above, that's expected: bring it to your Solutions Architect during scoping, as the split between where logic runs and where the UX renders is one of the first things a TSOW pins down.
Before anything else: know the lifecycle
Every TruModule integration goes through the same four phases: engagement, scope agreement, build, and accreditation, regardless of platform or region. Read Partner Lifecycle first. It explains what you are building toward, what TruRating needs from you and when, and why builds that skip the scoping step get sent back later rather than sooner.
Reading order
- Customer Journeys, Rendering Modes, and Multilanguage: what the customer sees and when, before any protocol detail.
- TSI Core Concepts: the protocol itself.
- First Working Flow: a minimal request and response sequence.
- Message Cookbook: task-based message reference.
- Data Collected: a higher-level view of what TruRating collects and what's mandated versus optional, before the field-level detail.
- The raw schema and required specifications: TruModule Specification, TruService Specification, and Security and Reliability, for exact field-level and contract detail.
Beyond the protocol
Once you know the protocol, two more things determine whether a build is actually accepted:
- The requirements above, which a build is checked against during accreditation.
- Getting Started with a Build and Scoping a Partner Integration: what happens procedurally, from your first sandbox access through to accreditation.
Executive summary
Stripped of protocol detail, this is a small integration. Your system sends TruService a handful of well-defined messages at a few natural points in an existing payment or checkout flow, and TruService tells you exactly what to display and when. You are not building rating logic, a UI design system, or analytics. You are wiring in message calls and rendering what comes back.
The minimal path is four message types:
- Query: ask whether rating is currently active for this merchant and terminal.
- Question: ask what to display at the agreed trigger point.
- Rating: return what the customer answered.
- Transaction: the purchase context, which can simply be embedded in the Rating message to start.
A first implementation typically uses one language, one rendering mode, and the transaction embedded rather than sent separately. See First Working Flow for the exact sequence.
What takes real time is not the protocol, it's the surrounding process: agreeing scope, getting screen designs signed off, and passing structured accreditation before go-live (see Partner Lifecycle). The technical ask itself stays simple regardless of platform, region, or device.