openapi: 3.1.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
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'
components:
  parameters:
    header-bearer-token:
      schema:
        type: string
        default: Bearer {$$.env.access_token}
      in: header
      name: Authorization
      required: true
    header-content-json:
      schema:
        type: string
        enum:
          - application/json
      in: header
      name: Content-Type
      required: true