Hospitality Integration Attributes

Input Request Attributes

The Hospitality transaction request is a Name Value pair format. There is a name (number) associated with all the attributes of the transaction. The EPOS application needs to send a list of attributes and their values in the request. Each attribute Name Value pair is separated by a Line Feed.

This is the list of input attributes for a transaction, showing Input and Output attributes specifically for Hospitality along with other attributes which are the same as retail:

DescriptionAttribute NameData TypeLengthMandatory/Conditional/Optional
MTR - Merchant Transaction reference
Uniquely identifies the transaction with a user defined tag. Hospitality does not enforce uniqueness for this attribute. It is recommended that the merchant constructs the transaction reference so that it is specific enough to allow transactions to be reconciled with accuracy. It is strongly recommended that the MTR field contains only the allowed characters defined in ‘Data Type'. If it should contain non-allowed characters then Hospitality will sanitize the content and exclude all characters not listed in 'Data Type'. Hospitality will use the sanitized MTR to process the transaction, however it will send the original content of this field in its output response.
1Allowed: Alpha Numeric, Hyphen(-), Underscore(_)Not Allowed: Consecutive Hyphen(--)0-30Mandatory
Transaction Type
Transaction Type indicates the type of financial transaction.

Transaction Type

Description

0

Sale
Includes Sale with Cashback

3

Cancel Transaction

20

Refund

40

Poll transaction Status
Value of (2=40) is used to query the status of previously submitted requests. For response see format of output.txt.
Set the target reference in attribute 97 to specify the transaction for which the status is required.

41

Delete transactions
Value of (2=41) is used to delete a transaction previously submitted. For response see format of output.txt.
Set the target reference in attribute 97 to specify the transaction to be deleted.

42

Poll Close Table requests
Value of (2=42) is used to get the table reference numbers for all submitted Close Table requests.
Other attributes of this request are the same as the Poll Transaction Status request except that attribute 97 (Target Reference) must not be included. For response format please see format of output.txt.

43

Close Transaction
Value of (2=43) is used to close ‘Pending’ and ‘Partially Complete’ transactions from the queue. This will mark the transaction status as ‘Complete’.
For sample request referhere

12

Sale with Token

13

Refund with Token

58

Account Verification

26

Get serial number (PTID) of PED connected

24

