Amadis
Retail Module
Technical Documentation
Please see the main ASL 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"?> |
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"?> |
XML message Payment response | <?xml version="1.0" encoding="UTF-8"?><SaleToPOIResponse> |
Payment with cashback
NexoRetail Feature | Payment with cashback |
---|---|
XML message Payment request | <?xml version="1.0"?> |
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 |