Integrated Reconciliation
Reconciliation reports can be accessed through the TTA via the or .Net interface. The name of the interface is "Tyro.Integ.ITerminalAdapterReports". At the conclusion of the execution of the methods, control will be returned to the caller and an object containing the result of the operation will be given.
The reports returned are in an XML format and are intended for use within the POS for the purposes of reconciliation. The typical use of these reports is to perform a card reconciliation at the end of the day and compare card transactions stored in the POS with card transactions retrieved from Tyro. A suggested approach is to first download the summary report and compare totals. If the totals match up then the reconciliation can be considered to have passed. If the totals do not match, then the detailed report should be downloaded so that each transaction can be verified. From there a 'overs and unders' report can be generated by the POS and the POS operators can be notified about the transactions that are missing.
Methods
The ITerminalAdapterReports interface exposes the following methods:
- IReport ReconciliationReportSummary(string date) : This method makes an HTTPS GET request to the Tyro Integration Server requesting a summary reconciliation report for the date specified (format yyyyMMdd). It uses the default MID and TID configured in the TTA configuration panel. An instance of IReport is returned that the caller can interrogate for the report information.
- IReport ReconciliationReportDetailed(string date) : This method make an HTTPS GET request to the Tyro Integration Server requesting a detailed reconciliation report for the date specified (format yyyyMMdd). It uses the default MID and TID configured in the TTA configuration panel. An instance of IReport is returned that the caller can interrogate for the report information.
- IReport ReconciliationReportSummaryMidTid(string mid, string tid, string date) : This method make an HTTPS GET request to the Tyro Integration Server requesting a summary reconciliation report for the mid, tid and date specified (format yyyyMMdd). An instance of IReport is returned that the caller can interrogate for the report information.
- IReport ReconciliationReportDetailedMidTid(string mid, string tid, string date) : This method make an HTTPS GET request to the Tyro Integration Server requesting a detailed reconciliation report for the mid, tid and date specified (format yyyyMMdd). An instance of IReport is returned that the caller can interrogate for the report information.
Return Value
The IReport interface contains the following methods:
- boolean ErrorOccurred() : This method returns true if a configuration or network error occurred. In this case the caller should call the GetError() method to determine what the cause of the error was so that corrective action can be take. A return value of false indicates that the call executed successfully.
- string GetText() : This method returns the text associated with the report. The text is an XML document and the format of the XML document is detailed below.
- Error GetError() : This method returns an Error object that allows the caller to determine things like the HttpStatusCode, the ErrorMessage and other useful pieces of information.
- string GetMid() : The mid associated with the report.
- string GetTid() : The tid associated with the report.
- string GetyyyyMMdd() : The date associated with the report.
Notes on integrated reconciliation functions:
- The reporting functions can be called at anytime of the day.
- The reporting functions can be called multiple times per day.
- The reporting functions can only be used to request reports no older than 7 days.
Response & Response Error Codes
The following HTTP error codes may be returned for an Integrated Reporting request. The value can be access via IReport.getError().
StatusCode
| HTTP Code | HTTP Name | When |
|---|---|---|
| 200 | OK | Request succeeds |
| 202 | Accepted | System not ready to receive requests |
| 400 | Bad Request | Request does not conform to requirements |
| 403 | Authentication Failed | Submitted key does not match Terminal's key |
| 404 | Not Found | Terminal is not connected to Tyro |
| 500 | Server Error | Error in Tyro system - Please report these to Tyro |
| 501 | Not Implemented | The operation is not available |
| 504 | Gateway Timeout | Request timed out before response could be generated |
Summary Report
| Response Parameter Name | Description |
|---|---|
| reconciliation-summary/@mid | The mid (Merchant ID) for this report |
| reconciliation-summary/@tid | The tid (Terminal ID) for this report |
| reconciliation-summary/@terminal-business-day | The terminal business day for this report (format yyyy-MM-dd) |
| reconciliation-summary/@total | The total amount of all the transactions for the business day |
| reconciliation-summary/card | The list of card schemes that we report on (currently 6 - Visa, MasterCard, EFTPOS, Amex, Diners, JCB). Within each card element, the following attributes are possible: |
| @type (the type of card scheme - one of visa, mastercard, eftpos, amex, diners, or jcb) | |
| @purchases (the total amount of purchases) | |
| @cash-out (the total amount of cash out) | |
| @refunds (the total amount of refunds - shown as a negative amount) | |
| @total (the net total for the card scheme) |
Detail Report
| Response Parameter Name | Description |
|---|---|
| reconciliation-detail/@mid | The mid (Merchant ID) for this report |
| reconciliation-detail/@tid | The tid (Terminal ID) for this report |
| reconciliation-detail/@terminal-business-day | The terminal business day for this report (format yyyy-MM-dd) |
| reconciliation-detail/@total | The total amount of all the transactions for the business day |
| reconciliation-detail/transaction | The list of transactions processed by that terminal on that business day. Within each transaction element, the following attributes are possible: |
| @type (the type of transaction processed - one of purchase, refund, or void) | |
| @card-type (the type of card scheme - one of visa, mastercard, eftpos, amex, diners, or jcb) | |
| @amount (the amount of the transaction - not including tip or cash out amount) | |
| @cash-out (the cash-out amount for the transaction) | |
| @tip (the tip amount for the transaction) | |
| @transaction-local-date-time (the local time that the transaction was processed on - format yyyy-MM-dd HH:mm:ss) | |
| @tyro-reference (a Tyro reference for the transaction - not unique but is unique when combined with MID, TID, and business day) | |
| @merchant-reference (the integrated transaction ID - optionally passed in by an integrated POS when the transaction was initiated) | |
| @settlement-date (the settlement date for the transaction - not known for Amex, Diners, or JCB) |
Summary Report example response
<?xml version="1.0" encoding="UTF-8"?>
<reconciliation-summary mid="200" tid="200" terminal-business-day="2011-
09-14" total="1620.00">
<card type="visa" purchases="280.00" refunds="-70.00" total="210.00"
/>
<card type="mastercard" purchases="200.00" refunds="-80.00" total="
120.00"/>
<card type="eftpos" purchases="1100.00" cash-out="50.00" refunds="
0.00" total="1150.00"/>
<card type="amex" purchases="30.00" refunds="0.00" total="30.00"/>
<card type="diners" purchases="70.00" refunds="0.00" total="70.00"/>
<card type="jcb" purchases="40.00" refunds="0.00" total="40.00"/>
</reconciliation-summary>Detail Report example response
<?xml version="1.0" encoding="UTF-8"?>
<reconciliation-detail mid="200" tid="200" terminal-business-day="2011-
09-14" total="1620.00">
<transaction type="purchase" card-type="visa" amount="100.00" tip="
10.00" transaction-local-date-time="2011-09-14 12:30:30" tyroreference="870020" merchant-reference="071061048231306351219677"
settlement-date="2011-09-16"/>
<transaction type="purchase" card-type="mastercard" amount="200.00"
transaction-local-date-time="2011-09-14 12:31:20" tyro-reference="
885214" merchant-reference="071061048231306351219678" settlement-date="
2011-09-16"/>
<transaction type="purchase" card-type="jcb" amount="40.00"
transaction-local-date-time="2011-09-14 12:33:23" tyro-reference="
896534" merchant-reference="071061048231306351219679"/>
<transaction type="purchase" card-type="amex" amount="30.00"
transaction-local-date-time="2011-09-14 12:36:35" tyro-reference="
905845" merchant-reference="071061048231306351219680"/>
<transaction type="purchase" card-type="eftpos" amount="650.00" cashout="50.00" transaction-local-date-time="2011-09-14 12:40:30" tyroreference="912556" merchant-reference="071061048231306351219681"
settlement-date="2011-09-16"/>
<transaction type="purchase" card-type="eftpos" amount="450.00"
transaction-local-date-time="2011-09-14 12:50:30" tyro-reference="
920187" merchant-reference="071061048231306351219682" settlement-date="
2011-09-16"/>
<transaction type="purchase" card-type="diners" amount="70.00"
transaction-local-date-time="2011-09-14 13:30:30" tyro-reference="
935587" merchant-reference="071061048231306351219683"/>
<transaction type="void" card-type="mastercard" amount="-80.00"
transaction-local-date-time="2011-09-14 13:50:30" tyro-reference="
946585" merchant-reference="071061048231306351219684" settlement-date="
2011-09-16"/>
<transaction type="purchase" card-type="visa" amount="170.00"
transaction-local-date-time="2011-09-14 14:23:25" tyro-reference="
953594" merchant-reference="071061048231306351219685" settlement-date="
2011-09-16"/>
<transaction type="refund" card-type="visa" amount="-70.00"
transaction-local-date-time="2011-09-14 15:41:12" tyro-reference="
962548" merchant-reference="071061048231306351219685" settlement-date="
2011-09-16"/>
</reconciliation-detail>Empty Summary Report example response
<?xml version="1.0" encoding="UTF-8"?>
<reconciliation-summary mid="200" tid="200" terminal-business-day="2011-
05-28" total="0.00">
<card type="visa" purchases="0.00" refunds="0.00" total="0.00"/>
<card type="mastercard" purchases="0.00" refunds="0.00" total="0.00"
/>
<card type="eftpos" purchases="0.00" cash-out="0.00" refunds="0.00"
total="0.00"/>
<card type="amex" purchases="0.00" refunds="0.00" total="0.00"/>
<card type="diners" purchases="0.00" refunds="0.00" total="0.00"/>
<card type="jcb" purchases="0.00" refunds="0.00" total="0.00"/>
</reconciliation-summary>Empty Detail Report example response
<?xml version="1.0" encoding="UTF-8"?>
<reconciliation-detail mid="200" tid="200" terminal-business-day="2011-
05-28" total="0.00"></reconciliation-detail>info
Note: The XML used in the reports does not come with a DTD or XML Schema. We reserve the right to add elements or attributes in the future if we need to. We will not, however, remove elements or attributes. Our suggestion is that developers use XPath for retrieving data from the XML responses.