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.
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
// 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);
Examples
Login
NexoRetail Feature | Login |
---|
XML message Login request | xml message login request <?xml version="1.0"?> <SaleToPOIRequest> <MessageHeader ProtocolVersion="3.0" MessageClass="Service" MessageCategory="Login" MessageType="Request" ServiceID="1" SaleID="ArkosSales" POIID="AFDB0001" /> <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 message login response <?xml version="1.0" encoding="UTF-8"?><SaleToPOIResponse><MessageHeader ServiceID="1" POIID="AFDB0001" MessageType="Response" ProtocolVersion="3.0" SaleID="ArkosSales" 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 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> |
---|
XML message Payment response | xml message simple payment response <?xml version="1.0" encoding="UTF-8"?><SaleToPOIResponse> <MessageHeader MessageType="Response" MessageClass="Service" MessageCategory="Payment" ServiceID="2" POIID="AFDB0001" SaleID="ArkosSales"/> <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 message payment request with cashback <?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="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 | xml message payment response with cashback <?xml version="1.0" encoding="UTF-8"?> <SaleToPOIResponse> <MessageHeader POIID="AFDB0001" MessageCategory="Payment" SaleID="ArkosSales" ServiceID="2" MessageType="Response" MessageClass="Service"/> <PaymentResponse> <Response Result="Success"/> <SaleData> <SaleTransactionID TransactionID="1" TimeStamp="2019-08-21T14:48:05+05:00"/> </SaleData> <POIData> <POITransactionID TransactionID="0000000018" TimeStamp="2022-03-21T13:22:43.151-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 Currency="EUR" CashBackAmount="20" AuthorizedAmount="50"/> <PaymentAcquirerData AcquirerPOIID="ASA00007" AcquirerID="Processor A Short Name" MerchantID="00000NEXOMER001"> <ApprovalCode>002027</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 tip
NexoRetail Feature | Payment with tip |
---|
XML message Payment request | xml message payment request with tip <?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="50.00" TipAmount="20.00"/> <SaleItem ItemID="Banane" ProductCode="77662389" ItemAmount="3" > <UnitPrice>0.79</UnitPrice> </SaleItem> </PaymentTransaction> <PaymentData PaymentType="Normal" /> </PaymentRequest> </SaleToPOIRequest> |
---|
XML message Payment response | xml message payment response with tip <?xml version="1.0" encoding="UTF-8"?> <SaleToPOIResponse> <MessageHeader MessageCategory="Payment" POIID="AFDB0001" SaleID="ArkosSales" MessageClass="Service" MessageType="Response" ServiceID="2"/> <PaymentResponse> <Response Result="Success"/> <SaleData> <SaleTransactionID TimeStamp="2019-08-21T14:48:05+05:00" TransactionID="1"/> </SaleData> <POIData> <POITransactionID TransactionID="0000000019" TimeStamp="2022-03-21T13:34:04.354-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="50" TipAmount="20" Currency="EUR"/> <PaymentAcquirerData AcquirerPOIID="ASA00007" AcquirerID="Processor A Short Name" MerchantID="00000NEXOMER001"> <ApprovalCode>002028</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 and tip
NexoRetail Feature | Payment with cashback and tip |
---|
XML message Payment request | xml message payment request with cashback and tip <?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="50.00" TipAmount="20.00" CashBackAmount="10.00"/> <SaleItem ItemID="Banane" ProductCode="77662389" ItemAmount="3" > <UnitPrice>0.79</UnitPrice> </SaleItem> </PaymentTransaction> <PaymentData PaymentType="Normal" /> </PaymentRequest> </SaleToPOIRequest> |
---|
XML message Payment response | xml message payment response with cashback and tip <?xml version="1.0" encoding="UTF-8"?> <SaleToPOIResponse> <MessageHeader MessageClass="Service" MessageType="Response" POIID="AFDB0001" MessageCategory="Payment" ServiceID="2" SaleID="ArkosSales"/> <PaymentResponse> <Response Result="Success"/> <SaleData> <SaleTransactionID TimeStamp="2019-08-21T14:48:05+05:00" TransactionID="1"/> </SaleData> <POIData> <POITransactionID TimeStamp="2022-03-21T13:52:16.900-04:00" TransactionID="0000000021"/> </POIData> <PaymentResult PaymentType="Normal"> <PaymentInstrumentData> <PaymentInstrumentType>Card</PaymentInstrumentType> <CardData> <PaymentBrand>Carte a Piste</PaymentBrand> <MaskedPAN>5219********0517</MaskedPAN> <EntryMode>MagStripe</EntryMode> </CardData> </PaymentInstrumentData> <AmountsResp Currency="EUR" TipAmount="20" AuthorizedAmount="50" CashBackAmount="10"/> <PaymentAcquirerData AcquirerPOIID="ASA00007" AcquirerID="Processor A Short Name" MerchantID="00000NEXOMER001"> <ApprovalCode>002030</ApprovalCode> </PaymentAcquirerData> <AmadisTicketData> <TVR>0000000000</TVR> <TSI>0000</TSI> <ApplicationPreferredName>Carte a Piste</ApplicationPreferredName> <CVM>3F0000</CVM> <ARC>3030</ARC> </AmadisTicketData> </PaymentResult> </PaymentResponse> </SaleToPOIResponse> |
---|
Refund
NexoRetail Feature | Refund |
---|
XML message Refund request | xml message simple refund request <?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" /> </PaymentTransaction> <PaymentData PaymentType="Refund" /> </PaymentRequest> </SaleToPOIRequest> |
---|
XML message Refund response | xml message simple refund response <?xml version="1.0" encoding="UTF-8"?> <SaleToPOIResponse> <MessageHeader POIID="AFDB0001" SaleID="ArkosSales" MessageCategory="Payment" MessageType="Response" ServiceID="2" MessageClass="Service"/> <PaymentResponse> <Response Result="Success"/> <SaleData> <SaleTransactionID TransactionID="1" TimeStamp="2019-08-21T14:48:05+05:00"/> </SaleData> <POIData> <POITransactionID TransactionID="0000000023" TimeStamp="2022-03-21T21:22:14.404-04:00"/> </POIData> <PaymentResult PaymentType="Refund"> <PaymentInstrumentData> <PaymentInstrumentType>Card</PaymentInstrumentType> <CardData> <PaymentBrand>Carte a Piste</PaymentBrand> <MaskedPAN>5219********0517</MaskedPAN> <EntryMode>MagStripe</EntryMode> </CardData> </PaymentInstrumentData> <AmountsResp Currency="EUR" AuthorizedAmount="1"/> <PaymentAcquirerData MerchantID="00000NEXOMER001" AcquirerPOIID="ASA00007"/> <AmadisTicketData> <TVR>0000000000</TVR> <TSI>0000</TSI> <ApplicationPreferredName>Carte a Piste</ApplicationPreferredName> <CVM>3F0000</CVM> <ARC>5931</ARC> </AmadisTicketData> </PaymentResult> </PaymentResponse> </SaleToPOIResponse> |
---|
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 with original request <?xml version="1.0"?> <SaleToPOIRequest> <MessageHeader MessageClass="Service" MessageCategory="Payment" MessageType="Request" ServiceID="2" SaleID="ArkosSales" POIID="AFDB0001" /> <PaymentRequest> <SaleData SaleReferenceID="ArkosSale42"> <SaleTransactionID TransactionID="24" TimeStamp="2019-08-21T14:48:05+05:00" /> </SaleData> <PaymentTransaction> <AmountsReq Currency="EUR" RequestedAmount="1.00" /> <OriginalPOITransaction> <POITransactionID TransactionID="00000032" TimeStamp="2022-03-22T11:26:10.000+00:00" /> </OriginalPOITransaction> </PaymentTransaction> <PaymentData PaymentType="Refund" /> </PaymentRequest> </SaleToPOIRequest> |
---|
XML message Refund response | xml message refund with original response <?xml version="1.0" encoding="UTF-8"?> <SaleToPOIResponse> <MessageHeader MessageCategory="Payment" POIID="AFDB0001" SaleID="ArkosSales" MessageClass="Service" MessageType="Response" ServiceID="2"/> <PaymentResponse> <Response Result="Success"/> <SaleData> <SaleTransactionID TransactionID="24" TimeStamp="2019-08-21T14:48:05+05:00"/> </SaleData> <POIData> <POITransactionID TransactionID="0000000006" TimeStamp="2022-03-23T09:20:35.280-04:00"/> </POIData> <PaymentResult PaymentType="Refund"> <PaymentInstrumentData> <PaymentInstrumentType>Card</PaymentInstrumentType> <CardData> <PaymentBrand>Carte a Piste</PaymentBrand> <MaskedPAN>5219********0517</MaskedPAN> <EntryMode>MagStripe</EntryMode> </CardData> </PaymentInstrumentData> <AmountsResp Currency="EUR" AuthorizedAmount="1"/> <PaymentAcquirerData AcquirerPOIID="ASA00001" MerchantID="00000NEXOMER001"/> <AmadisTicketData> <TVR>0000000000</TVR> <TSI>0000</TSI> <ApplicationPreferredName>Carte a Piste</ApplicationPreferredName> <CVM>3F0000</CVM> <ARC>5931</ARC> </AmadisTicketData> </PaymentResult> </PaymentResponse> </SaleToPOIResponse> |
---|
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 request <?xml version="1.0" encoding="UTF-8"?> <SaleToPOIRequest> <MessageHeader MessageClass="Service" MessageCategory="Reversal" MessageType="Request" ServiceID="15" SaleID="SaleTermB" POIID="POIServer" /> <ReversalRequest ReversalReason="CustCancel"> <OriginalPOITransaction SaleID="SaleTermA" POIID="POITerm1"> <POITransactionID TransactionID="0000000003" TimeStamp="2009-08-09T20:33:52.0+01:00" /> </OriginalPOITransaction> </ReversalRequest> </SaleToPOIRequest> |
---|
XML message Cancellation response | xml message cancellation response <SaleToPOIResponse> <MessageHeader SaleID="SaleTermB" MessageType="Response" MessageClass="Service" ServiceID="15" POIID="POIServer" MessageCategory="Payment"/> <ReversalResponse> <Response Result="Success"/> <POIData> <POITransactionID TimeStamp="2022-03-23T11:20:26.015-04:00" TransactionID="0000000006"/> </POIData> </ReversalResponse> </SaleToPOIResponse> |
---|
Cancellation without searching from the log
NexoRetail Feature | Cancellation without search from log |
---|
XML message Cancellation request | xml message cancellation request <?xml version="1.0" encoding="UTF-8"?> <SaleToPOIRequest> <MessageHeader MessageClass="Service" MessageCategory="Reversal" MessageType="Request" ServiceID="15" SaleID="SaleTermB" POIID="POIServer" /> <ReversalRequest ReversalReason="CustCancel"> <OriginalPOITransaction SaleID="SaleTermA" POIID="POITerm1"> <POITransactionID TransactionID="0000000007" TimeStamp="2009-08-09T20:33:52.0+01:00" /> </OriginalPOITransaction> </ReversalRequest> </SaleToPOIRequest> |
---|
XML message Cancellation response | xml message cancellation response <?xml version="1.0" encoding="UTF-8"?><SaleToPOIResponse><MessageHeader ServiceID="15" SaleID="SaleTermB" MessageCategory="Payment" POIID="POIServer" MessageType="Response" MessageClass="Service" /><ReversalResponse><Response Result="Success" /><POIData><POITransactionID TransactionID="0000000003" TimeStamp="2022-03-24T10:49:28.711-04:00" /></POIData></ReversalResponse></SaleToPOIResponse> |
---|