Tyro Payments Pay Requests API

openapi: 3.2.0
info:
  title: Tyro Pay Requests API
  version: '0.9'
  contact: {}
  description: 'Operations tagged Pay Requests across 2 of this provider''s published API definitions: tyro-connect-pay.yml, tyro-pos-pay-terminal.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.tyro.com/connect
  description: Production
tags:
- name: Pay Requests
paths:
  /pay/requests:
    post:
      summary: Create a Pay Request
      operationId: create-pay-request
      tags:
      - Pay Requests
      description: This endpoint is used for creating a Pay Request. Your server should create a Pay Request as soon as the total payment amount is known. Once the Pay Request is created, your frontend will use Tyro.js to collect the customer's payment details and invoke submit() to execute the payment.
      security:
      - JWT: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/new-pay-request'
            examples:
              Simple Pay Request:
                value:
                  locationId: tc-cool-3000
                  origin:
                    orderId: 0f448ac1-862a-4c7b-bdb4-a3b7cdbf444
                  provider:
                    name: TYRO
                    method: CARD
                  total:
                    amount: 10000
                    currency: AUD
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pay-request-response'
              examples:
                Simple Pay Response:
                  value:
                    id: 0f448ac1-862a-4c7b-bdb4-a3b7cdbf6149
                    locationId: tc-cool-3000
                    provider:
                      name: TYRO
                      method: CARD
                    origin:
                      orderId: 1f448ac1-862a-4c7b-bdb4-a3b7cdbf6145
                    status: AWAITING_PAYMENT_INPUT
                    supportedNetworks:
                    - visa
                    - mastercard
                    action: null
                    capture:
                      method: AUTOMATIC
                    paySecret: $2a$10$20qRi3XjN1PkTlEVDiYjHefra7c6i2i7yVNu9o5GGTO7ADsWNDuya
                    total:
                      amount: 10000
                      currency: AUD
          headers: {}
        '400':
          description: When the provided payload is not valid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The validation error message.
                  errorCode:
                    type: string
                    description: The unique error code for message.
              examples:
                Missing property:
                  value:
                    error: '"locationId" is required'
                    errorCode: VALIDATION_ERROR
        '403':
          description: When you don't have the right permissions to create a Pay Request for the provided location.
      parameters:
      - $ref: '#/components/parameters/header-bearer-token'
      - $ref: '#/components/parameters/header-content-json'
    servers:
    - url: https://api.tyro.com/connect
      description: Production
  /pay/requests/{payRequestId}:
    get:
      operationId: get-pay-request
      tags:
      - Pay Requests
      description: This endpoint is for fetching Pay Requests.
      summary: Retrieve a Pay Request
      responses:
        '200':
          description: The Pay Request response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pay-request-response'
        '404':
          description: When the provided `payRequestId` does not match a Pay Request stored in the system.
      security:
      - JWT: []
      parameters:
      - $ref: '#/components/parameters/header-bearer-token'
      - schema:
          type: string
        name: payRequestId
        in: path
        required: true
    patch:
      operationId: patch-pay-request
      tags:
      - Pay Requests
      summary: Update or execute actions on the Pay Request
      description: This endpoint is for updating a Pay Request or executing actions on the Pay Request.
      responses:
        '200':
          description: The Pay Request response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pay-request-response'
        '400':
          description: When the provided payload is not valid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The validation error message.
                  errorCode:
                    type: string
                    description: The unique error code for message.
              examples:
                Missing property:
                  value:
                    error: Requested capture amount exceeds authorised amount
                    errorCode: PAY_REQUEST_CAPTURE_AMOUNT_EXCEEDED
        '404':
          description: When the provided `payRequestId` does not match a Pay Request stored in the system.
      security:
      - JWT: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update-pay-request'
            examples:
              Perform Capture Action:
                value:
                  action: CAPTURE
              Update Authorisation:
                value:
                  action: UPDATE_AUTHORISATION
                  authorisation:
                    total:
                      amount: 5000
                      currency: AUD
              Cancel a Pay Request:
                value:
                  action: VOID
              Update Pay Total:
                value:
                  total:
                    amount: 10000
                    currency: AUD
      parameters:
      - $ref: '#/components/parameters/header-bearer-token'
      - schema:
          type: string
        name: payRequestId
        in: path
        required: true
    servers:
    - url: https://api.tyro.com/connect
      description: Production
  /pay-terminal/requests:
    post:
      summary: Create a Pay Request
      operationId: create-pay-terminal-request
      description: This endpoint is used for creating a Pay Request. Your server should create a Pay Request as soon as the total payment amount is known. Once the Pay Request is created, given the terminal is not busy, or offline, the process to pay will be initialised.
      security:
      - JWT: []
      tags:
      - Pay Requests
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/new-pay-request_2'
            examples:
              Simple Pay Request:
                value:
                  mid: '123'
                  tid: '456'
                  origin:
                    orderId: 2e6174ae-ba4f-4a02-8072-9304d862e320
                    transactionId: 2e6174ae-ba4f-4a02-8072-9304d862e320
                  total:
                    goodsAndServicesAmount: 1000
                    cashoutAmount: 500
                    refundAmount: 0
                    currency: AUD
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pay-request-response_2'
              examples:
                Simple Pay Response:
                  value:
                    id: 0f448ac1-862a-4c7b-bdb4-a3b7cdbf6149
                    mid: '123'
                    tid: '456'
                    status: AWAITING_INITIALISATION
                    origin:
                      orderId: 2e6174ae-ba4f-4a02-8072-9304d862e320
                      transactionId: 2e6174ae-ba4f-4a02-8072-9304d862e320
                    options:
                      integratedReceipt: true
                      receiptWidth: 60
                    total:
                      goodsAndServicesAmount: 1000
                      cashoutAmount: 500
                      refundAmount: 0
                      currency: AUD
          headers: {}
        '400':
          description: When the provided payload is not valid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The validation error message.
                  errorCode:
                    type: string
                    description: The unique error code for message.
              examples:
                Missing property:
                  value:
                    error: '"mid" is required'
                    errorCode: VALIDATION_ERROR
        '403':
          description: When you don't have the right permissions to create a Pay Request for the provided mid.
        '404':
          description: When the provided mid is not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The validation error message.
                  errorCode:
                    type: string
                    description: The unique error code for message.
              examples:
                Missing property:
                  value:
                    error: Merchant ID not found.
                    errorCode: MID_NOT_FOUND
        '412':
          description: When the terminal is not paired.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The validation error message.
                  errorCode:
                    type: string
                    description: The unique error code for message.
              examples:
                Missing property:
                  value:
                    error: Terminal is not paired.
                    errorCode: TERMINAL_NOT_PAIRED
      parameters:
      - $ref: '#/components/parameters/header-bearer-token'
      - $ref: '#/components/parameters/header-content-json'
    servers:
    - url: https://api.tyro.com/connect
      description: Production
  /pay-terminal/requests/{payRequestId}:
    get:
      operationId: get-pay-terminal-request
      description: This endpoint is for fetching Pay Requests.
      summary: Retrieve a Pay Request
      tags:
      - Pay Requests
      responses:
        '200':
          description: The Pay Request response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pay-request-response_2'
              examples:
                Simple Pay Response:
                  value:
                    id: a2be1eaf-b873-4aa9-9530-fc3007231572
                    mid: '123'
                    tid: '456'
                    status: SUCCESS
                    total:
                      currency: AUD
                      cashoutAmount: 1000
                      goodsAndServicesAmount: 5000
                      refundAmount: 0
                    options:
                      integratedReceipt: true
                      receiptWidth: 60
                    origin:
                      name: Example
                      orderId: Pay Terminal Example
                      transactionId: cffd6564-0023-44d8-996e-2932292277c2
                    transactionProgress:
                      id: COMPLETE
                      description: The transaction is processed
                    pendingDecision:
                      decisionId: 0f448ac1-862a-4c7b-bdb4-a3b7cdbf6149
                      question: Would you like to print a receipt?
                      options:
                      - 'YES'
                      - 'NO'
                    receipts:
                      customer: <This will be a printable receipt for the customer>
                      merchant: <This will be a printable receipt for the merchant>
                      signature: <This will be a printable receipt for the merchant if signature is required>
                    transactionOutcome:
                      transactionResult: Approved
                      approvalCode: '00'
                      transactionReference: xa29boybbo
                      authorisationNumber: '674574564'
                      cardType: visa
                      elidedPan: XXXXXXXXXXXX8635
                      retrievalReferenceNumber: '63594680046125834000'
                      surchargeAmount: 300
                      tipAmount: 500
                      totalAmount: 6800
        '404':
          description: When the provided `payRequestId` does not match a Pay Request stored in the system.
      security:
      - JWT: []
      parameters:
      - $ref: '#/components/parameters/header-bearer-token'
      - schema:
          type: string
        name: payRequestId
        in: path
        required: true
    put:
      summary: Answer a Terminal Prompt
      operationId: answer-pay-terminal-prompt
      description: An async endpoint used for attempting to answer a pending decision prompt on a terminal. The decisionId & answer is returned by the payRequest in the pendingDecision object, and is required to differentiate prompt messages. There is no result to acknowledge that this decision was received by the terminal.
      parameters:
      - $ref: '#/components/parameters/header-bearer-token'
      - $ref: '#/components/parameters/header-content-json'
      - schema:
          type: string
        name: payRequestId
        in: path
        required: true
      security:
      - JWT: []
      tags:
      - Pay Requests
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                decisionId:
                  type: string
                  description: The corresponding decisionId as provided by the pendingDecision object of the payRequest
                  example: 0f448ac1-862a-4c7b-bdb4-a3b7cdbf6149
                answer:
                  type: string
                  description: The exact case-sensitive answer as provided by the list of answers in the pendingDecision object of the payRequest
                  example: 'YES'
              required:
              - decisionId
              - answer
      responses:
        '202':
          description: Accepted
          headers: {}
        '400':
          description: When the provided payload is not valid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The validation error message.
                  errorCode:
                    type: string
                    description: The unique error code for message.
              examples:
                Missing property:
                  value:
                    error: '"decisionId" is required'
                    errorCode: VALIDATION_ERROR
        '403':
          description: When you don't have the right permissions to answer a pending decision for the provided payRequest.
        '412':
          description: When the terminal is not paired.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The validation error message.
                  errorCode:
                    type: string
                    description: The unique error code for message.
              examples:
                Missing property:
                  value:
                    error: Terminal is not paired.
                    errorCode: TERMINAL_NOT_PAIRED
    delete:
      summary: Cancel a Pay Request
      operationId: cancel-pay-terminal-request
      description: An async endpoint used for attempting to cancel a pending decision prompt on a terminal. There is no result to acknowledge that this cancellation was processed by the terminal. If the transaction is already in a fully processed state, this call will be rejected.
      parameters:
      - $ref: '#/components/parameters/header-bearer-token'
      - schema:
          type: string
        name: payRequestId
        in: path
        required: true
      security:
      - JWT: []
      tags:
      - Pay Requests
      responses:
        '202':
          description: Accepted
          headers: {}
        '403':
          description: When you don't have the right permissions to cancel a pending payRequest.
        '412':
          description: When the terminal is not paired.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The validation error message.
                  errorCode:
                    type: string
                    description: The unique error code for message.
              examples:
                Missing property:
                  value:
                    error: Terminal is not paired.
                    errorCode: TERMINAL_NOT_PAIRED
    servers:
    - url: https://api.tyro.com/connect
      description: Production