To check PED is connected with HPA application or not.
For sample request refer [here] (/docs/worldpay-total-hospitality-4-0-00/payatcounter-transaction-requests-responses-#check-pinpad-connection)

36

To generate X report.
For sample request refer [here] (/docs/worldpay-total-hospitality-4-0-00/payatcounter-transaction-requests-responses-#x-report)

37

To generate Z report.
For sample request refer [here] (/docs/worldpay-total-hospitality-4-0-00/payatcounter-transaction-requests-responses-#z-report)

64

Cashback Transation Response
This attribute is used by EPOS to send the cashback transaction response to Hospitality.
For sample request refer [here] (/docs/worldpay-total-hospitality-4-0-00/transaction-requests-responses#cashback)

66

Signature Verification Response
This attribute is used by POS to send the signature verification response to hospitality application.
For sample request refer [here] (/docs/worldpay-total-hospitality-4-0-00/payatcounter-transaction-requests-responses-#sending-signature-verification-response-to-pos)

2IntegerN/AMandatory
Transaction Amount
Transaction amount is in major currency units e.g. 3=10.23
Amount must be non-zero, non-negative and less than 99999.99. Please note however that transactions above the terminal’s ceiling limit will be cancelled even if they are less than 9999999.99. The Ceiling limit is defined by acquirer and varies by acquirer. Only 2 digits are allowed after the decimal point
3DecimalN/AMandatory
Cashback Amount
Used by EPOS to provide cashback amount to Hospitality
For sample request referhere
4DecimalAllowed values are 0 to 100 (current max cashback amount)Conditional
Mandatory in case of cashback
Masked PAN
This attribute is required for the Cancel transaction.
5Alpha Numeric13-19Conditional
Mandatory for Cancel transaction
Card Expiry Date
This attribute is required for the Cancel transaction in MMYY format.Note: The expiry date parameter in Cancel transactions has been retained for backwards compatibility, however any expiry date corresponding to MMYY format is accepted.
6Integer4Conditional
Mandatory for Cancel transaction
PGTR - Payment Gateway Transaction Reference This attribute is required for the Cancel transaction - it specifies the WPT Central Service reference of the transaction to be cancelled. (Returned in field 28 of Hospitality response message. Refer response message detailshere.13Alpha Numeric12-14Conditional
Mandatory for Cancel transaction
Token Reference19Alpha Numeric20Conditional
Mandatory for Sale with Token request i.e. when charging a token returned from the Account Verification request
Table Poll Filter
This field specifies a filter for table polling and is used where multiple EPOS applications are sending requests to Hospitality and any individual EPOS can specify tables to be closed. For example: 76= [12, 15] (comma separated list of table number)
76Numeric, Comma (,), Square brackets ([ ])N/AConditional
Optional if a single EPOS application is sending requests to Hospitality.
Mandatory in case of multiple EPOS
Target reference
This is the reference number by which terminal operators select the transaction in Pay@Table mode.For example, the table number, or if Pre-Sets are implemented, up to the first 10 digits could be the pre-set number and the remaining 2 digits could be the table number.
97Alpha Numeric12Conditional
Mandatory in the case of Pay@Table transactions
Do not use in case of Pay@Counter request
Sales Invoice Text This field specifies invoice/bill content sent by the EPOS application to Hospitality to be printed via the PED. It only is only supported with the Sale transaction. For sample request referhere98Alpha Numeric
Currency signs are NOT supported within invoice content
N/AOptional
End of MessageIndicates the end of the transaction request99Integer1Mandatory value of 0
Pay@Table PayNow/No Table Instance ID
Applies to Pay@Table transactions only
Defines the Instance ID of the PED on which transaction is to be processed. Format for Instance ID is INST followed by numeric 1,2,3 etc. e.g. INST1,INST2
101Alpha NumericDefined format
INSTxx where xx is a number between 1 and 99
Conditional
Mandatory in the case of Pay@Table for CNP and PayNow (No Table) transactions
Do not use in case of Pay@Counter transaction request.
Pay@Counter Instance ID
Applies to Pay@Counter transactions only
Defines the Instance ID of the PED on which transaction is to be processed. Format for Instance ID is INST followed by numeric 1,2,3 etc. e.g. INST1,INST2.
For sample request referhere
107Alpha NumericDefined format INSTxx where xx is a number between 1 and 99Conditional Mandatory in the case of Pay@Counter.
Do not use in case of Pay@Table transaction request.
Transaction Purpose
This attribute is mandatory for Account Verification, and when charging the token returned from an Account Verification transactions. It flags that these transactions are Unscheduled Card on File transactions. Its value must be 'N'.
03Alpha1Conditional
Mandatory value of N for Account Verification request, and when charging a token returned from the Account Verification request.
Validate Waiter ID
When Waiter ID is configured, this attribute is used by EPOS to confirm Hospitality the validity of a Waiter ID entered by the operator in Pay@Table transactions. Based on this value received from EPOS Hospitality proceeds further for payment.If Hospitality receives INVALID response from EPOS for a particular Waiter ID then it will not allow user to process the transaction.
Format of this attribute is [WAITERID1:VALID,WAITERID2:INVALID] were Waiter ID can be numeric or alphanumeric value.
E.g. 106 [WAITERID1:VALID,WAITERID2:INVALID].
106Alpha NumericDefined formatConditional
Mandatory ifIdentify Waiter from PEDfunctionality is enabled to validate ‘Waiter ID’.
Validate Signature on card.
Signature verification response can be sent to Hospitality application in the form of value 0or 1
108 = 0 or 1.
108Numeric1Mandatory.
Fixed gratuity amount.
This attribute helps merchants to send fixed gratuity amount to hospitality application and value 'G' in attribute 114 is mandatory with this attribute.
Applies to Pay@Counter transactions and not table transactions in pay at table mode.
Maximum value support is 9999.99
115Numeric7Conditional.
Mandatory for Fixed gratuity transactions.
Transaction level control of gratuity, donation & cashback.
This attribute helps merchants to supress gratuity, donation and cashback at transaction level.
Applies to Pay@Counter and pay@table both.
Below values are allowed:
1. C – Representing Cashback
2. G – Representing Gratuity
3. D – Representing Donation
4. N - Represents merchant did not want to prompt for any one of the above
114Alpha (case sensitive) only capital letters are allowed3Conditional.
Mandatory for controling gratuity, donation & cashback at transaction level.
Updating payment request/billing items.
This attribute helps merchants to update billing items or sale amount for transactions already exists in queue.
Applies to pay@table.
Only value 'U' (capital letters) is allowed in this attribute and it is case sensitive
113Alpha (case sensitive)1Conditional.
Mandatory in case of updating payment request/billing items.