LAN-based Pay@table integrations

LAN-based Pay@table integration is the Pay@table integration pathway that provides a simpler, easy-to-implement, and more localized implementation of Pay@table integration. LAN-based Pay@Table integration entails a locally-hosted POS Pay@table server communicating to the Tyro terminals and the POS system, this means that the terminals are communicating directly to the local POS Pay@table server, with the POS Pay@table server managing communication between the POS system and the Tyro terminals.

The communication pathways and the information exchanged between the POS Pay@table server and the Tyro terminal for LAN-based Pay@table integrations is specified in the image below:

Requirements for LAN-based Pay@table integration:

1. Three URLs (open sales, transaction result, diagnostics) for the local POS Pay@table server (with the http prefix) along with a passphrase meeting the criteria defined in the certification criteria are to be specified for each merchant location.
2. The Tyro terminals and the POS Pay@table server must be on the same Wi-Fi network or IP address subnet.
3. LAN-based Pay@table integrations are not operable using the 3G terminal connectivity mode due to the limitation described in point 2.

Requesting open sales

Sample URL schematics:

• LAN-based Pay@table: http://[pos server IP address] [:port] /open-sales
• Cloud-based Pay@table: https://my.pos.server/open-sales

The terminal will make an HTTP GET request of this URL after appending a (numeric) operatorId parameter, an optional (numeric) table parameter, an alpha-numeric value for the Merchant ID (mid) and an alpha-numeric value for the Terminal ID (tid) which in this case would be, for example:

• LAN-based Pay@table: http://[pos server IP address] [:port] /open-sales?operatorId=2175&mid=1234&tid=5 [&table=37]
• Cloud-based Pay@table: https://my.pos.server/open-sales?operatorId=2175&mid=1234&tid=5[&table=37 ]

The table parameter is only provided when the terminal is in one of the two 'Restaurant' modes and is provided to the POS as an additional data element to help the POS system narrow down the list of open sales to return to the terminal.

The response from the POS server will be in a list of open sales JSON format where an open sale is made up of the following attributes:

Examples:

• Single open sale:

{"open-sales":[{"amount":"4595","pos-reference":"abc123"}]}

• Multiple open sales:

