Tyro Payments Bookings API

openapi: 3.2.0
info:
  title: Bookings API
  version: '1.0'
  contact: {}
  description: 'The API allows the APP and POS to send and receive information about bookings. Currently the API supports creating, updating and retrieving bookings in the POS or the booking system.

    '
servers:
- url: https://api.tyro.com/connect
  description: Production
tags:
- name: Bookings
paths:
  /bookings:
    post:
      summary: Create Booking
      operationId: create-booking-request
      responses:
        '201':
          description: Created
          content:
            application/vnd.tyro.connect+json;version=1.0:
              schema:
                $ref: '#/components/schemas/booking'
              examples:
                Created Booking:
                  value:
                    id: 2688fcf2-44dd-4c72-88ac-79d0910f2983
                    locationId: merchant:abc123
                    bookingStatus: CREATED
                    origin:
                      bookingReference: some-booking-reference
                    asset:
                      type: TABLE
                      tables:
                      - number: '1'
                    numberOfPeople: 2
                    payments:
                    - amount: 4321
                      currency: AUD
                      description: Reservation payment
                    startTime: '2020-03-01T18:00:00Z'
          links:
            GetBooking:
              operationId: get-booking
              description: Retrieve the booking details
          headers: {}
        '400':
          description: When the provided payload is not valid.
          content:
            application/vnd.tyro.connect+json;version=1.0:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The validation error message.
              examples:
                Bad Status:
                  value:
                    error: '"asset.tableStatus" must be [SEATED]'
                Missing property:
                  value:
                    error: '"origin.bookingReference" is required'
        '403':
          description: When you don't have the right permissions to seat a booking for the provided location.
      description: 'This endpoint is used to create a booking within Tyro Connect. This call will create a booking in the POS system.


        The id that is returned as a part of the response should be used to identify the booking for subsequent events or retrieving the details via the [`GET`](#operation/get-booking) endpoint.'
      security:
      - JWT: []
      requestBody:
        content:
          application/vnd.tyro.connect+json;version=1.0:
            schema:
              $ref: '#/components/schemas/new-booking-request'
            examples:
              New Booking:
                value:
                  locationId: merchant:abc123
                  origin:
                    bookingReference: some-booking-reference
                  asset:
                    type: TABLE
                    tables:
                    - number: '1'
                  numberOfPeople: 2
                  startTime: '2020-03-01T18:00:00Z'
                  bookingStatus: CREATED
        description: ''
      parameters:
      - $ref: '#/components/parameters/header-bearer-token'
      - schema:
          $ref: '#/components/schemas/acceptHeaderBooking1_0'
        in: header
        name: Accept
        required: true
      - $ref: '#/components/parameters/header-content-json'
      tags:
      - Bookings
  /bookings/{bookingId}:
    get:
      responses:
        '200':
          description: The booking response
          content:
            application/vnd.tyro.connect+json;version=1.0:
              schema:
                $ref: '#/components/schemas/booking'
              examples:
                Simple Booking:
                  value:
                    id: 2688fcf2-44dd-4c72-88ac-79d0910f2983
                    locationId: merchant:abc123
                    bookingStatus: CREATED
                    origin:
                      bookingReference: some-booking-reference
                    asset:
                      type: TABLE
                      tables:
                      - number: '1'
                    numberOfPeople: 2
                    startTime: '2020-03-01T18:00:00Z'
        '403':
          description: When you don't have the right permissions to create a booking for the provided location.
        '404':
          description: When the provided `bookingId` does not match a booking stored in the system.
          content:
            application/vnd.tyro.connect+json;version=1.0:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The validation error message.
              examples:
                Bad Request:
                  value:
                    error: No booking found for 2688fcf2-44dd-4c72-88ac-79d0910f2983
      description: This endpoint is for fetching the details of a booking.
      parameters:
      - in: path
        description: Id of the booking in Tyro Connect that should be retrieved
        name: bookingId
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/header-bearer-token'
      - schema:
          $ref: '#/components/schemas/acceptHeaderBooking1_0'
        in: header
        name: Accept
        required: true
      operationId: get-booking
      summary: Get Booking
      security:
      - JWT: []
      tags:
      - Bookings
    patch:
      responses:
        '204':
          description: No body content
        '400':
          description: When the provided request is not valid.
          content:
            application/vnd.tyro.connect+json;version=1.0:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The validation error message.
              examples:
                Bad Request:
                  value:
                    error: '"asset.tableStatus" must be one of [SEATED, DINING, FINALISED, CLOSING]'
        '403':
          description: When you don't have the right permissions to update the booking.
        '404':
          description: When the provided `bookingId` does not match a booking stored in the system.
          content:
            application/vnd.tyro.connect+json;version=1.0:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The validation error message.
              examples:
                Bad Request:
                  value:
                    error: No booking found for 2688fcf2-44dd-4c72-88ac-79d0910f2983
      requestBody:
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/update-booking-request'
            examples:
              Customer cancelled booking:
                value:
                  bookingStatus: CANCELLED_BY_CUSTOMER
                  reason: Illness
              Update Booking details:
                value:
                  numberOfPeople: 3
        description: ''
      description: This endpoint is for updating a booking.
      parameters:
      - in: path
        description: Id of the booking in Tyro Connect that should be updated
        name: bookingId
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/header-bearer-token'
      - schema:
          $ref: '#/components/schemas/acceptHeaderBooking1_0'
        in: header
        name: Accept
        required: true
      - $ref: '#/components/parameters/header-content-json'
      operationId: patch-booking
      summary: Update Booking
      security:
      - JWT: []
      tags:
      - Bookings
components:
  schemas:
    section:
      type: object
      description: The section within the venue
      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
    room:
      type: object
      properties:
        number:
          type: string
          description: The room number or room id. This field accepts alphanumeric characters e.g `MAIN-33`
          example: MAIN-33
      required:
      - number
    new-booking-request:
      title: New booking request
      type: object
      description: The message to be sent to Tyro Connect in order to mark the booking as seated.
      properties:
        locationId:
          type: string
          description: The id of the location as specified by the Tyro Connect system.
        origin:
          type: object
          description: Information relevant to the booking partner that this booking was created with
          properties:
            bookingReference:
              $ref: '#/components/schemas/bookingReference'
          required:
          - bookingReference
        bookingStatus:
          $ref: '#/components/schemas/bookingStatus'
        numberOfPeople:
          $ref: '#/components/schemas/numberOfPeople'
        payments:
          $ref: '#/components/schemas/payments'
        startTime:
          type: string
          description: The date and time the booking starts at the venue. 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-02T17:30:00.000Z'
          format: date-time
        endTime:
          type: string
          description: The date and time the booking ends at the venue. 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-02T18:30:00.000Z'
          format: date-time
        customer:
          $ref: '#/components/schemas/customer'
        notes:
          type: string
          minLength: 1
          maxLength: 500
          description: 'Notes specific to the booking. Example: ''Window seat please'''
        asset:
          description: Contains asset information of the booking
          oneOf:
          - $ref: '#/components/schemas/roomAsset'
          - $ref: '#/components/schemas/tableAsset'
      required:
      - locationId
      - numberOfPeople
      - startTime
      - asset
    table:
      type: object
      properties:
        number:
          type: string
          minLength: 1
          description: The table number or table id. This field accepts alphanumeric characters e.g `MAIN-33`
          example: MAIN-33
    payment:
      title: Payment
      type: object
      properties:
        amount:
          type: integer
          description: This is the amount in cents. e.g 12520 is $125.20
          minimum: 0
        currency:
          type: string
          default: AUD
          enum:
          - AUD
          example: AUD
          description: This is always AUD
    tableAsset:
      type: object
      properties:
        type:
          type: string
          enum:
          - TABLE
        tableStatus:
          $ref: '#/components/schemas/tableStatus'
        arrivalStatus:
          $ref: '#/components/schemas/arrivalStatus'
        tables:
          type: array
          minItems: 1
          description: The tables used for the booking
          items:
            $ref: '#/components/schemas/table'
        section:
          $ref: '#/components/schemas/section'
        discounts:
          type: array
          minItems: 1
          items:
            type: string
        preOrders:
          type: array
          minItems: 1
          items:
            type: string
      required:
      - type
    tableStatus:
      type: string
      description: 'The current table status of the booking

        The supported statuses are:

        * `SEATED` - indicates that the customer connected to the booking has been seated.

        * `DINING` - indicate that the customer connected to the booking has started dining.

        * `CLOSING` - indicates that the customer connected to the booking is close to finishing their meal (e.g. when the bill has been printed).

        * `FINALISED` - indicates that the booking has been finalised (e.g. when the bill has been finalised).'
      enum:
      - SEATED
      - DINING
      - CLOSING
      - FINALISED
    arrivalStatus:
      type: string
      description: The customer's arrival status in relation to the booking
      enum:
      - ON_TIME
      - EARLY
      - RUNNING_LATE
      - NO_SHOW
    acceptHeaderBooking1_0:
      type: string
      enum:
      - application/vnd.tyro.connect+json;version=1.0
      - application/vnd.tyro.connect+json;version=0.1
      default: application/vnd.tyro.connect+json;version=0.1
      description: Specifies which version of the API to use. If no value is provided then 0.1 version will be used
    booking:
      title: Booking
      type: object
      properties:
        id:
          type: string
          description: The id of the booking 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
        origin:
          $ref: '#/components/schemas/origin'
        asset:
          oneOf:
          - $ref: '#/components/schemas/tableAsset'
          - $ref: '#/components/schemas/roomAsset'
        bookingStatus:
          $ref: '#/components/schemas/bookingStatus'
        numberOfPeople:
          $ref: '#/components/schemas/numberOfPeople'
        payments:
          $ref: '#/components/schemas/payments'
        startTime:
          type: string
          description: The date and time the booking starts at the venue. 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-02T17:30:00.000Z'
          format: date-time
        endTime:
          type: string
          description: The date and time the booking ends at the venue. 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-02T18:30:00.000Z'
          format: date-time
        customer:
          $ref: '#/components/schemas/customer'
        notes:
          type: string
          minLength: 1
          maxLength: 500
          description: 'Notes specific to the booking. Example: ''Window seat please'''
        reason:
          $ref: '#/components/schemas/reason'
      required:
      - id
      - locationId
      - numberOfPeople
      - asset
    bookingReference:
      type: string
      description: Reference for the booking. It is used to facilitate identification of the booking in the app and pos systems and must be unique per location and booking partner.
    reason:
      type: string
      maxLength: 50
      description: The reason the booking was rejected or cancelled. Provided only when bookingStatus is `REJECTED`, `CANCELLED_BY_MERCHANT` or `CANCELLED_BY_CUSTOMER`
    bookingStatus:
      type: string
      description: The current status of the booking
      enum:
      - CREATED
      - ACCEPTED
      - CANCELLED_BY_CUSTOMER
      - CANCELLED_BY_MERCHANT
      - REJECTED
      default: CREATED
    address:
      title: address
      type: object
      description: The customer address
      properties:
        line1:
          type: string
        line2:
          type: string
        suburb:
          type: string
        state:
          type: string
        postcode:
          type: string
        country:
          type: string
    assetUpdate:
      type: object
      properties:
        tableStatus:
          $ref: '#/components/schemas/tableStatus'
        arrivalStatus:
          $ref: '#/components/schemas/arrivalStatus'
        tables:
          type: array
          minItems: 1
          description: The tables used for the booking
          items:
            $ref: '#/components/schemas/table'
        section:
          $ref: '#/components/schemas/section'
        rooms:
          type: array
          minItems: 1
          description: The rooms in the booking
          items:
            $ref: '#/components/schemas/room'
        discounts:
          type: array
          minItems: 1
          items:
            type: string
        preOrders:
          type: array
          minItems: 1
          items:
            type: string
    payments:
      type: array
      description: A list of payments applied to the booking.
      items:
        $ref: '#/components/schemas/payment-with-description'
    customer:
      type: object
      description: The customer making the booking
      properties:
        id:
          type: string
          minLength: 1
        name:
          type: string
          minLength: 1
          description: Customer's name
        notes:
          type: string
          minLength: 1
          maxLength: 500
          description: Notes specific to the customer. For example, 'Loves red wine'.
        email:
          type: string
          minLength: 1
          description: Customer's email address
        address:
          allOf:
          - $ref: '#/components/schemas/address'
          - minLength: 1
        phoneNumber:
          type: string
          minLength: 1
          description: Customer's phone number
        birthday:
          type: string
          minLength: 1
          description: Customer's birthday
    time:
      type: string
      description: 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-02T17:30:00.000Z'
      format: date-time
    payment-with-description:
      title: Payment With Description
      allOf:
      - $ref: '#/components/schemas/payment'
      - properties:
          description:
            type: string
            description: A description of what this payment amount represents
            example: Deposit for booking
    origin:
      type: object
      description: Information relevant to the booking partner that this booking was created with
      properties:
        name:
          type: string
          description: Name of the booking app
        bookingReference:
          $ref: '#/components/schemas/bookingReference'
      required:
      - bookingReference
    update-booking-request:
      title: Update booking request
      type: object
      description: The message to be sent to Tyro Connect in order to update the booking
      properties:
        asset:
          $ref: '#/components/schemas/assetUpdate'
        bookingStatus:
          $ref: '#/components/schemas/bookingStatus'
        numberOfPeople:
          $ref: '#/components/schemas/numberOfPeople'
        payments:
          $ref: '#/components/schemas/payments'
        reason:
          $ref: '#/components/schemas/reason'
        customer:
          $ref: '#/components/schemas/customer'
        notes:
          type: string
          minLength: 1
          maxLength: 500
          description: 'Notes specific to the booking. Example: ''Window seat please'''
        startTime:
          $ref: '#/components/schemas/time'
        endTime:
          $ref: '#/components/schemas/time'
        origin:
          $ref: '#/components/schemas/origin'
    roomAsset:
      type: object
      description: The section within the venue
      properties:
        type:
          type: string
          enum:
          - ROOM
        rooms:
          type: array
          minItems: 1
          description: The rooms used for the booking
          items:
            $ref: '#/components/schemas/room'
      required:
      - type
      - rooms
    numberOfPeople:
      type: number
      minimum: 1
      description: The number of expected guests
  parameters:
    header-content-json:
      schema:
        type: string
        enum:
        - application/json
      in: header
      name: Content-Type
      required: true
    header-bearer-token:
      schema:
        type: string
        default: Bearer {$$.env.access_token}
      in: header
      name: Authorization
      required: true
  securitySchemes:
    JWT:
      type: openIdConnect
      openIdConnectUrl: https://auth.connect.tyro.com/.well-known/openid-configuration