Tyro Payments Refunds API

openapi: 3.2.0
info:
  title: Refunds API
  version: '1.0'
  contact: {}
  description: 'The API allows the APP to create a refund for an existing approved Tyro transaction without the need for the card to be present.

    '
servers:
- url: https://api.tyro.com/connect
  description: Production
tags:
- name: Refunds
paths:
  /refunds/search-and-refund:
    post:
      summary: Create a Refund
      description: This endpoint creates a refund for an existing transaction. Refunds are processed as referenced refunds, meaning they require a reference to the original transaction.
      operationId: search-and-refund
      security:
      - JWT: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                mid:
                  type: string
                  description: The merchant ID associated with the Tyro account.
                  example: '98765'
                transactionReference:
                  type: string
                  description: Identifier of the original transaction, as generated by the POS system or online system.
                originChannel:
                  type: string
                  description: The sales channel where the original transaction was processed.
                  enum:
                  - INSTORE
                  - PAYMENT_LINK
                  - ONLINE_CHECKOUT
                transactionDateTime:
                  type: string
                  format: date-time
                  description: The timestamp of when the original transaction was processed. Must be after midnight of 28th of March 2025, Sydney time (2025-03-28T00:00:00.000+11:00). 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: '2025-10-01T12:00:00.000Z'
                rrn:
                  type: string
                  description: Retrieval Reference Number (RRN) of the original transaction to be refunded.
                  example: 393939393939
                refundAmount:
                  type: number
                  description: Amount to refund to the customer, in cents (AUD).
                  example: 765
                refundReason:
                  type: string
                  description: Reason for issuing the refund, stored for audit purposes.
                  example: Customer changed their mind
                partnerReference:
                  type: string
                  description: A reference provided by the partner to help reconcile this refund with records in their own systems.
                  example: '122121'
              required:
              - mid
              - transactionReference
              - originChannel
              - transactionDateTime
              - refundAmount
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  refundTransactionReference:
                    type: string
                    description: Unique identifier for the refund transaction, generated by Tyro.
                  refundTransactionRrn:
                    type: string
                    description: Retrieval Reference Number (RRN) associated with the refund transaction.
                  refundAmount:
                    type: number
                    description: Amount refunded to the customer, in cents (AUD).
                    example: 765
                  amountAvailableForRefund:
                    type: number
                    description: Remaining amount (in cents, AUD) that can still be refunded against the original transaction.
                    example: 1000
                required:
                - refundTransactionReference
                - refundAmount
                - amountAvailableForRefund
              examples:
                Created Refund:
                  value:
                    refundTransactionReference: 8cda1097-0095-4000-a90f-c7375eefad3a
                    refundTransactionRrn: '990021002206'
                    refundAmount: 765
                    amountAvailableForRefund: 1000
        '400':
          description: When the provided payload is not valid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The validation error category.
                  errorCode:
                    type: string
                    description: The validation error code.
                  data:
                    type: array
                    description: A list of validation errors.
                    items:
                      type: string
              examples:
                Missing property:
                  value:
                    error: Bad request
                    errorCode: INVALID_INPUT
                    data:
                    - Invalid ABN
        '403':
          description: When you don't have the right permissions to create a refund.
        '404':
          description: When the transaction was not found using the fields provided.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The validation error message.
        '422':
          description: The request was well-formed but business validation failed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  errorCode:
                    type: string
                    description: The error code of the business validation failure. Possible values include `TRANSACTION_ALREADY_REFUNDED`, `REFUND_AMOUNT_EXCEEDS_TRANSACTION_AMOUNT`, `REFUND_REJECTED`.
                  message:
                    type: string
          headers: {}
      parameters:
      - $ref: '#/components/parameters/header-bearer-token'
      - $ref: '#/components/parameters/header-content-json'
      tags:
      - Refunds
components:
  parameters:
    header-content-json:
      schema:
        type: string
        enum:
        - application/json
      in: header
      name: Content-Type
      required: true
    header-bearer-token:
      schema:
        type: string
        default: Bearer {$$.env.access_token}
      in: header
      name: Authorization
      required: true