Switchfly Machine to Machine (OAuth2 & Refund) API

openapi: 3.2.0
info:
  title: Switchfly Loyalty Machine to Machine (OAuth2 & Refund) API
  description: Switchfly uses **OAuth 2** for the SSO authentication required to communicate with any 3rd party API in order to perform loyalty account actions.
  version: v3.4
tags:
- name: Machine to Machine (OAuth2 & Refund)
  description: Describes authentication required (`client_credentials` OAuth 2) and refund requests performed by Switchfly application to 3rd party service to cancel redemption components.
paths:
  /admin/token:
    post:
      tags:
      - Machine to Machine (OAuth2 & Refund)
      summary: Authentication Switchfly App against 3rd party API
      operationId: ClientCredentialAdminToken
      description: 'This endpoint will be used to perform a OAuth 2 - client credentials token

        request.


        The path in this endpoint can be the same as the `/token` path the only requirement is that a different set of

        `client_id` and `client_secret` credentials are shared by the 3rd party to Switchfly as this token request will

        be triggered to perform a **machine to machine** authentication which will then allow Switchfly to perform API

        requests to a secured `/refund` endpoint.


        The generated token will be used by the `/refund` endpoint as a Bearer token.


        User


        User


        Switchfly


        Switchfly


        3rd party

        Authorization service


        3rd party...


        3rd party

        Redemption API


        3rd party...


        Refund RQ + access token


        Refund RQ + access token


        Refund RS


        Refund RS


        User cancels booking or

        booking component


        User cancels booking or...


        1


        1


        4


        4


        5


        5


        Client credentials Grant RQ


        client_id


        secret


        Client credentials Grant RQ...


        Client credentials Acces token RS


        Client credentials Acces token RS


        2


        2


        3


        3Text is not SVG - cannot display'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/AdminClientCredentialsTokenRequest'
      responses:
        '200':
          description: Successful authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientCredentialsTokenResponse'
  /refund:
    post:
      tags:
      - Machine to Machine (OAuth2 & Refund)
      summary: Cancel booking or individual components of a booking
      description: 'This API will be used by Switchfly to perform points refund actions to a redemption booking from a loyalty customer.


        Switchfly will include the `redemptionConfirmationId` in the body of the request, this will help the 3rd party API to identify which redemption booking is being refunded, it will also include the amount of points and cash refunded (susceptible to)


        Refund could be of types `BOOKING` and `COMPONENT` which will describe if all the booking is being cancelled or if only an individual component will be cancelled.


        The refund endpoint is required to return a successful JSON response.'
      operationId: Refund
      security:
      - adminBearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Refund'
            examples:
              CancellationFullBookingRefundNoPenalty:
                $ref: '#/components/examples/CancellationFullBookingRefundNoPenalty'
              CancellationFullBookingRefundPenalty:
                $ref: '#/components/examples/CancellationFullBookingRefundPenalty'
              CancellationComponentPaidInPointsNoPenalty:
                $ref: '#/components/examples/CancellationComponentPaidInPointsNoPenalty'
              CancellationComponentPaidInPointsPenalty:
                $ref: '#/components/examples/CancellationComponentPaidInPointsPenalty'
              CancellationComponentPaidInCashNoPenalty:
                $ref: '#/components/examples/CancellationComponentPaidInCashNoPenalty'
              CancellationBookingPaidInCashNonRefundable:
                $ref: '#/components/examples/CancellationBookingPaidInCashNonRefundable'
      responses:
        '200':
          description: Successful operation (JSON valid response)
        '400':
          description: Malformed request
        '401':
          description: Not authorized to access the resource
        '403':
          description: It is forbidden to access the channel
        default:
          description: Unexpected Error
