Loyalty Request
It conveys Information related to the Loyalty transaction to process. Content of the Loyalty Request message.
Request Parameters
Data associated with the Sale System, with a particular value during the processing of the payment by the POI, including the cards acquisition.
Identification of the Cashier or Operator.
Language of the Cashier or Operator. If different from the Login.
Shift number. If different from the Login, see Login SaleData.
Identification of a transaction for the Sale System or the POI System.
Unique identification of a transaction to identify the transaction on the Sale System (e.g. ticket number), or the POI System.
Date and time of a transaction for the Sale System, the POI System or the Acquirer. Ensures the uniqueness of a transaction and indicates the time when the event occurs in the EventNotification message.
Identification of a Sale global transaction for a sequence of related POI transactions. If payment reservation.
Information related to the software and hardware features of the Sale Terminal. Sent in the Login Request if a Sale Terminal is involved in the login. In other messages, sent when a logical device is out of order (SaleCapabilities) or when other data have changed or were missing in the Login.
Identification of a group of transactions on a POI Terminal, having the same Sale features. Could be used to group POI for reconciliation or other purpose defined by the Sale System. The default value is assigned by the Login Request.
Type of token replacing the PAN of a payment card to identify the payment mean of the customer. It allows, for a merchant, to use a token for a transaction only or for a longer period. Possible values:
- Customer
- Transaction
Additional and optional identification of a customer order.
List of customer order open, closed or both to be sent in the response messages. Possible values:
- Both
- Closed
- Open
Sale information intended for the POI. Stored with the transaction.
Sale information intended for the Acquirer. Send to the Acquirer if present.
Sale information intended for the Issuer. The POI System receives this information and sends it to the Acquirer for the Issuer without any change.
Label to print on the bank statement.
Data related to the loyalty transaction.
Type of loyalty transaction. These types of loyalty transactions use the same message requests:
- Award: direct or payment-related award on a loyalty account.
- Rebate: rebate on a total amount, sale item amount, or sale items.
- Redemption: redemption on a loyalty account.
- AwardRefund: refund of a loyalty award transaction.
- RebateRefund: refund of a loyalty rebate transaction.
- RedemptionRefund: refund of a loyalty redemption transaction. Possible values:
- Award
- AwardRefund
- Rebate
- RebateRefund
- Redemption
- RedemptionRefund
Currency of a monetary amount.
Amount of a transaction. In the Loyalty Request message, it notifies the amount of the payment transaction on which the loyalty transaction has to be processed. In the Card Acquisition Request message, it allows the processing of a contactless card.
Identification of a previous POI transaction. In the Payment or the Loyalty Request message, it allows using the card of a previous CardAcquisition or Payment/Loyalty request.
Identification of a Sale System for the NEXO SaletoPOI protocol.
Identification of a payment terminal for the NEXO SaletoPOI protocol. If original transaction is coming from another POI.
Identification of a transaction for the Sale System or the POI System.
Unique identification of a transaction to identify the transaction on the Sale System (e.g. ticket number), or the POI System.
Date and time of a transaction for the Sale System, the POI System or the Acquirer. Ensures the uniqueness of a transaction and indicates the time when the event occurs in the EventNotification message.
Indicates if the card data has to be retrieved from a previous transaction.
Code assigned to a transaction approval by the Acquirer. If referral.
Identification of the Acquirer. Restrict to the Acquirer if present.
Value of an amount.
Identification of a transaction for the Sale System or the POI System.
Unique identification of a transaction to identify the transaction on the Sale System (e.g. ticket number), or the POI System.
Date and time of a transaction for the Sale System, the POI System or the Acquirer. Ensures the uniqueness of a transaction and indicates the time when the event occurs in the EventNotification message.
Conditions on which the transaction must be processed.
Payment brands accepted for this transaction. Card payment brands allowed by the Sale System for the payment transaction. Restrict brand if data sent.
Identification of the Acquirer. Restrict to these Acquirer if present.
The preferred type of payment is a debit transaction rather than a credit transaction.
Loyalty brands or programs allowed by the Sale System for the loyalty transaction. Restrict brand if data sent.
Type of Loyalty processing requested by the Sale System. Possible values:
- Allowed
- Forbidden
- Processed
- Proposed
- Required
Indicates if the Cashier requires POI forces online access to the Acquirer. Go online if data sent.
Payment instrument entry mode requested by the Sale System. Restrict entry mode if sent. Possible values:
- CheckReader
- Contactless
- File
- ICC
- Keyed
- MagStripe
- Manual
- RFID
- Scanned
- SynchronousICC
- Tapped
The code which identifies the category of the transaction (MCC). The payment implies a specific MCC.
In loyalty or value added payment card transaction, Sale items included in a transaction. The sum of the item amount could be more than the Requested amount in case of split payment without split of the items (split basket). In the StoredValue request message, sale items differentiate the Stored Value product with the EanUpc data element which has to be present.
Item identification inside a transaction (0 to n).
Product code of item purchased with the transaction.
Standard product code of item purchased with the transaction. If data sent, POI has to store it and send it if the host protocol allows it.
Unit of measure of a quantity. If Quantity is present. Possible values:
- Case
- Centilitre
- Centimetre
- Foot
- Gram
- Inch
- Kilogram
- Kilometre
- Litre
- Meter
- Mile
- Other
- Ounce
- Pint
- Pound
- Quart
- UKGallon
- USGallon
- Yard
Product quantity. If data is sent, POI has to store it and send it if the host protocol allows it.
Price per unit of product. If Quantity is present.
Total amount of the item line.
Type of taxes associated with the line item. If data is sent, POI has to store it and send it if the host protocol allows it.
Commercial or distribution channel associated with the line item. If data sent, POI has to store it and send it if the host protocol allows it.
Product name of an item purchased with the transaction.
Additional information related to the line item. If data sent, POI has to store it and send it if the host protocol allows it.
In the Payment, Loyalty or Balance Inquiry Request message, it allows the Sale Terminal to send the identification of the loyalty account or an awarded amount or an amount to redeem to the loyalty account. Data related to a Loyalty program or account.
Identification of a transaction for the Sale System or the POI System.
Unique identification of a transaction to identify the transaction on the Sale System (e.g. ticket number), or the POI System.
Date and time of a transaction for the Sale System, the POI System or the Acquirer. Ensures the uniqueness of a transaction and indicates the time when the event occurs in the EventNotification message.
Identification of a Loyalty account. In the Payment or the Loyalty Request message, it allows to identify the loyalty account by the Sale Terminal instead of the POI Terminal (e.g. because the account identification is a bar-code read by the Cashier on a scanner device).
Entry mode of the payment instrument information. In the Payment, Loyalty or StoredValue Request messages, it informs the POI System the entry mode of the payment instrument information when read by the Sale Terminal. In the Payment, Loyalty or StoredValue Response messages, it informs the Sale System the entry mode of the payment instrument. Possible values:
- Contactless
- File
- ICC
- Keyed
- MagStripe
- Manual
- Mobile
- RFID
- Scanned
- SynchronousICC
- Tapped
Type of account identification. In a request message, it informs the POI System the type of the account or card identification, when provided by the Sale Terminal. (e.g. because the card information is a barcode read by the Cashier on a scanner device). In a response message, it informs the Sale System the type of the account or card identification. Possible values:
- AccountNumber
- BarCode
- ISOTrack2
- PAN
- PhoneNumber
Support of the loyalty account identification. Allows knowing where and how you have found the loyalty account identification. Possible values:
- HybridCard
- LinkedCard
- LoyaltyCard
- NoCard
Loyalty account identification conforming to the IdentificationType.
Amount of a loyalty account. An awarded amount or an amount to redeem to the loyalty account might be sent in the Payment request message.
Unit of a loyalty amount. The amount could be expressed in point or in a monetary value and a currency. Possible values:
- Monetary
- Point
Currency of a monetary amount.
Value of an amount.
Response parameters
After submitting a call, you receive a response message to inform you that your request was received and processed.
Depending on the HTTP status code of the response message, it is helpful to build some logic to handle any errors that a request or the system may return.
HTTP Responses
200
It conveys Information related to the Loyalty transaction processed by the POI System. Content of the Loyalty Response message.
Show moreShow lessResponseobjectResult of a message request processing. If Result is Success,
ErrorConditionis absent or not used in the processing of the message. In the other cases, theErrorConditionhas to be present and can refine the processing of the message response.AdditionalResponsegives more information about the success or the failure of the message request processing, for logging without real time involvements.ResultstringResult of the processing of the message. Possible values:
- Failure
- Partial
- Success
ErrorConditionstringCondition that has produced an error on the processing of a message request. Returned if Result is not Success. Possible values:
- Aborted
- Busy
- Cancel
- DeviceOut
- InProgress
- InsertedCard
- InvalidCard
- LoggedOut
- MessageFormat
- NotAllowed
- NotFound
- PaymentRestriction
- Refusal
- UnavailableDevice
- UnavailableService
- UnreachableHost
- WrongPIN
AdditionalResponsestringAdditional information related to processing status of a message request. If present, the POI logs it for further examination.
SaleDataobjectData associated with the Sale System, with a particular value during the processing of the payment by the POI, including the cards acquisition.
OperatorIDstringIdentification of the Cashier or Operator.
OperatorLanguagestringLanguage of the Cashier or Operator. If different from the Login.
ShiftNumberstringShift number. If different from the Login, see Login SaleData.
SaleTransactionIDobjectIdentification of a transaction for the Sale System or the POI System.
TransactionIDstringUnique identification of a transaction to identify the transaction on the Sale System (e.g. ticket number), or the POI System.
TimeStampstringDate and time of a transaction for the Sale System, the POI System or the Acquirer. Ensures the uniqueness of a transaction and indicates the time when the event occurs in the EventNotification message.
SaleReferenceIDstringIdentification of a Sale global transaction for a sequence of related POI transactions. If payment reservation.
SaleTerminalDataobjectInformation related to the software and hardware features of the Sale Terminal. Sent in the Login Request if a Sale Terminal is involved in the login. In other messages, sent when a logical device is out of order (SaleCapabilities) or when other data have changed or were missing in the Login.
TotalsGroupIDstringIdentification of a group of transactions on a POI Terminal, having the same Sale features. Could be used to group POI for reconciliation or other purpose defined by the Sale System. The default value is assigned by the Login Request.
TokenRequestedTypestringType of token replacing the PAN of a payment card to identify the payment mean of the customer. It allows, for a merchant, to use a token for a transaction only or for a longer period. Possible values:
- Customer
- Transaction
CustomerOrderIDstringAdditional and optional identification of a customer order.
CustomerOrderReqarray[string]List of customer order open, closed or both to be sent in the response messages. Possible values:
- Both
- Closed
- Open
SaleToPOIDatastringSale information intended for the POI. Stored with the transaction.
SaleToAcquirerDatastringSale information intended for the Acquirer. Send to the Acquirer if present.
SaleToIssuerDataobjectSale information intended for the Issuer. The POI System receives this information and sends it to the Acquirer for the Issuer without any change.
StatementReferencestringLabel to print on the bank statement.
POIDataobjectData related to the POI System. In the Message Response, identification of the POI transaction.
POITransactionIDobjectIdentification of a transaction for the Sale System or the POI System.
TransactionIDstringUnique identification of a transaction to identify the transaction on the Sale System (e.g. ticket number), or the POI System.
TimeStampstringDate and time of a transaction for the Sale System, the POI System or the Acquirer. Ensures the uniqueness of a transaction and indicates the time when the event occurs in the EventNotification message.
POIReconciliationIDintegerIdentification of the reconciliation period between Sale and POI. If Result is Success.
LoyaltyResultarray[object]Data related to the result of a processed loyalty transaction. If loyalty account identified.
LoyaltyAccountobjectThis data structure conveys the identification of the account and the associated loyalty brand. Data related to a loyalty account processed in the transaction.
LoyaltyAccountIDobjectIdentification of a Loyalty account. In the Payment or the Loyalty Request message, it allows to identify the loyalty account by the Sale Terminal instead of the POI Terminal (e.g. because the account identification is a bar-code read by the Cashier on a scanner device).
EntryModearray[string]Entry mode of the payment instrument information. In the Payment, Loyalty or StoredValue Request messages, it informs the POI System the entry mode of the payment instrument information when read by the Sale Terminal. In the Payment, Loyalty or StoredValue Response messages, it informs the Sale System the entry mode of the payment instrument. Possible values:
- Contactless
- File
- ICC
- Keyed
- MagStripe
- Manual
- Mobile
- RFID
- Scanned
- SynchronousICC
- Tapped
IdentificationTypestringType of account identification. In a request message, it informs the POI System the type of the account or card identification, when provided by the Sale Terminal. (e.g. because the card information is a barcode read by the Cashier on a scanner device). In a response message, it informs the Sale System the type of the account or card identification. Possible values:
- AccountNumber
- BarCode
- ISOTrack2
- PAN
- PhoneNumber
IdentificationSupportstringSupport of the loyalty account identification. Allows knowing where and how you have found the loyalty account identification. Possible values:
- HybridCard
- LinkedCard
- LoyaltyCard
- NoCard
LoyaltyIDstringLoyalty account identification conforming to the IdentificationType.
LoyaltyBrandstringIdentification of a Loyalty brand. If a card is analysed.
CurrentBalancenumberMaximum: 99999999.999999Balance of an account. If known (provided by the card or an external host).
LoyaltyAmountobjectAmount of a loyalty account. An awarded amount or an amount to redeem to the loyalty account might be sent in the Payment request message.
LoyaltyUnitstringUnit of a loyalty amount. The amount could be expressed in point or in a monetary value and a currency. Possible values:
- Monetary
- Point
CurrencystringCurrency of a monetary amount.
AmountValuenumberMaximum: 99999999.999999Value of an amount.
LoyaltyAcquirerDataobjectData related to the loyalty Acquirer during a loyalty transaction. If content not empty.
LoyaltyAcquirerIDstringIdentification of the loyalty Acquirer.
ApprovalCodestringCode assigned to a transaction approval by the Acquirer. Could be an identifier of the approved transaction for the Acquirer. This data element is conditional for the Loyalty Acquirers. Used in the PaymentRequest request for a referral.
LoyaltyTransactionIDobjectIdentification of a transaction for the Sale System or the POI System.
TransactionIDstringUnique identification of a transaction to identify the transaction on the Sale System (e.g. ticket number), or the POI System.
TimeStampstringDate and time of a transaction for the Sale System, the POI System or the Acquirer. Ensures the uniqueness of a transaction and indicates the time when the event occurs in the EventNotification message.
HostReconciliationIDstringIdentifier of a reconciliation period with a payment or loyalty host. Allows the assignment of a transaction to the Acquirer reconciliation (or batch).
RebatesobjectRebate form to an award. If rebates awarded.
TotalRebatenumberMaximum: 99999999.999999The global awarded amount that is not attached to an item.
RebateLabelstringShort text to qualify a rebate on an line item. Text to be printed on a receipt in front of the rebate on an item or the rebate on the totals.
SaleItemRebatearray[object]The awarded amount that is attached to an item as a rebate. To be differentiated from the award which is the amount or quantity earned on the loyalty account.
ItemIDintegerItem identification inside a transaction (0 to n).
ProductCodeintegerMinimum: 1Maximum: 20Product code of item purchased with the transaction.
EanUpcintegerStandard product code of item purchased with the transaction.
UnitOfMeasurestringUnit of measure of a quantity. If Quantity present. Possible values:
- Case
- Centilitre
- Centimetre
- Foot
- Gram
- Inch
- Kilogram
- Kilometre
- Litre
- Meter
- Mile
- Other
- Ounce
- Pint
- Pound
- Quart
- UKGallon
- USGallon
- Yard
QuantitystringProduct quantity. If rebate is additional units.
ItemAmountnumberMaximum: 99999999.999999Total amount of the item line. If rebate on the line item amount.
RebateLabelstringShort text to qualify a rebate on an line item. If provided by the Acquirer.
PaymentReceiptarray[object]DocumentQualifierstringQualification of the document to print to the Cashier or the Customer. SaleReceipt or CashierReceipt. Possible values:
- CashierReceipt
- CustomerReceipt
- Document
- Journal
- SaleReceipt
- Voucher
IntegratedPrintFlagbooleanType of the print integrated to other prints.
RequiredSignatureFlagbooleanIndicate that the cardholder payment receipt requires a physical signature by the Customer.
OutputContentobjectContent to display or print. This is a sequence of elements if they have different formats.
OutputFormatstringFormat of the content to display or print. Display or print device function. Possible values:
- BarCode
- MessageRef
- Text
- XHTML
PredefinedContentobjectReference of a predefined message to display or print. It conveys information related to the predefined message.
ReferenceIDstringIdentification of a predefined message to display or print.
LanguagestringIdentification of a language.
OutputTextarray[object]Content of text message to display or print. Mandatory, if
OutputFormatis Text, not allowed otherwise. One instance ofOutputTextper shared format.TextstringContent of text message to display, print or play.
CharacterSetintegerCharacter height of the text string to display or print. Absence of this data element means the characters have normal height.
FontstringName of the font. Used to change character font of the output, as agreed between the POI and Sale Systems.
StartRowintegerMinimum: 1Maximum: 500Row where the text string has to be displayed or printed.
StartColumnintegerMinimum: 1Maximum: 500Column where the text string has to be displayed or printed.
ColorstringColor of the text string to display or print. Possible values:
- Black
- Blue
- Cyan
- Green
- Magenta
- Red
- White
- Yellow
CharacterWidthstringCharacter width of the text string to display or print. Absence of this data element means the characters have normal width. Possible values:
- DoubleWidth
- SingleWidth
CharacterHeightstringCharacter height of the text string to display or print. Absence of this data element means the characters have normal height. Possible values:
- DoubleHeight
- HalfHeight
- SingleHeight
CharacterStylestringTypographic style of the sequence of characters to display or print. Absence of this data element means the characters have normal style. Possible values:
- Bold
- Italic
- Normal
- Underline
AlignmentstringAlignment of the text string on the display line or print line. Absence of this data element means the characters have normal alignment. Possible values:
- Centred
- Justified
- Left
- Right
EndOfLineFlagbooleanIndicates if the text is at the end of a line. Allows the display or the print of a new line and a carry-over return characters after the formatted text.
OutputXHTMLstringXHTML document body containing the message to display or print. Mandatory if
OutputFormatis XHTML, not allowed otherwise.OutputBarcodeobjectBarcode content to display or print. Mandatory if
OutputFormatis Barcode, not allowed otherwise.BarcodeTypestringType of Barcode coding. Qualification of the barcode value to display or print. Possible values:
- Code128
- Code25
- EAN13
- EAN8
- PDF417
- QRCode
- UPCA
BarcodeValuestringValue with a Barcode coding. The barcode value to display or print.