Amadis

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 10 Next »

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);

Initialize a Client mode Module

In Client mode, a Retail Module is actively trying to connect to a Sale System. When that connection is lost or terminated, it will continue trying to reconnect.

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);

Poll the Module for Sale events

See Events for the supported event types and specifications

// 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

// Previously polled event
NexoEvent event = [...];

// Create response data content according to event type
byte[] responseData = {...};

// Send response
retailModule.respond(event, responseData);

Signal a System state change

retailModule.signal(NexoSignal.CardDetected);

retailModule.signal(NexoSignal.Busy);
retailModule.signal(NexoSignal.Available);

Test Cases

Test case 0001

NexoRetail Feature

Payment

XML message

 xml message simple payment

<?xml version="1.0"?>
<SaleToPOIRequest>
<MessageHeader MessageClass="Service" MessageCategory="Payment" MessageType="Request" ServiceID="2" SaleID="ArkosSales" POIID="AFDB0001" />
<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>

Trace

 xml message

2022-03-21 11:20:26,869 TRACE [ntrig] # login
2022-03-21 11:20:26,878 TRACE [ntrig] Sending the content of "login.xml" (501 bytes)
2022-03-21 11:20:26,878 TRACE [ntrig] Waiting for 500 milliseconds
2022-03-21 11:20:26,886 TRACE [ntrig] Received from the POI: <?xml version="1.0" encoding="UTF-8"?><SaleToPOIResponse><MessageHeader MessageClass="Service" MessageType="Response" MessageCategory="Login" ProtocolVersion="3.0" ServiceID="1" POIID="AFDB0001" SaleID="ArkosSales" /><LoginResponse><Response Result="Success" /><POISystemData><DateTime>2022-03-21T11:20:27.208-04:00</DateTime><POISoftware ManufacturerID="Manufacturer" SoftwareVersion="1.0" ApplicationName="Application" CertificationCode="NA" /><POIStatus GlobalStatus="OK" /></POISystemData></LoginResponse></SaleToPOIResponse>
2022-03-21 11:20:27,385 TRACE [ntrig] # prepay
2022-03-21 11:20:27,393 TRACE [ntrig] Sending the content of "payNatixis.xml" (736 bytes)
2022-03-21 11:20:27,393 TRACE [ntrig] # end of script
2022-03-21 11:20:37,962 TRACE [ntrig] Received from the POI: <?xml version="1.0" encoding="UTF-8"?><SaleToPOIRequest><MessageHeader SaleID="AFDB0001" MessageCategory="Display" MessageType="Request" ServiceID="2" MessageClass="Device" DeviceID="1" POIID="ArkosSales" /><DisplayRequest><DisplayOutput Device="CashierDisplay" ResponseRequiredFlag="False" InfoQualify="POIReplication"><OutputContent OutputFormat="Text"><OutputText>InsertOrPresentCard</OutputText></OutputContent></DisplayOutput></DisplayRequest></SaleToPOIRequest>
2022-03-21 11:20:39,054 TRACE [ntrig] Received from the POI: <?xml version="1.0" encoding="UTF-8"?><SaleToPOIRequest><MessageHeader MessageClass="Device" DeviceID="1" MessageType="Request" POIID="ArkosSales" SaleID="AFDB0001" MessageCategory="Display" ServiceID="2" /><DisplayRequest><DisplayOutput ResponseRequiredFlag="False" Device="CashierDisplay" InfoQualify="POIReplication"><OutputContent OutputFormat="Text"><OutputText>PleaseWait</OutputText></OutputContent></DisplayOutput></DisplayRequest></SaleToPOIRequest>
2022-03-21 11:20:40,281 TRACE [ntrig] Received from the POI: <?xml version="1.0" encoding="UTF-8"?><SaleToPOIRequest><MessageHeader POIID="ArkosSales" DeviceID="1" MessageClass="Device" SaleID="AFDB0001" MessageCategory="Display" MessageType="Request" ServiceID="2" /><DisplayRequest><DisplayOutput ResponseRequiredFlag="False" InfoQualify="POIReplication" Device="CashierDisplay"><OutputContent OutputFormat="Text"><OutputText>Approved</OutputText></OutputContent></DisplayOutput></DisplayRequest></SaleToPOIRequest>
2022-03-21 11:20:51,797 TRACE [ntrig] Received from the POI: <?xml version="1.0" encoding="UTF-8"?><SaleToPOIResponse><MessageHeader ServiceID="2" MessageType="Response" MessageCategory="Payment" POIID="AFDB0001" SaleID="ArkosSales" MessageClass="Service" /><PaymentResponse><Response Result="Failure" ErrorCondition="DeviceOut"><AdditionalResponse>Internal system error: MissingDataField { field: "PaymentData" }</AdditionalResponse></Response><SaleData><SaleTransactionID TransactionID="1" TimeStamp="2019-08-21T14:48:05+05:00" /></SaleData><POIData><POITransactionID TimeStamp="2022-03-21T11:20:52.119-04:00" TransactionID="Undefined" /></POIData></PaymentResponse></SaleToPOIResponse>

