Tyro Connect Loyalty Data API

openapi: 3.1.0
info:
  title: Loyalty Data 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: Registered Card
  - name: Member
  - name: Onboarding
paths:
  /loyalty/members:
    post:
      summary: Register member for loyalty
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/register-member-request'
            examples:
              Register Member with paymentId:
                value:
                  origin:
                    memberId: member-1
                  paymentId: 6940871887d8
                  locationId: cafe-on-main-steet
              Register Member with memberReference:
                value:
                  origin:
                    memberId: member-1
                  memberReference: 8f5e6eac-4adb-4b4c-93c0-eb72fad3be35
                  locationId: cafe-on-main-steet
        description: ''
      responses:
        '202':
          description: >
            The request has been accepted. The member will be registered when a
            matching payment is found.


            Clients must not rely on the response body of this endpoint;
            although a JSON payload may currently be returned, it is deprecated
            and will be removed in a future version.
        '400':
          description: When the provided payload is not valid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The validation error message.
              examples:
                Missing property:
                  value:
                    error: '"paymentId" is required'
        '401':
          description: When you don't have a valid access token.
        '403':
          description: When you don't have the right permissions for a location.
      description: >-
        This endpoint registers a member for a participating location with the
        loyalty API. This notifies you of all future payments performed by the
        members at locations you have access to. The payment should have taken
        place within a 60 minute window of the registration.
      operationId: get-payment-by-id
      security:
        - JWT: []
      tags:
        - Member
      parameters:
        - $ref: '#/components/parameters/header-bearer-token'
    delete:
      summary: Deregister a member for loyalty.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/deregister-member-request'
      responses:
        '204':
          description: No body content. Member has been successfully deregistered.
        '400':
          description: When any mandatory request parameters are missing.
        '401':
          description: When no valid access token is provided.
        '403':
          description: >-
            When a valid token is provided but it has no permissions to execute
            the request.
        '404':
          description: When a member with the provided member id could not be found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The error message.
              examples:
                Unknown memberId:
                  value:
                    error: 'Failed to find member matching memberId: some-member-id'
      description: >-
        This endpoint deregisters a member from all participating locations with
        the loyalty API. You will no longer receive notifications about the
        payments performed by the members at locations you have access to.
      operationId: deregister-member
      security:
        - JWT: []
      tags:
        - Member
      parameters:
        - $ref: '#/components/parameters/header-bearer-token'
  /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'
  /loyalty/registered-cards/{registeredCardId}:
    parameters:
      - name: registeredCardId
        in: path
        description: Id of the registered card
        required: true
        schema:
          type: string
    get:
      summary: Get registered card by Id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/loyalty-card'
              examples:
                New member card:
                  value:
                    id: >-
                      fe6eacb4c5f5afcf650bff0ea56fdc36-6c8a6220e6f73dde3d161ce605ec68fc7a98b93c9fb708e2674b756df6fd5826c7b55516
                    paymentId: e429f245-4dcb-4961-9d27-c40538e990b2
                    paymentSource: EFTPOS
                    origin:
                      memberId: foo@bar.com
                    preAccumulatedReward: 5000
        '401':
          description: When you don't have a valid access token.
        '404':
          description: When the provided `registeredCardId` does not exist.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The error message.
              examples:
                Missing property:
                  value:
                    error: >-
                      No card was found for id:
                      a72ca942-1cf7-47c8-8808-dd5aa095e81a
      description: This endpoint retrieves a registered card for a registered member.
      operationId: get-loyalty-card-by-id
      security:
        - JWT: []
      tags:
        - Registered Card
      parameters:
        - $ref: '#/components/parameters/header-bearer-token'
    delete:
      summary: Delete registered card by Id
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/deregister-member-card-request'
            examples:
              Register Member:
                value:
                  origin:
                    memberId: member-1
      responses:
        '200':
          description: No body content
          content: {}
        '401':
          description: When you don't have a valid access token.
        '404':
          description: When the provided `Id` does not exist.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The error message.
              examples:
                Missing property:
                  value:
                    error: >-
                      No card was found for id:
                      a72ca942-1cf7-47c8-8808-dd5aa095e81a
      description: This endpoint removes a registered card from a registered member.
      operationId: deregister-member-card
      security:
        - JWT: []
      tags:
        - Registered Card
      parameters:
        - $ref: '#/components/parameters/header-bearer-token'
  /locations/merchant-onboarding/loyalty/{onboardingReference}:
    parameters:
      - name: onboardingReference
        in: path
        description: The unique reference identifier for the merchant onboarding request.
        required: true
        schema:
          type: string
    get:
      summary: Get merchant onboarding request by reference
      description: >-
        This endpoint retrieves the details of a merchant onboarding request for
        a loyalty partner to review, including the location details, business
        details, and the current status of each integration.
      operationId: get-merchant-onboarding-request-by-reference
      security:
        - JWT: []
      tags:
        - Onboarding
      parameters:
        - $ref: '#/components/parameters/header-bearer-token'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/merchant-onboarding-request-response'
              examples:
                In progress onboarding:
                  value:
                    onboardingId: abc-123-ref
                    tcLocationId: tc-cafe-main-2000
                    status: IN_PROGRESS
                    locationDetails:
                      name: Cafe on Main Street
                      address: 1 Main Street
                      postcode: '2000'
                      countryIsoCode: AUS
                      timezone: Australia/Sydney
                      phoneNumber: '+61212345678'
                    businessDetails:
                      abn: '12345678901'
                      entityName: Cafe Holdings Pty Ltd
                      address: 1 Main Street
                      postcode: '2000'
                      countryIsoCode: AUS
                    integrations: []
                Completed onboarding with loyalty success:
                  value:
                    onboardingId: abc-123-ref
                    tcLocationId: tc-cafe-main-2000
                    status: COMPLETED
                    locationDetails:
                      name: Cafe on Main Street
                      address: 1 Main Street
                      postcode: '2000'
                      countryIsoCode: AUS
                      timezone: Australia/Sydney
                      phoneNumber: '+61212345678'
                    businessDetails:
                      abn: '12345678901'
                      entityName: Cafe Holdings Pty Ltd
                      address: 1 Main Street
                      postcode: '2000'
                      countryIsoCode: AUS
                    integrations:
                      - name: loyalty
                        status: SUCCESS
        '401':
          description: When you don't have a valid access token.
        '403':
          description: When you don't have the right permissions.
        '404':
          description: >-
            When the provided `onboardingReference` does not exist or does not
            belong to your partner.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The error message.
              examples:
                Not found:
                  value:
                    error: >-
                      MerchantOnboardingRequest with onboardingReference
                      abc-123-ref not found
    post:
      summary: Submit a decision for a merchant onboarding request
      description: >-
        This endpoint allows a loyalty partner to approve or reject a merchant
        onboarding request. When approving, a `loyaltyProgramId` must be
        provided. When rejecting, an optional `reason` may be provided.
      operationId: submit-merchant-onboarding-decision
      security:
        - JWT: []
      tags:
        - Onboarding
      parameters:
        - $ref: '#/components/parameters/header-bearer-token'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/merchant-onboarding-decision-request'
            examples:
              Approve onboarding:
                value:
                  action: APPROVE
                  loyaltyProgramId: my-loyalty-program-id
              Reject onboarding:
                value:
                  action: REJECT
                  reason: Merchant does not meet eligibility criteria.
      responses:
        '200':
          description: The decision has been successfully processed.
        '400':
          description: When the provided payload is not valid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The validation error message.
              examples:
                Missing loyaltyProgramId on approve:
                  value:
                    error: loyaltyProgramId is required when action is APPROVE
        '401':
          description: When you don't have a valid access token.
        '403':
          description: When you don't have the right permissions.
        '404':
          description: >-
            When the provided `onboardingReference` does not exist or does not
            belong to your partner.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The error message.
              examples:
                Not found:
                  value:
                    error: >-
                      MerchantOnboardingRequest with onboardingReference
                      abc-123-ref not found
        '409':
          description: >-
            When a decision has already been submitted for this onboarding
            request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The error message.
              examples:
                Already decided:
                  value:
                    error: >-
                      MerchantOnboardingRequest with onboardingReference
                      abc-123-ref has already received a partner decision
        '422':
          description: When the provided `loyaltyProgramId` is not recognised.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The error message.
              examples:
                Unknown loyaltyProgramId:
                  value:
                    error: loyaltyProgramId 'my-unknown-program' was not found
  /payments/test:
    post:
      operationId: create-test-payment
      summary: Create a test payment
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create-test-payment'
            examples:
              Create a test payment for a member:
                value:
                  locationId: tc-testlocation-2000
                  memberId: some-member-id
                  paymentType: PURCHASE
                  paymentSource: EFTPOS
                  goodsAndServicesAmount: 100
              Create a test payment for member with a new card:
                value:
                  locationId: tc-testlocation-2000
                  memberId: some-member-id
                  paymentType: PURCHASE
                  paymentSource: EFTPOS
                  goodsAndServicesAmount: 100
                  useNewCard: true
              Create a test payment for a non-member:
                value:
                  locationId: tc-testlocation-2000
                  memberId: null
                  paymentType: PURCHASE
                  paymentSource: EFTPOS
                  goodsAndServicesAmount: 200
              Create a test payment for a returning non-member:
                value:
                  locationId: tc-testlocation-2000
                  memberReference: ab6775c4-b446-4cd7-b2b6-d4dae6e9563b
                  paymentType: PURCHASE
                  paymentSource: EFTPOS
                  goodsAndServicesAmount: 300
        description: ''
      responses:
        '200':
          description: Created
          content:
            application/json:
              schema:
                oneOf:
                  - title: Registered Member Payment
                    type: object
                    properties:
                      memberId:
                        type: string
                        description: >-
                          The memberId of the created test payment. This is the
                          same `memberId` value that is passed in.
                        example: some-member-id
                    required:
                      - memberId
                  - title: Non-Member Payment
                    type: object
                    properties:
                      memberReference:
                        type: string
                        description: >-
                          The memberReference of the created test payment. This
                          value can be used to identify returning non-member
                          customers in future test payments.
                        example: ab6775c4-b446-4cd7-b2b6-d4dae6e9563b
                    required:
                      - memberReference
        '404':
          description: When you provide a value that we can't reconcile
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The error message.
              examples:
                Unknown memberId:
                  value:
                    error: 'Failed to find member matching memberId: some-member-id'
                Unknown locationId:
                  value:
                    error: >-
                      Failed to retrieve caid for the provided locationId:
                      tc-somelocation-2000
      description: >-
        This endpoint is for creating fake payments that can be used to test
        your integration with our system. After registering a member, payments
        can be generated for that member by providing the memberId that you
        specified during registration. If `memberId` is null the payment will
        utilise a random card number not associated with any member and the
        response will include a `memberReference` value that can be used to
        identify this non-member customer in future test payments.
      security:
        - JWT: []
      parameters:
        - $ref: '#/components/parameters/header-bearer-token'
