Tyro Connect Reporting API
Provides merchant settlement and transaction reporting for Tyro-acquired payments, returning settlement batches and dated transaction listings for reconciliation and financial reporting by app partners.
OpenAPI Specification
openapi: 3.1.0
info:
title: Reporting API
version: '1.0'
contact: {}
description: >-
This API allows you to retrieve various transaction and settlements data for
a given mid.
servers:
- url: https://api.tyro.com/connect
description: Production
paths:
/reporting/merchants/{mid}/settlements?settlementDate={settlementDate}:
get:
responses:
'200':
description: Settlements response
content:
application/json:
schema:
$ref: '#/components/schemas/reporting-settlements-response'
examples:
Single Settlement Returned:
value:
mid: '111'
settlementDate: '2021-07-01'
settlements:
- clearingPaymentId: e6da4a8e-70f3-4156-9b81-f027f061d59e
grossAmount: 20011
settlementDetails:
- type: EXTERNAL_BANK_ACCOUNT
bsb: '840300'
institutionName: MyBank
accountNumber: '****9201'
accountName: Potene Enterprises Pty Ltd
settlementAmount: 20011
lastUpdatedAt: '2021-07-01T13:45:15.000Z'
settlementStatus: SENT
lodgementReference: Tyro July 1st
Multiple Settlements Returned:
value:
mid: '112'
settlementDate: '2021-07-01'
settlements:
- clearingPaymentId: e6da4a8e-70f3-4156-9b81-f027f061d59e
grossAmount: 150032
settlementDetails:
- type: EXTERNAL_BANK_ACCOUNT
institutionName: MyBank
bsb: '840300'
accountNumber: '****9201'
accountName: Potene Enterprises Pty Ltd
settlementAmount: 20011
lastUpdatedAt: '2021-07-01T13:45:15.000Z'
settlementStatus: SENT
lodgementReference: Tyro July 1st
- type: EXTERNAL_BANK_ACCOUNT
institutionName: MyBank
bsb: '840300'
accountNumber: '****9201'
accountName: Potene Enterprises Pty Ltd
settlementAmount: 120021
settlementStatus: PENDING
lodgementReference: Tyro July 1st
- type: TYRO_BANK_ACCOUNT
'400':
description: Bad Request - Missing or invalid parameters
content:
application/json:
schema:
type: object
properties:
error:
type: string
errorCode:
type: string
errors:
type: array
items:
type: object
message:
type: string
'403':
description: >-
Forbidden - When you don't have the required permissions to query
the provided location
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: >-
This endpoint allows you to retrieve BECs-cleared settlement details for
a specific merchant on a given date.
parameters:
- in: path
description: >-
The merchant ID associated with the Tyro account. Used to identify
the merchant whose settlement data is being retrieved.
name: mid
required: true
schema:
type: string
- in: query
description: >-
Requested settlement date (YYYY-MM-DD). Must be within the past 3
years.
name: settlementDate
required: true
schema:
type: string
format: date
- $ref: '#/components/parameters/header-bearer-token'
operationId: get-reporting-settlements
summary: Get Settlements for a Merchant
security:
- JWT: []
/reporting/merchants/{mid}/transactions?transactionDate={transactionDate}&limit=100&page=1:
get:
responses:
'200':
description: Transactions response
content:
application/json:
schema:
$ref: '#/components/schemas/reporting-transactions-response'
examples:
Multiple Transactions:
value:
terminalBusinessDay: '2025-05-26'
merchantDetails:
mid: '122'
tradingName: Test Merchant
transactions:
- transactionId: >-
5c05f70e3f0e3bd3b5359d5cf20e5a75fb4dd525229350e15137e78f1bfa4de6
transactionLocalDateTime: '2025-05-26T00:22:06'
transactionStatus: APPROVED
transactionDescription: null
locationId: '122'
tid: 7
deviceType: BYO
mobilePlatformType: null
paymentType: GOODS_AND_SERVICES
feeType: INTERNATIONAL
fromAccountType: CREDIT
isExpressPayment: false
card:
type: MASTERCARD
cardLastFour: XXXXXXXXXXXX0007
cardEntryMode: MAG_STRIPE
cardPresent: true
isEcommerceTransaction: false
ecommerceOrderId: null
isRefund: false
refundReason: null
isReversal: false
reversalReason: null
isInternational: true
dcc:
currencyCode: null
exchangeRate: null
foreignCurrencyAmount: null
merchantCommissionAmount: 0
amountDetails:
saleAmount: 9000
refundAmount: 0
tipAmount: 1000
cashOutAmount: 0
surchargeAmount: 409
donationAmount: 0
totalAmount: 10409
amountToPayMerchant: 10000
settlementAmount: 10000
merchantAcquiringFee: 0.2602
acquirerActionCode: APPROVED
rrn: 514600990020
tyroReference: 990020
integratedTransactionId: 85c9090d-3a80-4c2f-8e3a-f2513f3426f0
- transactionId: >-
871b9690255b6203b7c2845cde6aebd5bb2b3f7142807472345627055876e7c6
transactionLocalDateTime: '2025-05-26T00:22:06'
transactionStatus: APPROVED
transactionDescription: null
locationId: '122'
tid: 7
deviceType: DX4000
mobilePlatformType: null
paymentType: GOODS_AND_SERVICES
feeType: INTERNATIONAL
fromAccountType: CREDIT
isExpressPayment: false
card:
type: VISA
cardLastFour: XXXXXXXXXXXX0002
cardEntryMode: MAG_STRIPE
cardPresent: true
isEcommerceTransaction: false
ecommerceOrderId: null
isRefund: false
refundReason: null
isReversal: false
reversalReason: null
isInternational: true
dcc:
currencyCode: null
exchangeRate: null
foreignCurrencyAmount: null
merchantCommissionAmount: 0
amountDetails:
saleAmount: 9000
refundAmount: 0
tipAmount: 1000
cashOutAmount: 0
surchargeAmount: 135
donationAmount: 0
totalAmount: 10135
amountToPayMerchant: 10000
settlementAmount: 10000
merchantAcquiringFee: 0.2534
acquirerActionCode: APPROVED
rrn: 514600990018
tyroReference: 990021
integratedTransactionId: af40e34f-3a80-4c2f-8e3a-f25139ae342b
- transactionId: >-
45b60cf98f723bd3b5359d5cf20e5a75fb4dd525229350e15137eae654e210b3
transactionLocalDateTime: '2025-05-26T00:22:06'
transactionStatus: APPROVED
transactionDescription: null
locationId: '122'
tid: 7
deviceType: null
mobilePlatformType: null
paymentType: REFUND_GOODS_AND_SERVICES
feeType: INTERNATIONAL
fromAccountType: CREDIT
isExpressPayment: false
card:
type: VISA
cardLastFour: XXXXXXXXXXXX0002
cardEntryMode: MAG_STRIPE
cardPresent: true
isEcommerceTransaction: false
ecommerceOrderId: null
isRefund: true
refundReason: null
isReversal: false
reversalReason: null
isInternational: true
dcc:
currencyCode: null
exchangeRate: null
foreignCurrencyAmount: null
merchantCommissionAmount: 0
amountDetails:
saleAmount: 0
refundAmount: -10000
tipAmount: 0
cashOutAmount: 0
surchargeAmount: 0
donationAmount: 0
totalAmount: -10000
amountToPayMerchant: -10000
settlementAmount: -10000
merchantAcquiringFee: 0
acquirerActionCode: APPROVED
rrn: 990021002206
tyroReference: 990018
integratedTransactionId: 5253aa4e-95dd-466b-9e4e-1fee1b640e77
pagination:
page: 1
size: 3
limit: 100
total: 3
'400':
description: Bad Request - Missing or invalid parameters
content:
application/json:
schema:
type: object
properties:
error:
type: string
errorCode:
type: string
errors:
type: array
items:
type: object
message:
type: string
'403':
description: >-
Forbidden - When you don't have the required permissions to query
the provided location
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: >-
This endpoint allows you to retrieve a merchant's list of transactions
for a given terminal business day.
parameters:
- in: path
description: >-
The merchant ID associated with the Tyro account. Used to identify
the merchant whose transaction data is being retrieved.
name: mid
required: true
schema:
type: string
- in: query
description: >-
The date (YYYY-MM-DD) that the terminal has processed the requested
transactions. Must be within the past 3 years.
name: transactionDate
required: true
schema:
type: string
format: date
- in: query
schema:
type: number
minimum: 1
maximum: 2000
example: 100
name: limit
required: true
description: Specifies the amount of results to be retrieved.
- in: query
schema:
type: number
minimum: 1
example: 2
name: page
required: true
description: >-
Specify the page to retrieve.
Page-numbering is based on the value of "limit". If limit=5, then
page=1 will display the hits from 1 to 5, page=3 will display the
hits from 11 to 15.
Page numbers start at 1.
A request for a non-existing page will yield 0 results.
- $ref: '#/components/parameters/header-bearer-token'
operationId: get-reporting-transactions
summary: Get Transactions for a Merchant
security:
- JWT: []
components:
securitySchemes:
JWT:
type: openIdConnect
openIdConnectUrl: https://auth.connect.tyro.com/.well-known/openid-configuration
parameters:
header-bearer-token:
schema:
type: string
default: Bearer {$$.env.access_token}
in: header
name: Authorization
required: true
schemas:
settlement-details:
title: Settlements Detail
type: object
properties:
type:
type: string
enum:
- EXTERNAL_BANK_ACCOUNT
- ATO
- TYRO_TRANSACTION_ACCOUNT
- TYRO_BANK_ACCOUNT
- LOAN
description: >-
Settlement type indicating the destination account for the payment
or transfer. More values may be added in the future.
institutionName:
type: string
description: Name of the institution receiving the settlement.
bsb:
type: string
description: BSB code in the format 'XXXXXX'.
example: '123456'
accountNumber:
type: string
description: Account number of the settlement destination, partially masked.
example: '*****7890'
accountName:
type: string
description: Name associated with the settlement destination account.
settlementAmount:
type: number
description: Signed amount settled, in cents.
example: -10001
lastUpdatedAt:
type: string
format: date-time
description: >-
Indicates the time of the latest settlement status update. The
format of the date time is the notation as defined by [RFC 3339,
section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6)
example: '2023-10-01T12:00:00.00Z'
settlementStatus:
type: string
enum:
- SENT
- PENDING
- ON_HOLD
- RESUBMISSION_INITIATED
- RESUBMISSION_SENT
- RESUBMISSION_ON_HOLD
- WITHHELD_BY_ACQUIRER
- WITHHELD_BY_BANK
description: |
Status of the settlement.
* `SENT` - The settlement has been successfully sent from Tyro to the merchant’s destination financial institution. Note: The actual deposit time into the merchant’s account is determined by their bank and is not known by Tyro.
* `PENDING` - The settlement process has been initiated by Tyro, but funds have not yet left Tyro’s systems.
* `ON_HOLD` - The settlement is currently withheld. This may occur due to account suspension, suspected fraud, or participation in a net settlement arrangement. Funds are retained by Tyro until resolution.
* `RESUBMISSION_INITIATED` - The settlement got returned back by customer's bank and Tyro initiated its resubmission.
* `RESUBMISSION_SENT` - The settlement got returned back by customer's bank and resubmission was successfully sent from Tyro.
* `RESUBMISSION_ON_HOLD` - The settlement got returned back by customer's bank and resubmission is on hold and funds are withheld by Tyro.
* `WITHHELD_BY_ACQUIRER` - The settlement failed and funds are withheld by Tyro.
* `WITHHELD_BY_BANK` - The settlement failed and funds are withheld by the customer's bank.
lodgementReference:
type: string
description: >-
Lodgement reference provided with the settlement to the receiving
institution, up to 18 characters.
required:
- type
settlement:
title: Settlements
type: object
properties:
clearingPaymentId:
type: string
description: >-
ID of the clearing payment run used to bundle transactions for a
settlement.
grossAmount:
type: number
description: Signed gross amount settled, in cents.
example: 10001
settlementDetails:
type: array
description: >-
Multiple settlement entries may be returned due to settlement splits
by scheme, by location, or due to additional settlement destinations
such as loan repayments or ATO garnishees.
items:
$ref: '#/components/schemas/settlement-details'
required:
- settlementDetails
reporting-settlements-response:
title: Settlements Response
type: object
properties:
mid:
type: string
description: >-
The merchant ID associated with the Tyro account. Used to identify
the merchant whose settlement data is being retrieved.
settlementDate:
type: string
format: date
description: >-
Requested settlement date (YYYY-MM-DD). Must be within the past 3
years.
settlements:
type: array
description: >-
List of settlements for the specified merchant on the given date. If
the array is empty, it may indicate that the merchant does not
settle via BECS, or no settlement occurred on that date.
items:
$ref: '#/components/schemas/settlement'
required:
- mid
- settlementDate
- settlements
transaction:
title: Transaction
type: object
properties:
transactionId:
type: string
description: Unique identifier for the transaction.
example: 5c05f70e3f0e3bd3b5359d5cf20e5a75fb4dd525229350e15137e78f1bfa4de6
transactionLocalDateTime:
type: string
format: date-time
description: >-
The local date and time on the terminal when the transaction was
processed.
example: '2025-05-26T14:30:15'
transactionStatus:
type: string
description: >-
Status of the transaction. Possible values include `APPROVED`,
`DECLINED`, `CANCELLED`, `TIMED_OUT`, `VOIDED`, `PRE_AUTHORISED`.
example: APPROVED
transactionDescription:
type:
- string
- 'null'
description: Description of the transaction.
example: Card Payment
locationId:
type: string
description: >-
A unique identifier used to represent a specific location of a
merchant.
example: '122'
tid:
type: integer
description: A unique identifier of the terminal used to process the transaction.
example: 12345
deviceType:
type:
- string
- 'null'
description: Type of device used to process the transaction.
example: DX4000
mobilePlatformType:
type:
- string
- 'null'
description: Mobile platform type if applicable.
example: IOS
paymentType:
type: string
description: >-
Payment method type. Possible values include `GOODS_AND_SERVICES`,
`REFUND_GOODS_AND_SERVICES`, `GOODS_AND_SERVICES_WITH_CASH`,
`CASH_WITHDRAWAL`, `CREDIT_ADJUSTMENT`.
example: GOODS_AND_SERVICES
feeType:
type: string
description: >-
Fee structure applied. Possible values include
`DEBIT_EFTPOS_CASHOUT`, `DEBIT_EFTPOS_NO_CASHOUT`, `CREDIT_SWIPED`,
`CREDIT_COMMERCIAL_AND_PREMIUM`, `INTERNATIONAL`,
`MASTERCARD_INTERNATIONAL`, `UNION_PAY_INTERNATIONAL_DEBIT`,
`DEBIT_SCHEME_SWIPED`, `AMEX_JCB_FEES`, `ALIPAY`, `NO_FEES`,
`UNKNOWN`.
example: DEBIT_EFTPOS_NO_CASHOUT
fromAccountType:
type:
- string
- 'null'
description: >-
Source account type. Possible values include `DEFAULT`, `SAVINGS`,
`CHEQUE`, `CREDIT`.
example: CREDIT
isExpressPayment:
type:
- boolean
- 'null'
description: >-
Whether this was an express payment (i.e. Visa or Mastercard
purchases under $35).
example: false
card:
title: Card Details
type: object
properties:
type:
type: string
description: >-
Card type/scheme. Possible values include `VISA`, `MASTERCARD`,
`EFTPOS`, `UNION_PAY`, `AMEX`, `JCB`, `DINERS`.
example: VISA
cardLastFour:
type: string
description: Masked card number, with only the last four digits visible.
example: XXXXXXXXXXXX0009
cardEntryMode:
type: string
description: >-
How the card payment was processed. Possible values include
`CHIP`, `CONTACTLESS`, `CONTACTLESS_MAG_STRIPE`, `MAG_STRIPE`,
`CHIP_ERROR_MAG_STRIPE_USED`, `MANUAL`, `UNKNOWN`.
example: MAG_STRIPE
cardPresent:
type:
- boolean
- 'null'
description: Whether the card was physically present.
example: true
required:
- type
- cardLastFour
- cardEntryMode
- cardPresent
isEcommerceTransaction:
type: boolean
description: Whether this is an e-commerce transaction.
example: false
ecommerceOrderId:
type:
- string
- 'null'
description: E-commerce order id if applicable.
example: null
isRefund:
type: boolean
description: Whether this transaction is a refund.
example: false
refundReason:
type:
- string
- 'null'
description: Reason for refund if applicable.
example: null
isReversal:
type: boolean
description: Whether this transaction is a reversal.
example: false
reversalReason:
type:
- string
- 'null'
description: Reason for reversal if applicable.
example: null
isInternational:
type:
- boolean
- 'null'
description: Whether the transaction was processed with in a foreign currency.
example: false
dcc:
type: object
description: Details for a Dynamic Currency Conversion (DCC) transaction.
properties:
currencyCode:
type:
- string
- 'null'
description: Foreign currency code for DCC transaction.
example: USD
exchangeRate:
type:
- number
- 'null'
description: Exchange rate applied for DCC.
example: 1.45
foreignCurrencyAmount:
type:
- number
- 'null'
description: Amount in foreign currency (in cents).
example: 5862
merchantCommissionAmount:
type: number
description: Commission amount for DCC (in cents).
example: 120
required:
- currencyCode
- exchangeRate
- foreignCurrencyAmount
- merchantCommissionAmount
amountDetails:
title: Amount Details
type: object
properties:
saleAmount:
type: number
description: Sale amount (in cents).
example: 12550
refundAmount:
type: number
description: Refund amount (negative value, in cents).
example: -550
tipAmount:
type: number
description: Tip amount (in cents).
example: 0
cashOutAmount:
type: number
description: Cash out amount (in cents).
example: 0
surchargeAmount:
type: number
description: Surcharge amount (in cents).
example: 215
donationAmount:
type: number
description: Donation amount (in cents).
example: 0
required:
- saleAmount
- refundAmount
- tipAmount
- cashOutAmount
- surchargeAmount
- donationAmount
totalAmount:
type: number
description: Total transaction amount (in cents).
example: 12765
amountToPayMerchant:
type: number
description: Amount to be paid to merchant (in cents).
example: 12550
settlementAmount:
type: number
description: Net settlement amount after fees (in cents).
example: 12335
merchantAcquiringFee:
type: number
description: Acquiring fee charged to merchant (in cents).
example: 0.3839
acquirerActionCode:
type: string
description: >-
Action code from acquirer. Possible values include `APPROVED`,
`DECLINED`, `CALL_ISSUER`, `CAPTURE_CARD`.
example: APPROVED
rrn:
type:
- number
- 'null'
description: Retrieval Reference Number.
example: null
tyroReference:
type:
- number
- 'null'
description: Tyro transaction reference number. Maximum six digits.
example: null
integratedTransactionId:
type:
- string
- 'null'
description: >-
Identifier used by the POS to process an integrated transaction with
the terminal.
example: null
required:
- transactionId
- transactionLocalDateTime
- transactionStatus
- transactionDescription
- locationId
- tid
- deviceType
- mobilePlatformType
- paymentType
- feeType
- fromAccountType
- isExpressPayment
- card
- isEcommerceTransaction
- ecommerceOrderId
- isRefund
- refundReason
- isReversal
- reversalReason
- isInternational
- dcc
- amountDetails
- totalAmount
- amountToPayMerchant
- settlementAmount
- merchantAcquiringFee
- acquirerActionCode
- rrn
- tyroReference
- integratedTransactionId
reporting-transactions-response:
title: Transactions Report
type: object
properties:
terminalBusinessDay:
type: string
format: date
description: >-
The date (YYYY-MM-DD) that the terminal has processed the requested
transactions.
example: '2025-05-26'
merchantDetails:
title: Merchant Details
type: object
description: Details of the merchant for whom the transactions are reported.
properties:
mid:
type: string
description: The merchant ID associated with the Tyro account.
example: '111'
tradingName:
type: string
description: The trading name of the merchant.
example: Test Merchant
required:
- mid
- tradingName
transactions:
type: array
description: List of transactions for the specified merchant and date.
items:
$ref: '#/components/schemas/transaction'
pagination:
type: object
description: Pagination details for the transaction results.
properties:
page:
type: integer
description: The current page number.
minimum: 1
example: 1
size:
type: integer
description: The number of transactions per page.
example: 10
limit:
type: integer
description: >-
The maximum number of transactions that can be returned per
page.
example: 100
total:
type: integer
description: The total number of transactions.
example: 45
required:
- page
- size
- limit
- total
required:
- terminalBusinessDay
- merchantDetails
- transactions
- pagination