Test case 0002

NexoRetail Feature

Payment with cashback

XML message

 xml message payment with cashback

2022-03-21 11:48:16,923 TRACE [ntrig] # login
2022-03-21 11:48:16,924 TRACE [ntrig] Sending the content of "login.xml" (501 bytes)
2022-03-21 11:48:16,925 TRACE [ntrig] Waiting for 500 milliseconds
2022-03-21 11:48:16,928 TRACE [ntrig] Received from the POI: <?xml version="1.0" encoding="UTF-8"?><SaleToPOIResponse><MessageHeader MessageClass="Service" ProtocolVersion="3.0" MessageCategory="Login" MessageType="Response" POIID="AFDB0001" SaleID="ArkosSales" ServiceID="1" /><LoginResponse><Response Result="Success" /><POISystemData><DateTime>2022-03-21T11:48:17.244-04:00</DateTime><POISoftware ManufacturerID="Manufacturer" ApplicationName="Application" SoftwareVersion="1.0" CertificationCode="NA" /><POIStatus GlobalStatus="OK" /></POISystemData></LoginResponse></SaleToPOIResponse>
2022-03-21 11:48:17,430 TRACE [ntrig] # prepay
2022-03-21 11:48:17,431 TRACE [ntrig] Sending the content of "payNatixis.xml" (761 bytes)
2022-03-21 11:48:17,432 TRACE [ntrig] # end of script
2022-03-21 11:48:19,721 TRACE [ntrig] Received from the POI: <?xml version="1.0" encoding="UTF-8"?><SaleToPOIRequest><MessageHeader ServiceID="2" POIID="ArkosSales" SaleID="AFDB0001" MessageCategory="Display" MessageType="Request" MessageClass="Device" DeviceID="1" /><DisplayRequest><DisplayOutput InfoQualify="POIReplication" Device="CashierDisplay" ResponseRequiredFlag="False"><OutputContent OutputFormat="Text"><OutputText>InsertOrPresentCard</OutputText></OutputContent></DisplayOutput></DisplayRequest></SaleToPOIRequest>
2022-03-21 11:48:20,763 TRACE [ntrig] Received from the POI: <?xml version="1.0" encoding="UTF-8"?><SaleToPOIRequest><MessageHeader MessageType="Request" MessageClass="Device" DeviceID="1" POIID="ArkosSales" SaleID="AFDB0001" MessageCategory="Display" ServiceID="2" /><DisplayRequest><DisplayOutput InfoQualify="POIReplication" ResponseRequiredFlag="False" Device="CashierDisplay"><OutputContent OutputFormat="Text"><OutputText>PleaseWait</OutputText></OutputContent></DisplayOutput></DisplayRequest></SaleToPOIRequest>
2022-03-21 11:48:21,535 TRACE [ntrig] Received from the POI: <?xml version="1.0" encoding="UTF-8"?><SaleToPOIRequest><MessageHeader POIID="ArkosSales" SaleID="AFDB0001" ServiceID="2" DeviceID="1" MessageCategory="Display" MessageType="Request" MessageClass="Device" /><DisplayRequest><DisplayOutput ResponseRequiredFlag="False" Device="CashierDisplay" InfoQualify="POIReplication"><OutputContent OutputFormat="Text"><OutputText>Approved</OutputText></OutputContent></DisplayOutput></DisplayRequest></SaleToPOIRequest>
2022-03-21 11:48:25,136 TRACE [ntrig] Received from the POI: <?xml version="1.0" encoding="UTF-8"?><SaleToPOIResponse><MessageHeader ServiceID="2" MessageCategory="Payment" MessageType="Response" SaleID="ArkosSales" POIID="AFDB0001" MessageClass="Service" /><PaymentResponse><Response Result="Failure" ErrorCondition="DeviceOut"><AdditionalResponse>Internal system error: MissingDataField { field: "PaymentData" }</AdditionalResponse></Response><SaleData><SaleTransactionID TransactionID="1" TimeStamp="2019-08-21T14:48:05+05:00" /></SaleData><POIData><POITransactionID TransactionID="Undefined" TimeStamp="2022-03-21T11:48:25.453-04:00" /></POIData></PaymentResponse></SaleToPOIResponse>

