Tyro Payments Loyalty API

openapi: 3.2.0
info:
  title: Data Loyalty API
  version: '1.0'
  description: The Loyalty Data API provides App partners with the ability to access data regarding members sales to help aggregate loyalty points. Currently the API allows apps to register their members and are notified on every transaction performed.
  contact: {}
servers:
- url: https://api.tyro.com/connect
  description: Production
tags:
- name: Loyalty
paths:
  /loyalty/activities/{loyaltyActivityId}:
    parameters:
    - name: loyaltyActivityId
      in: path
      description: ID of loyalty activity to retrieve
      required: true
      schema:
        type: string
    get:
      summary: Get loyalty activity by Id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/loyalty-activity'
              examples:
                Without sale object:
                  value:
                    id: 99fdaa02-4cb4-4948-a79e-4b69e4008feb
                    locationId: e429f245-4dcb-4961-9d27-c40538e990b2
                    memberId: foo@bar.com
                    payment:
                      origin:
                        paymentId: e429f245-4dcb-4961-9d27-c40538e990b2
                        paymentSource: EFTPOS
                      type: PURCHASE
                      zonedDateTime: '2021-10-11T11:00:01+11:00'
                      breakdown:
                        goodsAndServices:
                          amount: '299'
                          currency: AUD
                        cashout:
                          amount: '0'
                          currency: AUD
                        tip:
                          amount: '0'
                          currency: AUD
                        surcharge:
                          amount: '0'
                          currency: AUD
                      total:
                        amount: '299'
                        currency: AUD
                    sale: null
                With sale object:
                  value:
                    id: 99fdaa02-4cb4-4948-a79e-4b69e4008feb
                    locationId: e429f245-4dcb-4961-9d27-c40538e990b2
                    memberId: foo@bar.com
                    payment:
                      origin:
                        paymentId: e429f245-4dcb-4961-9d27-c40538e990b2
                        paymentSource: EFTPOS
                      type: PURCHASE
                      zonedDateTime: '2021-05-02T08:28:13+10:00'
                      breakdown:
                        goodsAndServices:
                          amount: '299'
                          currency: AUD
                        cashout:
                          amount: '0'
                          currency: AUD
                        tip:
                          amount: '0'
                          currency: AUD
                        surcharge:
                          amount: '0'
                          currency: AUD
                      total:
                        amount: '299'
                        currency: AUD
                    sale:
                      value:
                        tax:
                          amount: 0
                          currency: AUD
                        type: SALE
                        items:
                        - id: '1'
                          sku: cherry-pie
                          name: Cherry
                          total:
                            amount: 0
                            currency: AUD
                          quantity: 1
                          unitPrice:
                            amount: 0
                            currency: AUD
                          unitPriceTax:
                            amount: 0
                            currency: AUD
                        staff:
                          id: '1'
                        table:
                          seats: 1
                          number: '11'
                        bookingId: 6dca53a9-04c7-46aa-991c-cfdf51a8f652
                        total:
                          amount: -2
                          currency: AUD
                        origin:
                          saleId: abc-def-123
                        source:
                          type: MEANDU
                        status: CLOSED
                        payments:
                        - method: EFTPOS
                          goodsAndServicesAmount:
                            amount: 0
                            currency: AUD
                        subtotal:
                          amount: 0
                          currency: AUD
                        discounts:
                        - amount: 1
                          currency: AUD
                        - amount: 1
                          currency: AUD
                        locationId: pizza-shop
                        closedZonedDateTime: '2021-05-02T08:28:13+10:00'
                        openedZonedDateTime: '2022-05-02T08:28:13+10:00'
        '401':
          description: When you don't have a valid access token.
        '404':
          description: When the provided `loyaltyActivityId` does not exist.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The error message.
              examples:
                Missing property:
                  value:
                    error: 'No sale was found for id: a72ca942-1cf7-47c8-8808-dd5aa095e81a'
      description: This endpoint retrieves a loyalty activity for a registered member.
      operationId: get-loyalty-activity-by-id
      security:
      - JWT: []
      parameters:
      - $ref: '#/components/parameters/header-bearer-token'
      tags:
      - Loyalty