components:
  schemas:
    ClientCredentialsTokenResponse:
      type: object
      required:
      - access_token
      properties:
        access_token:
          type: string
          description: The access token issued by the authorization server.
        token_type:
          type: string
          description: Type of token issued.
        expires_in:
          type: integer
          description: The lifetime of the access token in seconds.
    AdminClientCredentialsTokenRequest:
      type: object
      required:
      - grant_type
      - client_id
      - client_secret
      - scope
      properties:
        grant_type:
          type: string
          enum:
          - client_credentials
        client_id:
          type: string
          description: The client ID associated with the client application.
        client_secret:
          type: string
          description: The client secret associated with the client application.
        scope:
          type: string
          enum:
          - refund
          description: Scope used to request token for `/refund` endpoint API requests.
    Refund:
      type: object
      format: json
      required:
      - bookingId
      - travelerProfileId
      - redemptionConfirmationId
      - pointsToRefund
      - cancellationFeesInPoints
      - cashToRefund
      - currency
      - refundType
      properties:
        bookingId:
          type: number
          description: Switchfly unique identifier
        travelerProfileId:
          type: string
          description: Unique Identifier for User Profile
        redemptionConfirmationId:
          type: string
          description: Confirmation Id/Code of the redemption to refund
        pointsToRefund:
          type: string
          description: Total points to refund after penalties
        cancellationFeesInPoints:
          type: string
          description: Cancellation penalty in points
        cashToRefund:
          type: number
          description: Cash to refund (matches customerCurrency)
        currency:
          type: string
          description: Currency in which the CC was charged for the amount (matches customerCurrency)
        refundType:
          type: string
          enum:
          - BOOKING
          - COMPONENT
          description: Supported refund types
        cancelledProduct:
          description: Only sent when refundType is COMPONENT
          required:
          - id
          - type
          - description
          properties:
            id:
              type: string
              description: Component unique identifier
            type:
              type: string
              enum:
              - ACTIVITY
              - AIR
              - CAR
              - ROOM
              - INSURANCE
              description: Supported component types
            description:
              type: string
              description: Component description, e.g, activity name, hotel name, car model, flight numbers
  examples:
    CancellationComponentPaidInPointsNoPenalty:
      value:
        bookingId: 1234567
        travelerProfileId: uniqueId1234
        redemptionConfirmationId: '123456'
        pointsToRefund: 8150
        cancellationFeesInPoints: 0
        cashToRefund: 0
        currency: USD
        refundType: COMPONENT
        cancelledProduct:
          id: 3
          type: ACTIVITY
          description: Swim with dolphins
    CancellationComponentPaidInPointsPenalty:
      value:
        bookingId: 1234567
        travelerProfileId: uniqueId1234
        redemptionConfirmationId: '123456'
        pointsToRefund: 4075
        cancellationFeesInPoints: 4075
        cashToRefund: 0
        currency: USD
        refundType: COMPONENT
        cancelledProduct:
          id: 3
          type: ACTIVITY
          description: Swim with dolphins
    CancellationComponentPaidInCashNoPenalty:
      value:
        bookingId: 1234567
        travelerProfileId: uniqueId1234
        redemptionConfirmationId: '123456'
        pointsToRefund: 0
        cancellationFeesInPoints: 0
        cashToRefund: 100
        currency: USD
        refundType: COMPONENT
        cancelledProduct:
          id: 4
          type: CAR
          description: Toyota Trueno
    CancellationBookingPaidInCashNonRefundable:
      value:
        bookingId: 1234567
        travelerProfileId: uniqueId1234
        redemptionConfirmationId: '123456'
        pointsToRefund: 0
        cancellationFeesInPoints: 0
        cashToRefund: 0
        currency: USD
        refundType: BOOKING
    CancellationFullBookingRefundPenalty:
      value:
        bookingId: 1234567
        travelerProfileId: uniqueId1234
        redemptionConfirmationId: '123456'
        pointsToRefund: 65450
        cancellationFeesInPoints: 3000
        cashToRefund: 0
        currency: USD
        refundType: BOOKING
    CancellationFullBookingRefundNoPenalty:
      value:
        bookingId: 1234567
        travelerProfileId: uniqueId1234
        redemptionConfirmationId: '123456'
        pointsToRefund: 68450
        cancellationFeesInPoints: 0
        cashToRefund: 100
        currency: USD
        refundType: BOOKING
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Uses token retrieved from OAuth 2 SSO token requests
    adminBearerAuth:
      type: http
      scheme: bearer
      description: Uses token retrieved from Machine to Machine OAuth 2 client credentials token request.