Trace

 xml message

2022-03-21 11:53:19,234 TRACE [ntrig] # login
2022-03-21 11:53:19,244 TRACE [ntrig] Sending the content of "login.xml" (501 bytes)
2022-03-21 11:53:19,245 TRACE [ntrig] Waiting for 500 milliseconds
2022-03-21 11:53:19,247 TRACE [ntrig] Received from the POI: <?xml version="1.0" encoding="UTF-8"?><SaleToPOIResponse><MessageHeader MessageClass="Service" MessageType="Response" ProtocolVersion="3.0" MessageCategory="Login" POIID="AFDB0001" ServiceID="1" SaleID="ArkosSales" /><LoginResponse><Response Result="Success" /><POISystemData><DateTime>2022-03-21T11:53:19.562-04:00</DateTime><POISoftware CertificationCode="NA" ApplicationName="Application" SoftwareVersion="1.0" ManufacturerID="Manufacturer" /><POIStatus GlobalStatus="OK" /></POISystemData></LoginResponse></SaleToPOIResponse>
2022-03-21 11:53:19,750 TRACE [ntrig] # prepay
2022-03-21 11:53:19,757 TRACE [ntrig] Sending the content of "payNatixis.xml" (761 bytes)
2022-03-21 11:53:19,757 TRACE [ntrig] # end of script
2022-03-21 11:53:22,065 TRACE [ntrig] Received from the POI: <?xml version="1.0" encoding="UTF-8"?><SaleToPOIRequest><MessageHeader MessageCategory="Display" DeviceID="1" MessageClass="Device" MessageType="Request" POIID="ArkosSales" SaleID="AFDB0001" ServiceID="2" /><DisplayRequest><DisplayOutput Device="CashierDisplay" InfoQualify="POIReplication" ResponseRequiredFlag="False"><OutputContent OutputFormat="Text"><OutputText>InsertOrPresentCard</OutputText></OutputContent></DisplayOutput></DisplayRequest></SaleToPOIRequest>
2022-03-21 11:53:23,108 TRACE [ntrig] Received from the POI: <?xml version="1.0" encoding="UTF-8"?><SaleToPOIRequest><MessageHeader SaleID="AFDB0001" MessageCategory="Display" ServiceID="2" POIID="ArkosSales" DeviceID="1" MessageType="Request" MessageClass="Device" /><DisplayRequest><DisplayOutput ResponseRequiredFlag="False" InfoQualify="POIReplication" Device="CashierDisplay"><OutputContent OutputFormat="Text"><OutputText>PleaseWait</OutputText></OutputContent></DisplayOutput></DisplayRequest></SaleToPOIRequest>
2022-03-21 11:53:23,847 TRACE [ntrig] Received from the POI: <?xml version="1.0" encoding="UTF-8"?><SaleToPOIRequest><MessageHeader SaleID="AFDB0001" MessageType="Request" MessageCategory="Display" DeviceID="1" POIID="ArkosSales" MessageClass="Device" ServiceID="2" /><DisplayRequest><DisplayOutput Device="CashierDisplay" InfoQualify="POIReplication" ResponseRequiredFlag="False"><OutputContent OutputFormat="Text"><OutputText>Approved</OutputText></OutputContent></DisplayOutput></DisplayRequest></SaleToPOIRequest>
2022-03-21 11:53:28,740 TRACE [ntrig] Received from the POI: <?xml version="1.0" encoding="UTF-8"?><SaleToPOIResponse><MessageHeader MessageCategory="Payment" MessageClass="Service" MessageType="Response" POIID="AFDB0001" SaleID="ArkosSales" ServiceID="2" /><PaymentResponse><Response Result="Failure" ErrorCondition="DeviceOut"><AdditionalResponse>Internal system error: MissingDataField { field: "PaymentData" }</AdditionalResponse></Response><SaleData><SaleTransactionID TimeStamp="2019-08-21T14:48:05+05:00" TransactionID="1" /></SaleData><POIData><POITransactionID TransactionID="Undefined" TimeStamp="2022-03-21T11:53:29.055-04:00" /></POIData></PaymentResponse></SaleToPOIResponse>

  • No labels