Technical Documentation

Description

The Retail Module provides simplified connection and asynchronous communication with a Nexo Retail SaleSystem.

Goal and usage

This Module’s main functionality is to provide and manage an Event stream with a SaleSystem, allowing a Merchant application to efficiently receive triggers for actions such as Payment Requests, Display Requests, Input Requests. It also give simplified ways to provide Response to those events.

A secondary goal of the Retail Module is to manage the connectivity and system state with as little overview from the Merchant application as possible, allowing transparent management of System state. This allows the module to filter events that the Merchant Application is not awaiting, minimizing integration overhead.

For example, while the System is currently in a Service exchange, the module will automatically respond to incoming different Service requests with a Busy response

How to?

Initialize a Server mode Module

In Server mode, a Retail Module is awaiting a Sale System connection passively. When that connection is lost or terminated, it will go back to awaiting the next one.

To start in Server mode, use the static factory function StartServer on the AmadisRetailModule class, providing the port on which to await connections

NexoRetailModule retailModule = NexoRetailModule.StartServer(serverPort, provider);

Starting from version 2.5.1, StartServer has a second parameter, allowing the integrator’s application control over some application-specific information used by the retail module
See ISoftwareInformation

Initialize a Client mode Module

To start in Server mode, use the static factory function StartClient on the AmadisRetailModule class, providing the hostname and port of the Sale System

NexoRetailModule retailModule = NexoRetailModule.StartClient(saleHostname, salePort, provider);

Poll the Module for Sale events

// With timeout in ms
NexoEvent event = retailModule.pollTimeout(1000);

// Non-blocking
NexoEvent event = retailModule.poll();

NexoEventType type = event.GetType();
switch (type) {
case Login: 
  {...}
[...]
}

Respond to a previously polled event

Signal a System state change

See Events

Examples

Login

NexoRetail Feature	Login
XML message Login request	<?xml version="1.0"?> <SaleToPOIRequest> <MessageHeader ProtocolVersion="3.0" MessageClass="Service" MessageCategory="Login" MessageType="Request" ServiceID="1" SaleID="AmadisSaleSystem" POIID="AmadisTestPOI0001" /> <LoginRequest OperatorLanguage="en" OperatorID="fbe"> <DateTime>2019-08-21T13:21:23+05:00</DateTime> <SaleSoftware ManufacturerID="Amadis" ApplicationName="ArkosSalesInterface" SoftwareVersion="0.2.3" CertificationCode="NotCertified" /> </LoginRequest> </SaleToPOIRequest>
XML message Login response	<?xml version="1.0" encoding="UTF-8"?><SaleToPOIResponse><MessageHeader ServiceID="1" POIID="AmadisTestPOI0001" MessageType="Response" ProtocolVersion="3.0" SaleID="AmadisSaleSystem" MessageCategory="Login" MessageClass="Service" /><LoginResponse><Response Result="Success" /><POISystemData><DateTime>2022-03-21T12:40:34.160-04:00</DateTime><POISoftware SoftwareVersion="1.0" CertificationCode="NA" ApplicationName="Application" ManufacturerID="Manufacturer" /><POIStatus GlobalStatus="OK" /></POISystemData></LoginResponse></SaleToPOIResponse>

Simple Payment

