Tyro Payments Reporting API

openapi: 3.2.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
tags:
- name: Reporting
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: []
      tags:
      - Reporting
  /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: []
      tags:
      - Reporting
components:
  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.\n  * `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.\n  * `PENDING` - The settlement process has been initiated by Tyro, but funds have not yet left Tyro’s systems.\n  * `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.\n  * `RESUBMISSION_INITIATED` - The settlement got returned back by customer's bank and Tyro initiated its resubmission.\n  * `RESUBMISSION_SENT` - The settlement got returned back by customer's bank and resubmission was successfully sent from Tyro.\n  * `RESUBMISSION_ON_HOLD` - The settlement got returned back by customer's bank and resubmission is on hold and funds are withheld by Tyro.\n  * `WITHHELD_BY_ACQUIRER` - The settlement failed and funds are withheld by Tyro.\n  * `WITHHELD_BY_BANK` - The settlement failed and funds are withheld by the customer's bank.\n"
        lodgementReference:
          type: string
          description: Lodgement reference provided with the settlement to the receiving institution, up to 18 characters.
      required:
      - type
    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
    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
    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
  parameters:
    header-bearer-token:
      schema:
        type: string
        default: Bearer {$$.env.access_token}
      in: header
      name: Authorization
      required: true
  securitySchemes:
    JWT:
      type: openIdConnect
      openIdConnectUrl: https://auth.connect.tyro.com/.well-known/openid-configuration