components:
  parameters:
    header-bearer-token:
      schema:
        type: string
        default: Bearer {$$.env.access_token}
      in: header
      name: Authorization
      required: true
  schemas:
    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
    line-item:
      type: object
      title: Line Item
      description: This object represents a line item within a sale.
      properties:
        id:
          type: string
          description: A unique id representing the item within the overall order, i.e. 2 of the same items will have unique ids.
        name:
          type: string
        category:
          type: string
        description:
          type: string
        sku:
          type: string
          description: The Id of the item that is aligned with the Id of the item in the POS.
        barcode:
          type: string
        modifiers:
          type: array
          description: 'A list of modifications to be made to the parent item.

            Each object in this array is a [`Line Item`](#/components/schemas/line-item)'
          items:
            $ref: '#/components/schemas/line-item'
        unitPrice:
          allOf:
          - $ref: '#/components/schemas/money-positive-aud'
          - description: The single unit price (in cents) including tax but excluding discounts (if any)
        unitPriceTax:
          allOf:
          - $ref: '#/components/schemas/money-positive-aud'
          - description: The single unit amount (in cents) of tax collected by the merchant
        unitCost:
          allOf:
          - $ref: '#/components/schemas/money-positive-aud'
          - description: The single unit cost (in cents) paid by the merchant
        unitCostTax:
          allOf:
          - $ref: '#/components/schemas/money-positive-aud'
          - description: The single unit amount (in cents) of tax paid by the merchant
        discounts:
          type: array
          description: A list of discounts applied to the line item (this is not a per unit discount). e.g if the line item has a quantity of 3, and each item has a 20 cent discount, you could include one discount of 60 cents in the list, or three 20 cent discounts in the list.
          items:
            $ref: '#/components/schemas/money-positive-aud-with-description'
        sale:
          title: Sale info
          description: Provides additional information about the sale. Only present when top-level sale type is COMBINATION. Allows a POS to record a sale that contains item/s that are returned or exchanged as part of the sale.
          type: object
          properties:
            type:
              type: string
              enum:
              - SALE
              - REFUND
        surcharges:
          type: array
          description: A list of surcharges applied to the line item (this is not a per unit surcharge). e.g if the line item has a quantity of 5, and each item has a $2 surcharge, you could include one surcharge of $10 in the list, or five $2 surcharges in the list.
          items:
            $ref: '#/components/schemas/money-positive-aud-with-description'
        quantity:
          type: number
          minimum: 0
          exclusiveMinimum: 0
          description: The number of units of this item in the sale. It can be fractional.
        tax:
          allOf:
          - $ref: '#/components/schemas/money-positive-aud'
          - description: The amount (in cents) of tax collected by the merchant for this line item
        total:
          allOf:
          - $ref: '#/components/schemas/money-positive-aud'
          - description: The total (in cents) of this line item after tax, discounts, surcharges, modifiers and rounding have been applied.
      required:
      - id
      - name
      - sku
      - unitPrice
      - unitPriceTax
      - quantity
      - tax
      - total
    loyalty-activity:
      title: Loyalty Activity object
      type: object
      properties:
        id:
          type: string
          description: The Id of the loyalty activitiy in the Tyro Connect system.
          example: 0f448ac1-862a-4c7b-bdb4-a3b7cdbf6149
        locationId:
          type: string
          description: The Id of the location as specified by the Tyro Connect system.
        memberId:
          type: string
          description: The identifier of the member who is associated with this activity. This value corresponds to the origin.memberId provided during member registration.
        payment:
          type: object
          properties:
            origin:
              type: object
              properties:
                paymentId:
                  type: string
                  description: Payment Identifier generated from the payment source. It refers to the `transaction.receipt` (from Tyro eCommerce APIs) or otherwise referred to as the RRN.
                paymentSource:
                  type: string
                  enum:
                  - EFTPOS
                  - ONLINE
            type:
              type: string
              enum:
              - PURCHASE
              - REFUND
              - CASHOUT
              - OPEN_PRE_AUTH
              - CLOSE_PRE_AUTH
              - VOID
            mode:
              type: string
              description: EFTPOS integration type. It will always be `NOT_APPLICABLE` for `ONLINE` payments.
              enum:
              - INTEGRATED
              - STANDALONE
              - NOT_APPLICABLE
            zonedDateTime:
              type: string
              format: date-time
            breakdown:
              type: object
              properties:
                goodsAndServices:
                  allOf:
                  - $ref: '#/components/schemas/money-positive-aud'
                  - description: This is the amount paid by the card holder for their goods and/or services. This amount does not include any tip, surcharge, or cash out.
                cashout:
                  allOf:
                  - $ref: '#/components/schemas/money-positive-aud'
                  - description: If the cardholder withdrew cash as part of the transaction this value represents how much cash was given to the cardholder.
                tip:
                  allOf:
                  - $ref: '#/components/schemas/money-positive-aud'
                  - description: If the cardholder left a tip this value represents how much the tip was.
                surcharge:
                  allOf:
                  - $ref: '#/components/schemas/money-positive-aud'
                  - description: If the cardholder was charged a surcharge this value represents how much the surcharge was.
            total:
              allOf:
              - $ref: '#/components/schemas/money-positive-aud'
              - description: The total amount that was paid by the cardholder.
        sale:
          type: object
          properties:
            locationId:
              type: string
              description: This is the Tyro Connect defined location Id. It is a globally unique identifier that is used to identify a merchants individual site
            origin:
              type: object
              description: Identifiers and reference numbers that were generated by the POS.
              required:
              - saleId
              - locationId
              properties:
                saleId:
                  type: string
                  description: The Id of the sale generated by the POS. This value should allow for partner systems to reconcile this sale with the POS.
                locationId:
                  type: string
                  description: The Id of the store according to the POS
                locationName:
                  type: string
                  description: This is the human readable name of the location.
            source:
              type: object
              description: Information about the source of the sale.
              required:
              - type
              properties:
                type:
                  type: string
                  enum:
                  - DELIVEROO
                  - DOORDASH
                  - GOOGLE
                  - HEYYOU
                  - HUNGRYHUNGRY
                  - MEANDU
                  - MENULOG
                  - MRYUM
                  - ORDERUP
                  - OTHER
                  - POS
                  - UBEREATS
                  description: An enum describing the source type of the sale.
                other:
                  type: string
                  description: The source of the sale if the source type is OTHER.
            type:
              type: string
              enum:
              - SALE
              - REFUND
              - VOID
              default: SALE
              description: An enum describing what kind of sale took place.
            status:
              type: string
              enum:
              - CLOSED
              default: CLOSED
              description: An enum describing the status of the sale. In the future the API will support more values for this field.
            openedZonedDateTime:
              type: string
              format: date-time
              example: '2018-05-02T08:28:13+10:00'
              description: The time the sale was opened on the POS. 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)
            closedZonedDateTime:
              type: string
              description: The time the sale was closed on the POS. 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: '2018-05-02T08:28:13+10:00'
              format: date-time
            customer:
              type: object
              properties:
                id:
                  type: string
                name:
                  type: string
            register:
              type: object
              description: 'Information about which register in the venue was used '
              properties:
                id:
                  type: string
                name:
                  type: string
            staff:
              type: object
              description: Details about the staff member who performed the transaction
              required:
              - id
              properties:
                id:
                  type: string
                  description: The id of the staff member in the POS system. Please **do not** put the staff members name here
            section:
              type: object
              description: The section within the venue where the sale took place.
              properties:
                id:
                  type: string
                  description: The POS system's Id of the section
                name:
                  type: string
                  description: The readable name of the section. E.g. Front bar, drive through for hospitality or for retail men's clothes, womens shoes etc.
            table:
              type: object
              description: Optional information about the table where in the venue the sale took place.
              properties:
                number:
                  type: string
                  description: The table number or table id. This field accepts alphanumeric characters e.g `MAIN-33`
                  example: MAIN-33
                seats:
                  type: integer
                  description: The number of PAX where were seated at the table
              required:
              - number
            bookingId:
              type: string
              description: The booking ID defined by Tyro Connect to identify a reservation
            items:
              type: array
              items:
                $ref: '#/components/schemas/line-item'
            discounts:
              type: array
              items:
                $ref: '#/components/schemas/money-positive-aud-with-description'
            surcharges:
              type: array
              items:
                $ref: '#/components/schemas/money-positive-aud-with-description'
            tax:
              allOf:
              - $ref: '#/components/schemas/money-positive-aud'
              - description: The total amount (in cents) of tax collected for this sale by the merchant.
            payments:
              type: array
              items:
                type: object
                properties:
                  acquirer:
                    type: object
                    description: Details about the financial instituition that processed the payment. This object is only supplied when the `method` is `EFTPOS`
                    properties:
                      name:
                        type: string
                        description: The name of the Financial Institution that processed the payment. If it was Tyro Payments who processed the transaction, this value is `TYRO`
                        pattern: ^[A-Z]+$
                        example: TYRO
                      transactionReference:
                        type: string
                        description: A reference number that can be used to look up the transaction in the acquirer's system.
                      terminalId:
                        type: string
                        description: The Financial Institution's id of the payment terminal that performed the transaction
                    required:
                    - name
                    - transactionReference
                    - terminalId
                  method:
                    type: string
                    enum:
                    - EFTPOS
                    - CASH
                    - GIFT_CARD
                    - POINTS
                  goodsAndServicesAmount:
                    allOf:
                    - $ref: '#/components/schemas/money-positive-aud'
                    - description: The amount (in cents) being paid for the goods and services
                  tipAmount:
                    allOf:
                    - $ref: '#/components/schemas/money-positive-aud'
                    - description: The tip amount added on top of the goods and services
                  cashoutAmount:
                    allOf:
                    - $ref: '#/components/schemas/money-positive-aud'
                    - description: The cashout amount requested on top of the goodsAndServicesAmount
                  surchargeAmount:
                    allOf:
                    - $ref: '#/components/schemas/money-positive-aud'
                    - description: The surcharge amount (in cents) charged by the merchant to process the payment method
                required:
                - method
                - goodsAndServicesAmount
            total:
              allOf:
              - $ref: '#/components/schemas/money-positive-aud'
              - description: 'The total (in cents) of this sale. It must calculate to: sum(items[].total) - discounts + surcharges'
            subtotal:
              allOf:
              - $ref: '#/components/schemas/money-positive-aud'
              - description: 'The subtotal (in cents) of this sale. It must calculate to: sum(items[].total)'
          required:
          - locationId
          - origin
          - source
          - type
          - openedZonedDateTime
          - closedZonedDateTime
          - staff
          - tax
          - payments
      required:
      - id
      - locationId
      - origin
      - payment
    money-positive-aud-with-description:
      title: Money Positive Amount With Description
      allOf:
      - $ref: '#/components/schemas/money-positive-aud'
      - type: object
        properties:
          description:
            type: string
            description: A description of what this amount of money represents
            example: Tuesday Happy Hour Discount
  securitySchemes:
    JWT:
      type: openIdConnect
      openIdConnectUrl: https://auth.connect.tyro.com/.well-known/openid-configuration