{"open-sales":[{"amount":"5000","pos-reference":"abc123","display-text":"group1"},{"amount":"2000","pos-reference":"abc124","display-text":"group2},{"amount":"2000","pos-reference":"abc125","display-text":"group3},{"amount":"10000","pos-reference":"abc126,"display-text":"group4"}]}

• No open sales:

{"open-sales":[]}

• Single open sale with always-report-outcome:

{"open-sales":[{"amount":"4595","pos-reference":"abc123"}], "always-return-outcome":"true"}

• Multiple open sales with always-report-outcome:

{"open-sales":[{"amount":"5000","pos-reference":"abc123","display-text":"group1"},{"amount":"2000","pos-reference":"abc124","display-text":"group2},{"amount":"2000","pos-reference":"abc125","display-text":"group3},{"amount":"10000","pos-reference":"abc126,"display-text":"group4"}], "always-return-outcome":"true"}

The response must have the content-type set to text/plain (all other content-types are rejected) and a character encoding of ISO-8859-1 (LATIN1).

Error codes:

• If the requested table does not exist, the POS server must return an HTTP status code of 400.
• If the operatorId is invalid, the POS server must return an HTTP status code of 401.
• If the table is unavailable (due to locking etc.), the POS server must return an HTTP status code of 412. An optional status message can be added to the content of this response which will be displayed on the terminal. The maximum message length for this message is ninety characters. If the message is longer than ninety characters, the first ninety characters will be displayed. If no message is provided, a default message of "Table is unavailable at this time" will be displayed.

Please note also that HTTP URL redirects will not be followed by the terminal.

Posting approved transaction result for a table

Sample URL schematics:

• LAN-based Pay@table: http://[pos server IP address] [:port] /transaction-result
• Cloud-based Pay@table: https://my.pos.server/transaction-result

The terminal will send an HTTP POST request to this URL where the message body contains the approved transaction result in JSON format (content-type text/plain) containing the following data:

Examples

Example 1: Transaction processed in AUD with surcharging

{
  "approval-code": "027573",
  "base-amount": "100.00",
  "base-currency": "AUD",
  "card-currency": "AUD",
  "card-type": "American Express",
  "elided-pan": "xxxxxxxxxxx8431",
  "issuer-action-code": "00",
  "mid": "25",
  "operator-id": "10",
  "pan-length": "15",
  "pos-reference": "VE39LVUXNY",
  "receipt-block": "removed for brevity",
  "response-message": "APPROVED",
  "result": "APPROVED",
  "rrn": "565351134949",
  "surcharge-amount": "3.00",
  "table": "0",
  "terminal-transaction-local-date-time": "20160923134949+1000",
  "tid": "488",
  "tip-amount": "0.00",
  "transaction-amount": "103.00",
  "transaction-currency": "AUD",
  "transaction-reference": "565351",
  "transaction-type": "purchase",
  "transmission-date-time": "20160923034949+0000"
}

Example 2: Transaction in AUD with surcharging and tip

{
  "approval-code": "027576",
  "base-amount": "100.00",
  "base-currency": "AUD",
  "card-currency": "AUD",
  "card-type": "American Express",
  "elided-pan": "xxxxxxxxxxx8431",
  "issuer-action-code": "00",
  "mid": "25",
  "operator-id": "10",
  "pan-length": "15",
  "pos-reference": "LQZRW1EUX4",
  "receipt-block": "removed for brevity",
  "response-message": "APPROVED",
  "result": "APPROVED",
  "rrn": "565358143510",
  "surcharge-amount": "3.00",
  "table": "0",
  "terminal-transaction-local-date-time": "20160923143510+1000",
  "tid": "488",
  "tip-amount": "10.00",
  "transaction-amount": "113.00",
  "transaction-currency": "AUD",
  "transaction-reference": "565358",
  "transaction-type": "purchase",
  "transmission-date-time": "20160923043511+0000"
}

Example 3: Transaction in USD with tip

{
  "approval-code": "037492",
  "base-amount": "100.00",
  "base-currency": "AUD",
  "card-currency": "USD",
  "card-type": "Visa",
  "elided-pan": "xxxxxxxxxxxx0010",
  "exchange-rate": "1.390000000",
  "issuer-action-code": "00",
  "mid": "25",
  "operator-id": "10",
  "pan-length": "16",
  "pos-reference": "JS44PCP5P1",
  "receipt-block": "removed for brevity",
  "response-message": "APPROVED",
  "result": "APPROVED",
  "rrn": "626716706773",
  "surcharge-amount": "0.00",
  "table": "0",
  "terminal-transaction-local-date-time": "20160923160940+1000",
  "tid": "488",
  "tip-amount": "10.00",
  "transaction-amount": "79.14",
  "transaction-currency": "USD",
  "transaction-reference": "706773",
  "transaction-type": "purchase",
  "transmission-date-time": "20160923060940+0000"
}

Example 4: Transaction in USD with receipt block

{
 "approval-code": "000003",
 "base-amount": "100.00",
 "base-currency": "AUD",
 "card-currency": "AUD",
 "card-type": "Visa",
 "elided-pan": "xxxxxxxxxxxx9521",
 "issuer-action-code": "00",
 "mid": "850",
 "operator-id": "6",
 "pan-length": "16",
 "pos-reference": "6UDMSOZA9O",
 "receipt-block": "
       Pay@table test      
      123 test street      
      Sydney NSW 2000      
 
       MERCHANT COPY       
 
    Tyro Payments EFTPOS   
 
NAB Visa Credit
AID: A0000000031010
Card: xxxxxxxxxxxx9521 (t)
 
Purchase    AUD     $100.00
Surcharge   AUD       $0.50
                 ----------
Total       AUD     $100.50
 
APPROVED              00
 
Table number: 2
Terminal ID: 437
Transaction Ref: 460030
Authorisation No: 000003
25 Jan 2021 at 02:19 PM
 
Retain copy for your records
 
Response time: 1.12 sec
 
",
 "response-message": "APPROVED",
 "result": "APPROVED",
 "rrn": "102514460030",
 "surcharge-amount": "0.50",
 "table": "2",
 "terminal-transaction-local-date-time": "20210125141924+1100",
 "tid": "437",
 "tip-amount": "0.00",
 "transaction-amount": "100.50",
 "transaction-currency": "AUD",
 "transaction-reference": "460030",
 "transaction-type": "purchase",
 "transmission-date-time": "20210125031925+0000"
}

Error codes:

• To acknowledge the request from the terminal, the POS server will return a HTTP status code of 200 (OK).
• A HTTP status code other than 200 sent by the POS server will be interpreted as a permanent error condition and the terminal will reset ready for the next transaction. If the terminal does not receive any response from the POS server, the terminal will continue to send the transaction result through until a response is received.

Please note that as the terminal will resend transaction results through until a response is received, POS servers should implement a facility to handle duplicate receipt of transaction results. To ensure that the POS server can determine the authenticity of the message, the terminal must include a Message Authentication Code (MAC) as an HTTP header (with name x-tyro-mac). Please refer to Appendix A for details regarding how to generate and verify the MAC for the message.

To learn more, please refer to the Posting cancelled transaction result for a table section.