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:

Lan Based

Requirements for LAN-based Pay@table integration:

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.
The Tyro terminals and the POS Pay@table server must be on the same Wi-Fi network or IP address subnet.
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:

Parameter	Description	Mandatory
amount	Amount in cents between 1 and 9999999	Yes
pos-reference	POS generated reference (must be unique for new sales but must be the same for subsequent requests in a split bill scenario)	Yes
display-text	Text that is displayed next to the amount on the select open sale screen when there is more than one open sale in the response. Due to screen size limitations only 6 characters can be displayed.	No
table	The table number associated with this open sale. Used only to indicate to the terminal that it should use the restaurant worlflow (i.e. offer split billing) if retireved using the 'BAR' button.	NO
always-return-outcome	All transaction outcomes should be reported back to the POS. This allows POSs with table locking workflows to know that they will always receive a response from the terminal so that the terminal
can also participate in the table locking workflow.	No (Default is false)

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:

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:

Parameter	Description	Mandatory
result	Always 'APPROVED'	Yes
table	The table number	No
approval-code	The issuer approval code	No
mid	The Tyro Merchant ID	Yes
tid	The Tyro Terminal ID	Yes
pos-reference	POS generated reference	Yes
response-message	The transaction response message. Always ‘APPROVED’ or ‘APPROVED W/ SIGNATURE’.	Yes
tip-amount	The tip amount to two decimal places in AUD.	Yes
base-amount	The transaction request amount to two decimal places in AUD	Yes
base-currency	The transaction request currency code. Always ‘AUD’	Yes
card-currency	The currency code that the transaction was processed in	Yes
card-type	The type of card used in the transaction. May be "EFTPOS", "Visa", "MasterCard", "American Express", "Diners Club", "JCB", "PayPal", "UnionPay". Tyro adds new card-types as new payment types are accepted so the list of card types will expand over time.	Yes
elided-pan	The card PAN with all digits shown as an ‘x’ except for the last four digits	Yes
gst-percentage	The percentage of the sale that attracts GST	No
operator-id	The Operator ID used to process the transaction	Yes
pan-length	The length of the PAN	Yes
rrn	The Retrieval Reference Number for the transaction (safe to consider as unique for a merchant in a 7 day period)	Yes
surcharge-amount	The surcharge amount added to two decimal places in AUD (incl. GST)	No
terminal-transaction-local-date-time	The local date time for the transaction. Format: YYYYMMDDHHMMSSZZZZZ	Yes
transaction-reference	The non-unique transaction reference	Yes
transaction-type	The type of transaction. Always ‘purchase’.	Yes
transmission-date-time	The date time that the transaction was transmitted to the issuer in UTC. Format: YYYYMMDDHHMMSSZZZZZ	Yes
transaction-amount	The total amount of the transaction (i.e. base amount plus tip amount plus surcharge amount) in the selected currency expressed with the appropriate number of decimal places for the currency	Yes
transaction-currency	The currency code that the transaction was processed in	Yes
exchange-rate	The exchange rate that the customer agreed to use expressed as a divisor	No
receipt-block	A plain text, pre-formatted receipt block suitable for printing/storing	Yes

Examples

Example 1: Transaction processed in AUD with surcharging

Copy

Copied

{
  "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

Copy

Copied

{
  "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

Copy

Copied

{
  "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

Copy

Copied

{
 "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.