components:
  schemas:
    update-pay-request:
      title: Update Pay Request
      type: object
      oneOf:
      - title: Updating Authorisation
        required:
        - action
        - authorisation
        description: 'When the capture method is `MANUAL_ESTIMATED`, submitting this request will extend the authorisation holding period and allow you to increase the authorised amount.


          **Note:** This feature is only supported for Visa and Mastercard transactions and may not enabled by default for your account.

          '
        properties:
          action:
            type: string
            enum:
            - UPDATE_AUTHORISATION
          authorisation:
            type: object
            required:
            - total
            properties:
              total:
                allOf:
                - $ref: '#/components/schemas/money-positive-aud'
                - description: The new total amount to authorise (in smallest currency unit). It has to be greater than the original authorised amount.
      - title: Capturing Authorisation
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - CAPTURE
          capture:
            type: object
            required:
            - total
            properties:
              total:
                allOf:
                - $ref: '#/components/schemas/money-positive-aud'
                - description: The total amount to capture (in smallest currency unit). You cannot capture more than the authorised amount.
      - title: Voiding Authorisation
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - VOID
      - title: Updating Pay Request without performing an action
        properties:
          total:
            allOf:
            - $ref: '#/components/schemas/money-positive-aud'
            - description: The total amount (in smallest currency unit). The total can be updated without performing an action.
          payMethod:
            type: object
            properties:
              customerId:
                type: string
                description: The Tyro generated ID of the customer linked to this Pay Method. Pass `null` to remove a `customerId` from the pay request.
              save:
                type: boolean
                description: Indicates whether the pay method should be saved after a successful payment.
            required:
            - save
    transaction-result:
      title: Transaction Result
      type: object
      properties:
        merchant:
          type: string
          description: Merchant for this transaction
        authentication:
          type: object
          description: 3ds authentication details for this transaction
          properties:
            accessControlServerEci:
              type: string
            accessControlServerTransactionId:
              type: string
            acceptVersions:
              type: string
            amount:
              type: string
            additionalInfo:
              type: string
            authenticationToken:
              type: string
            3dsServerTransactionId:
              type: string
            channel:
              type: string
            directoryServerId:
              type: string
            directoryServerTransactionId:
              type: string
            method:
              type: string
            methodCompleted:
              type: string
            methodSupported:
              type: string
              enum:
              - SUPPORTED
              - NOT_SUPPORTED
            payerInteraction:
              type: string
            protocolVersion:
              type: string
            redirectedDomainName:
              type: string
            requestorId:
              type: string
            requestorName:
              type: string
            statusReasonCode:
              type: string
            transactionId:
              type: string
            transactionStatus:
              type: string
              enum:
              - 'YES'
              - 'NO'
              - UNAVAILABLE
              - ATTEMPTED
              - CHALLENGE
              - REJECTED
              - DECOUPLED
              - INFORMATIONAL
            time:
              type: string
            version:
              type: string
        order:
          type: object
          description: Order for this transaction
          properties:
            id:
              type: string
            status:
              type: string
            currency:
              type: string
            reference:
              type: string
            amount:
              type: number
            authorisedAmount:
              type: number
            capturedAmount:
              type: number
            refundedAmount:
              type: number
            merchantCurrency:
              type: string
            merchantAmount:
              type: number
            createdAt:
              type: string
            updatedAt:
              type: string
        card:
          type: object
          description: Card used for this transaction
          properties:
            brand:
              type: string
            scheme:
              type: string
            expiry:
              type: object
              properties:
                month:
                  type: string
                year:
                  type: string
            nameOnCard:
              type: string
            number:
              type: string
            fundingMethod:
              type: string
            firstSixDigits:
              type: string
            lastFourDigits:
              type: string
        operationResult:
          type: object
          description: The result of this operation
          properties:
            result:
              type: string
              enum:
              - FAILURE
              - PENDING
              - SUCCESS
              - UNKNOWN
            acquirerCode:
              type: string
            gatewayCode:
              type: string
            authorisationCode:
              type: string
            errorCode:
              type: string
            errorMessage:
              type: string
        transaction:
          type: object
          description: The transaction for the operation
          properties:
            id:
              type: string
            type:
              type: string
            amount:
              type: number
            currency:
              type: string
            retrievalReferenceNumber:
              type: string
            acquirer:
              type: object
              properties:
                id:
                  type: string
                merchantId:
                  type: string
                additionalResponse:
                  type: string
    new-pay-request:
      title: New Pay Request
      type: object
      properties:
        locationId:
          type: string
          description: The id of the location as specified by the Tyro Connect system
        provider:
          type: object
          description: Details about the financial institution that processed the payment.
          properties:
            name:
              type: string
              description: The name of the provider that processed the payment. More providers will be supported at a later date.
              enum:
              - TYRO
            method:
              type: string
              description: The payment method used. More methods will be supported at a later date.
              enum:
              - CARD
          required:
          - name
          - method
        origin:
          description: Contains information about the partner that created the Pay Request.
          type: object
          properties:
            orderId:
              type: string
              maxLength: 50
              description: An identifier that has been generated by the origin. This can be used for reconciliation of orders in the app partner’s system.
            orderReference:
              type: string
              description: Easily identifiable reference for the order.
            name:
              type: string
              description: Name of the app partner that created the Pay Request.
          required:
          - orderId
        payMethod:
          description: The Pay Method associated with the Pay Request
          type: object
          properties:
            id:
              type: string
              description: The id of the Pay Method to use for this Pay Request. When the provided Pay Method is valid, the Pay Request can be submitted immediately without prompting the customer for payment details.
            customerId:
              type: string
              description: The Tyro generated ID of the customer linked to this Pay Method. If no `payMethod.customerId` is provided when `payMethod.save` is true, then a new `payMethod.customerId` is generated by Tyro. Otherwise, pass the `customerId` if this is a returning customer.
            save:
              type: boolean
              description: When set to true, the pay method will be saved after a successful payment. The pay method can then be used to make future payments.
        action:
          type: string
          description: When the `payMethod.id` and `payMethod.customerId` are provided. An action can be executed immediately without prompting the customer for input.
          enum:
          - SUBMIT
        capture:
          description: Optional field that can be used to specify how the funds will be captured.
          type: object
          properties:
            method:
              type: string
              description: '- `AUTOMATIC` (default) - captures the funds upon Pay Request submission.

                - `MANUAL` - can be used to put funds on hold and only authorise the payment, with the funds captured later.

                - `MANUAL_ESTIMATED` - can be used when you want to authorise an estimated amount, with the funds captured later. With this option, you can update the authorised amount before capture or expiration.

                '
              enum:
              - AUTOMATIC
              - MANUAL
              - MANUAL_ESTIMATED
            total:
              allOf:
              - $ref: '#/components/schemas/money-positive-aud'
              - description: The total amount to capture (in smallest currency unit). You cannot capture more than the authorised amount.
          required:
          - method
        total:
          allOf:
          - $ref: '#/components/schemas/money-positive-aud'
          - description: The total amount (in smallest currency unit)
        statementDescriptor:
          type: string
          description: Statement descriptors are used to explain to a customer the charges that appear on their bank statement. There is a maximum of 21 characters and special characters such as {}<>'" are disallowed. The descriptor should be as clear and recognisable as possible. The descriptor can be dynamic and include invoice numbers or other references to help the customer recognise the charge.
        statementDescriptorLocation:
          type: string
          description: This is the city or web address where the transaction occurred. There is a maximum of 13 characters and special characters such as {}<>'" are disallowed.
      required:
      - locationId
      - total
      - provider
      - origin
    money-positive-aud:
      title: Money Positive Amount
      type: object
      properties:
        amount:
          type: integer
          description: This is the amount in smallest currency unit. e.g 12520 (in cents) is $125.20
          example: 12520
          minimum: 0
        currency:
          type: string
          default: AUD
          enum:
          - AUD
          example: AUD
          description: This is always AUD
      required:
      - amount
      - currency
    pay-request-response:
      title: Pay Request Response
      type: object
      properties:
        id:
          type: string
          description: The ID of the Pay Request generated by Tyro.
        paySecret:
          type: string
          description: The Pay Secret associated with this Pay Request. This is used by the frontend to submit the Pay Request. Pay Secret expire after 24 hours from the time the Pay Request was created. It’s recommended to avoid logging or storing the pay secret for security reasons.
        locationId:
          type: string
          description: The id of the location as specified by the Tyro Connect system
        provider:
          type: object
          description: Details about the provider that processed the payment.
          properties:
            name:
              type: string
              description: The name of the provider that processed the payment. More providers will be supported at a later date.
              enum:
              - TYRO
            method:
              type: string
              description: The payment method used
              enum:
              - CARD
        origin:
          description: Contains information about the partner that created the Pay Request.
          type: object
          properties:
            orderId:
              type: string
              maxLength: 50
              description: An identifier that has been generated by the origin. This can be used for reconciliation of orders in the app partner’s system.
            orderReference:
              type: string
              description: Easily identifiable reference for the order.
            name:
              type: string
              description: Name of the app partner that created the Pay Request.
        payMethod:
          description: The Pay Method details for the Pay Request
          type: object
          properties:
            id:
              type: string
              description: The id of the Pay Method attached to the Pay Request.
            customerId:
              type: string
              description: The Tyro generated ID of the customer linked to the Pay Method.
            save:
              type: boolean
              description: When set to true, the pay method will be saved after a successful payment.
        capture:
          type: object
          properties:
            method:
              type: string
              description: '- `AUTOMATIC` (default) - captures the funds upon Pay Request submiss

# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tyro/refs/heads/main/openapi/tyro-pay-requests-api-openapi.yml