NexoRetail Feature	Payment
XML message Payment request	<?xml version="1.0"?> <SaleToPOIRequest> <MessageHeader MessageClass="Service" MessageCategory="Payment" MessageType="Request" ServiceID="2" SaleID="AmadisSaleSystem" POIID="AmadisTestPOI0001" /> <PaymentRequest> <SaleData SaleReferenceID="ArkosSale42"> <SaleTransactionID TransactionID="1" TimeStamp="2019-08-21T14:48:05+05:00" /> </SaleData> <PaymentTransaction> <AmountsReq Currency="EUR" RequestedAmount="1.00" /> <SaleItem ItemID="Banane" ProductCode="77662389" ItemAmount="3" > <UnitPrice>0.79</UnitPrice> </SaleItem> </PaymentTransaction> <PaymentData PaymentType="Normal" /> </PaymentRequest> </SaleToPOIRequest>
XML message Payment response	<?xml version="1.0" encoding="UTF-8"?><SaleToPOIResponse> <MessageHeader MessageType="Response" MessageClass="Service" MessageCategory="Payment" ServiceID="2" POIID="AmadisTestPOI0001" SaleID="AmadisSaleSystem"/> <PaymentResponse> <Response Result="Success"/> <SaleData> <SaleTransactionID TimeStamp="2019-08-21T14:48:05+05:00" TransactionID="1"/> </SaleData> <POIData> <POITransactionID TransactionID="0000000017" TimeStamp="2022-03-21T13:15:13.277-04:00"/> </POIData> <PaymentResult PaymentType="Normal"> <PaymentInstrumentData> <PaymentInstrumentType>Card</PaymentInstrumentType> <CardData> <PaymentBrand>Carte a Piste</PaymentBrand> <MaskedPAN>5219********0517</MaskedPAN> <EntryMode>MagStripe</EntryMode> </CardData> </PaymentInstrumentData> <AmountsResp AuthorizedAmount="1" Currency="EUR"/> <PaymentAcquirerData MerchantID="00000NEXOMER001" AcquirerPOIID="ASA00007" AcquirerID="Processor A Short Name"> <ApprovalCode>002026</ApprovalCode> </PaymentAcquirerData> <AmadisTicketData> <TVR>0000000000</TVR> <TSI>0000</TSI> <ApplicationPreferredName>Carte a Piste</ApplicationPreferredName> <CVM>3F0000</CVM> <ARC>3030</ARC> </AmadisTicketData> </PaymentResult> </PaymentResponse> </SaleToPOIResponse>

Payment with cashback

NexoRetail Feature	Payment with cashback
XML message Payment request	<?xml version="1.0"?> <SaleToPOIRequest> <MessageHeader MessageClass="Service" MessageCategory="Payment" MessageType="Request" ServiceID="2" SaleID="AmadisSaleSystem" POIID="AmadisTestPOI0001" /> <PaymentRequest> <SaleData SaleReferenceID="ArkosSale42"> <SaleTransactionID TransactionID="1" TimeStamp="2019-08-21T14:48:05+05:00" /> </SaleData> <PaymentTransaction> <AmountsReq Currency="EUR" RequestedAmount="50.00" CashBackAmount="20.00"/> <SaleItem ItemID="Banane" ProductCode="77662389" ItemAmount="3" > <UnitPrice>0.79</UnitPrice> </SaleItem> </PaymentTransaction> <PaymentData PaymentType="Normal" /> </PaymentRequest> </SaleToPOIRequest>
XML message Payment response

Payment with tip

NexoRetail Feature	Payment with tip
XML message Payment request
XML message Payment response

Payment with cashback and tip

NexoRetail Feature	Payment with cashback and tip
XML message Payment request
XML message Payment response

Refund

NexoRetail Feature	Refund
XML message Refund request
XML message Refund response

Refund with Original Transaction

As the original transaction is optional for a refund, when present, it can be accessed by

PaymentRequest paymentReq = (PaymentRequest) req;

paymentReq.OriginalTransactionID.TransactionID;

NexoRetail Feature	Refund with Original Transaction
XML message Refund request
XML message Refund response

Cancellation searching from the log

Note: A previous transaction (Payment) was previously done with TransactionID="0000000003” and then canceled.

NexoRetail Feature	Cancellation search from log
XML message Cancellation request
XML message Cancellation response

Cancellation without searching from the log

NexoRetail Feature	Cancellation without search from log
XML message Cancellation request
XML message Cancellation response

Input Message

NexoRetail Feature	Input Message Example
XML message Input request
XML message Input response

Display Message

NexoRetail Feature	Display Message Example
XML message Display request
XML message Display response