components:
  securitySchemes:
    JWT:
      type: openIdConnect
      openIdConnectUrl: https://auth.connect.tyro.com/.well-known/openid-configuration
  parameters:
    header-bearer-token:
      schema:
        type: string
        default: Bearer {$$.env.access_token}
      in: header
      name: Authorization
      required: true
  schemas:
    register-member-request:
      properties:
        origin:
          type: object
          properties:
            memberId:
              type: string
              description: Member's Identifier on the app.
          required:
            - memberId
        locationId:
          type: string
          description: Tyro Connect's identifier for the location.
      anyOf:
        - title: Using paymentId
          properties:
            paymentId:
              type: string
              description: >-
                Payment Identifier generated from the payment source. Typically
                this is listed as the
                `payRequest.transaction.retrievalReferenceNumber` or as
                `transaction.receipt` depending on your ecommerce integration
                type.
          required:
            - paymentId
        - title: Using memberReference
          properties:
            memberReference:
              type: string
              description: >-
                The reference provided by the terminal via the QR code sign-up
                flow. By passing this value back to us here it allows us to more
                accurately identify the payment instrument(s) used by the
                customer.
          required:
            - memberReference
      required:
        - origin
        - locationId
    deregister-member-request:
      type: object
      title: Request body to deregister a member
      required:
        - origin
      properties:
        origin:
          type: object
          required:
            - memberId
          properties:
            memberId:
              type: string
              description: Member's Identifier on the app.
    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
    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
    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
    

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