openapi: 3.0.3
info:
  title: POS service API
  description: >-
    This is an API reference for the Point of Sale service, which allows you to
    manage point of sale devices, including their settings, activation, and
    configuration.
  version: 1.0.0
servers:
  - url: https://api-services.pxp.io/api/v1
    description: Production environment
  - url: https://api-services.test.pxp.io/api/v1
    description: Sandbox environment
paths:
  /point-of-sales/{site}:
    post:
      tags:
        - Manage POS devices
      summary: Add a POS device
      description: >-
        This endpoint is used to initiate a new point of sale device for a
        specific site. It creates the device with the provided configuration
        settings.
      operationId: add-pos-device
      parameters:
        - name: site
          in: path
          required: true
          description: The ID of the site where the point of sale will be deployed.
          example: SITE-1
          schema:
            type: string
      requestBody:
        description: Configuration details for the new point of sale device.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePointOfSaleRequest'
      responses:
        '200':
          description: Successfully initiated the point of sale device.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePointOfSaleResponse'
  /point-of-sales/{site}/{merchantPointOfSaleId}:
    get:
      tags:
        - Manage POS devices
      summary: Retrieve a POS device
      description: >-
        This endpoint retrieves the details of a specific point of sale device
        by its merchant ID.
      operationId: retrieve-pos-device
      parameters:
        - name: site
          in: path
          required: true
          example: SITE-1
          description: The ID of the site where the point of sale is located.
          schema:
            type: string
        - name: merchantPointOfSaleId
          in: path
          required: true
          example: POS-12345
          description: The unique merchant identifier for the point of sale device.
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved the point of sale device details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPointOfSaleResponse'
    delete:
      tags:
        - Manage POS devices
      summary: Delete a POS device
      description: This endpoint deletes a specific point of sale device.
      operationId: delete-pos-device
      parameters:
        - name: site
          in: path
          required: true
          example: SITE-1
          description: The ID of the site where the point of sale is located.
          schema:
            type: string
        - name: merchantPointOfSaleId
          in: path
          required: true
          example: POS-12345
          description: The unique merchant identifier for the point of sale device.
          schema:
            type: string
      responses:
        '200':
          description: Successfully deleted the point of sale device.
    put:
      tags:
        - Manage POS devices
      summary: Update a POS device
      description: This endpoint updates the details of a specific point of sale device.
      operationId: update-pos-device
      parameters:
        - name: site
          in: path
          example: SITE-1
          required: true
          description: The ID of the site where the point of sale is located.
          schema:
            type: string
        - name: merchantPointOfSaleId
          in: path
          required: true
          example: POS-12345
          description: The unique merchant identifier for the point of sale device.
          schema:
            type: string
      requestBody:
        description: Updated configuration details for the point of sale device.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePointOfSaleRequest'
      responses:
        '200':
          description: Successfully updated the point of sale device.
  /point-of-sales/{serialNumber}/activate:
    put:
      tags:
        - Manage POS devices
      summary: Activate a POS device
      description: This endpoint activates a point of sale device using its serial number.
      operationId: activate-pos-device
      parameters:
        - name: serialNumber
          in: path
          required: true
          example: SN1234567890
          description: The serial number of the point of sale device to activate.
          schema:
            type: string
      responses:
        '200':
          description: Successfully activated the point of sale device.
  /point-of-sales/{pointOfSaleId}/authentication-settings:
    post:
      tags:
        - Authentication settings
      summary: Create authentication settings
      description: >-
        This endpoint creates authentication settings for a specific point of
        sale device.
      operationId: create-authentication-settings
      parameters:
        - name: pointOfSaleId
          in: path
          required: true
          example: 123456789
          description: The unique system identifier for the point of sale device.
          schema:
            type: integer
            format: int64
      requestBody:
        description: The authentication settings to apply to the point of sale device.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAuthenticationSettingsRequest'
      responses:
        '200':
          description: Successfully created the authentication settings.
    get:
      tags:
        - Authentication settings
      summary: Get authentication settings
      description: >-
        This endpoint retrieves the authentication settings for a specific point
        of sale device.
      operationId: get-authentication-settings
      parameters:
        - name: pointOfSaleId
          in: path
          required: true
          description: The unique system identifier for the point of sale device.
          example: 123456789
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Successfully retrieved the authentication settings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAuthenticationSettingsResponse'
    put:
      tags:
        - Authentication settings
      summary: Update authentication settings
      description: >-
        This endpoint updates the authentication settings for a specific point
        of sale device.
      operationId: update-authentication-settings
      parameters:
        - name: pointOfSaleId
          in: path
          required: true
          description: The unique system identifier for the point of sale device.
          example: 12345789
          schema:
            type: integer
            format: int64
      requestBody:
        description: The updated authentication settings.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAuthenticationSettingsRequest'
      responses:
        '200':
          description: Successfully updated the authentication settings.
  /point-of-sales/{pointOfSaleId}/feature-settings:
    post:
      tags:
        - Feature settings
      summary: Create feature settings
      description: >-
        This endpoint creates feature settings for a specific point of sale
        device.
      operationId: create-feature-settings
      parameters:
        - name: pointOfSaleId
          in: path
          required: true
          description: The unique system identifier for the point of sale device.
          example: 123456789
          schema:
            type: integer
            format: int64
      requestBody:
        description: The feature settings to apply to the point of sale device.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFeatureSettingsRequest'
      responses:
        '200':
          description: Successfully created the feature settings.
    get:
      tags:
        - Feature settings
      summary: Get feature settings
      description: >-
        This endpoint retrieves the feature settings for a specific point of
        sale device.
      operationId: get-feature-settings
      parameters:
        - name: pointOfSaleId
          in: path
          required: true
          example: 123456789
          description: The unique system identifier for the point of sale device.
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Successfully retrieved the feature settings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetFeatureSettingsResponse'
    put:
      tags:
        - Feature settings
      summary: Update feature settings
      description: >-
        This endpoint updates the feature settings for a specific point of sale
        device.
      operationId: update-feature-settings
      parameters:
        - name: pointOfSaleId
          in: path
          required: true
          description: The unique system identifier for the point of sale device.
          example: 123456789
          schema:
            type: integer
            format: int64
      requestBody:
        description: The updated feature settings.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFeatureSettingsRequest'
      responses:
        '200':
          description: Successfully updated the feature settings.
  /point-of-sales/{site}/general-settings:
    post:
      tags:
        - General settings
      summary: Create general settings
      description: This endpoint creates general settings for a specific site.
      operationId: create-general-settings
      parameters:
        - name: site
          in: path
          example: SITE-1
          required: true
          description: The ID of the site where the settings will be applied.
          schema:
            type: string
      requestBody:
        description: The general settings to apply to the site.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGeneralSettingsRequest'
      responses:
        '200':
          description: Successfully created the general settings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateGeneralSettingsResponse'
  /point-of-sales/{pointOfSaleId}/general-settings:
    get:
      tags:
        - General settings
      summary: Get general settings
      description: >-
        This endpoint retrieves the general settings for a specific point of
        sale device.
      operationId: get-general-settings
      parameters:
        - name: pointOfSaleId
          in: path
          required: true
          description: The unique system identifier for the point of sale device.
          example: 123456789
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Successfully retrieved the general settings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetGeneralSettingsResponse'
    put:
      tags:
        - General settings
      summary: Update general settings
      description: >-
        This endpoint updates the general settings for a specific point of sale
        device.
      operationId: update-general-settings
      parameters:
        - name: pointOfSaleId
          in: path
          required: true
          description: The unique system identifier for the point of sale device.
          example: 123456789
          schema:
            type: integer
            format: int64
      requestBody:
        description: The updated general settings.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateGeneralSettingsRequest'
      responses:
        '200':
          description: Successfully updated the general settings.
  /point-of-sales/{pointOfSaleId}/log-settings:
    post:
      tags:
        - Log settings
      summary: Create log settings
      description: This endpoint creates log settings for a specific point of sale device.
      operationId: create-log-settings
      parameters:
        - name: pointOfSaleId
          in: path
          required: true
          example: 123456789
          description: The unique system identifier for the point of sale device.
          schema:
            type: integer
            format: int64
      requestBody:
        description: The log settings to apply to the point of sale device.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateLogSettingsRequest'
      responses:
        '200':
          description: Successfully created the log settings.
    get:
      tags:
        - Log settings
      summary: Get log settings
      description: >-
        This endpoint retrieves the log settings for a specific point of sale
        device.
      operationId: get-log-settings
      parameters:
        - name: pointOfSaleId
          in: path
          required: true
          example: 123456789
          description: The unique system identifier for the point of sale device.
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Successfully retrieved the log settings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetLogSettingsResponse'
    put:
      tags:
        - Log settings
      summary: Update log settings
      description: >-
        This endpoint updates the log settings for a specific point of sale
        device.
      operationId: update-log-settings
      parameters:
        - name: pointOfSaleId
          in: path
          required: true
          example: 123456789
          description: The unique system identifier for the point of sale device.
          schema:
            type: integer
            format: int64
      requestBody:
        description: The updated log settings.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateLogSettingsRequest'
      responses:
        '200':
          description: Successfully updated the log settings.
  /point-of-sales/{pointOfSaleId}/store-and-forward-settings:
    post:
      tags:
        - Store and Forward settings
      summary: Create Store and Forward settings
      description: >-
        This endpoint creates store and forward settings for a specific point of
        sale device.
      operationId: create-store-and-forward-settings
      parameters:
        - name: pointOfSaleId
          in: path
          required: true
          description: The unique system identifier for the point of sale device.
          example: 123456789
          schema:
            type: integer
            format: int64
      requestBody:
        description: The store and forward settings to apply to the point of sale device.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateStoreAndForwardSettingsRequest'
      responses:
        '200':
          description: Successfully created the store and forward settings.
    get:
      tags:
        - Store and Forward settings
      summary: Get Store and Forward settings
      description: >-
        This endpoint retrieves the store and forward settings for a specific
        point of sale device.
      operationId: get-store-and-forward-settings
      parameters:
        - name: pointOfSaleId
          in: path
          required: true
          example: 123456789
          description: The unique system identifier for the point of sale device.
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Successfully retrieved the store and forward settings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetStoreAndForwardSettingsResponse'
    put:
      tags:
        - Store and Forward settings
      summary: Update Store and Forward settings
      description: >-
        This endpoint updates the store and forward settings for a specific
        point of sale device.
      operationId: update-store-and-forward-settings
      parameters:
        - name: pointOfSaleId
          in: path
          required: true
          example: 123456789
          description: The unique system identifier for the point of sale device.
          schema:
            type: integer
            format: int64
      requestBody:
        description: The updated store and forward settings.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateStoreAndForwardSettingsRequest'
      responses:
        '200':
          description: Successfully updated the store and forward settings.
  /point-of-sales/{pointOfSaleId}/host-url-settings:
    post:
      tags:
        - URL settings
      summary: Create host URL settings
      description: >-
        This endpoint creates host URL settings for a specific point of sale
        device.
      operationId: create-host-url-settings
      parameters:
        - name: pointOfSaleId
          in: path
          required: true
          example: 123456789
          description: The unique system identifier for the point of sale device.
          schema:
            type: integer
            format: int64
      requestBody:
        description: The host URL settings to apply to the point of sale device.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateHostUrlRequest'
      responses:
        '200':
          description: Successfully created the host URL settings.
  /point-of-sales/{pointOfSaleId}/{urlType}/host-url-settings:
    get:
      tags:
        - URL settings
      summary: Get host URL settings
      description: >-
        This endpoint retrieves specific host URL settings for a point of sale
        device by URL type.
      operationId: get-host-url-settings
      parameters:
        - name: pointOfSaleId
          in: path
          required: true
          example: 123465789
          description: The unique system identifier for the point of sale device.
          schema:
            type: integer
            format: int64
        - name: urlType
          in: path
          required: true
          description: >-
            The type of URL (e.g., Transaction, StoreAndForward,
            InStoreNotification).
          schema:
            $ref: '#/components/schemas/HostUrlTypes'
      responses:
        '200':
          description: Successfully retrieved the host URL settings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetHostUrlResponse'
    put:
      tags:
        - URL settings
      summary: Update host URL settings
      description: >-
        This endpoint updates specific host URL settings for a point of sale
        device by URL type.
      operationId: update-host-url-settings
      parameters:
        - name: pointOfSaleId
          in: path
          required: true
          example: 123456789
          description: The unique system identifier for the point of sale device.
          schema:
            type: integer
            format: int64
        - name: urlType
          in: path
          required: true
          description: >-
            The type of URL (e.g., Transaction, StoreAndForward,
            InStoreNotification).
          schema:
            $ref: '#/components/schemas/HostUrlTypes'
      requestBody:
        description: The updated host URL settings.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateHostUrlRequest'
      responses:
        '200':
          description: Successfully updated the host URL settings.
components:
  schemas:
    AuthenticationSettings:
      type: object
      required:
        - hmacKey
      description: The authentication settings for a point of sale device.
      properties:
        hmacKey:
          type: string
          description: >-
            The single hmac key used in association with the point of sale
            device to authenticate.
          example: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
    CreateAuthenticationSettingsRequest:
      type: object
      required:
        - hmacKey
      description: >-
        The request to create authentication settings for a point of sale
        device.
      properties:
        hmacKey:
          type: string
          description: >-
            The single hmac key used in association with the point of sale
            device to authenticate.
          example: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
    CreateFeatureSettingsRequest:
      type: object
      description: The request to create feature settings for a point of sale device.
      properties:
        merchantPointOfSaleId:
          type: string
          nullable: true
          description: The unique merchant identifier for the point of sale device.
          example: POS-12345
        statusPacketsEnabled:
          type: boolean
          nullable: true
          description: >-
            Indicates whether status packets, which provide real-time updates
            about the device's status, are enabled for the point of sale device.
          example: true
        languageSelectionEnabled:
          type: boolean
          nullable: true
          description: >-
            Specifies whether the language selection feature is enabled,
            allowing users to choose their preferred language during
            transactions.
          example: true
        gratuityEnabled:
          type: boolean
          nullable: true
          description: >-
            Indicates whether the gratuity (tip) feature is enabled, allowing
            customers to add a tip to their transactions.
          example: false
        onlinePinEnabled:
          type: boolean
          nullable: true
          description: >-
            Specifies whether the online PIN feature is enabled, requiring
            customers to enter their PIN for card transactions.
          example: true
        keyedEnabled:
          type: boolean
          nullable: true
          description: >-
            Indicates whether the keyed entry feature is enabled, allowing
            manual entry of card details for transactions.
          example: false
    CreateGeneralSettingsRequest:
      type: object
      description: The request to create general settings for a site.
      required:
        - serialNumber
        - deviceModel
        - communicationProtocol
      properties:
        serialNumber:
          type: string
          description: The serial number of the point of sale device to activate.
          example: SN1234567890
        merchantPointOfSaleId:
          type: string
          description: The unique merchant identifier for the point of sale device.
          nullable: true
          example: POS-12345
        deviceModel:
          $ref: '#/components/schemas/DeviceModels'
        communicationProtocol:
          $ref: '#/components/schemas/CommunicationProtocols'
        communicationEndpoint:
          $ref: '#/components/schemas/CommunicationEndpoint'
    CreateGeneralSettingsResponse:
      type: object
      description: The response after creating general settings for a site.
      properties:
        status:
          $ref: '#/components/schemas/Status'
        site:
          type: string
          description: The ID of the site where the point of sale will be deployed.
          example: SITE-1
        merchantPointOfSaleId:
          type: string
          description: The unique merchant identifier for the point of sale device.
          example: POS-12345
        pointOfSaleId:
          description: The unique system identifier for the point of sale device.
          type: integer
          format: int64
          example: 123456789
    CreateHostUrlRequest:
      type: object
      description: The request to create a host URL for a point of sale device.
      properties:
        url:
          type: string
          nullable: true
          example: https://transaction.example.com
        urlType:
          $ref: '#/components/schemas/HostUrlTypes'
    CreateLogSettingsRequest:
      type: object
      description: The request to create log settings for a point of sale device.
      properties:
        verboseLoggingEnabled:
          type: boolean
          description: >-
            Indicates whether verbose logging is enabled for the point of sale
            device. When enabled, more detailed logs are generated, which can be
            useful for debugging and troubleshooting.
          nullable: true
          example: true
        maximumLogSize:
          type: integer
          format: int32
          description: >-
            The maximum size of the log file in bytes. Once the log file reaches
            this size, older log entries may be removed or archived to prevent
            exceeding the size limit.
          example: 10485760
          nullable: true
        logFileCleanUpDays:
          type: integer
          format: int32
          nullable: true
          description: >-
            The number of days after which log files are cleaned up or archived.
            This helps manage storage by removing or archiving logs that are
            older than the specified number of days.
          example: 30
    CreatePointOfSaleRequest:
      type: object
      description: The request to create a new point of sale device.
      required:
        - serialNumber
        - merchantPointOfSaleId
        - deviceModel
        - communicationProtocol
        - authenticationSettings
      properties:
        serialNumber:
          type: string
          description: The serial number of the point of sale device
          example: SN1234567890
        merchantPointOfSaleId:
          type: string
          description: The unique merchant identifier for the point of sale device.
          example: POS-12345
        deviceModel:
          $ref: '#/components/schemas/DeviceModels'
        communicationProtocol:
          $ref: '#/components/schemas/CommunicationProtocols'
        communicationEndpoint:
          $ref: '#/components/schemas/CommunicationEndpoint'
        authenticationSettings:
          $ref: '#/components/schemas/AuthenticationSettings'
        hostUrls:
          type: array
          description: The endpoint URLs used by the PXP point of sale application.
          items:
            $ref: '#/components/schemas/HostUrl'
          nullable: true
          example:
            - url: https://transaction.example.com
              urlType: Transaction
        logSettings:
          $ref: '#/components/schemas/LogSettings'
        featureSettings:
          $ref: '#/components/schemas/FeatureSettings'
        storeAndForwardSettings:
          $ref: '#/components/schemas/StoreAndForwardSettings'
    CreatePointOfSaleResponse:
      type: object
      description: The response after creating a new point of sale device.
      properties:
        status:
          $ref: '#/components/schemas/Status'
        site:
          type: string
          description: The ID of the site where the point of sale will be deployed.
          example: SITE-1
        merchantPointOfSaleId:
          type: string
          description: The unique merchant identifier for the point of sale device.
          example: POS-12345
        pointOfSaleId:
          type: integer
          description: The unique system identifier for the point of sale device.
          format: int64
          example: 123456789
    CreateStoreAndForwardSettingsRequest:
      type: object
      description: >-
        The request to create store and forward settings for a point of sale
        device.
      properties:
        storeAndForwardEnabled:
          type: boolean
          description: >-
            Specifies whether the store and forward feature should be enabled
            for the point of sale device. This feature allows transactions to be
            temporarily stored locally when there is no network connectivity and
            then forwarded to the server once connectivity is restored.
          nullable: true
          example: true
        transactionAmountThreshold:
          type: integer
          format: int32
          description: >-
            Defines the maximum transaction amount (in the smallest currency
            unit, such as cents) that can be processed using the store and
            forward feature. Transactions that exceed this threshold will not be
            stored for later forwarding.
          nullable: true
          example: 10000
        throttlingLimit:
          type: integer
          format: int32
          description: >-
            Sets the maximum number of transactions that can be processed within
            a specific time frame when the store and forward feature is enabled.
            This helps to manage the flow of transactions once network
            connectivity is restored.
          nullable: true
          example: 100
        processInterval:
          type: integer
          format: int32
          description: >-
            Specifies the time interval (in seconds) between attempts to process
            and forward stored transactions once network connectivity is
            available.
          nullable: true
          example: 300
        x509PrivateKey:
          type: string
          nullable: true
          description: >-
            The private key used for encrypting stored transaction data. This
            key is part of the X.509 certificate standard, which is used to
            ensure secure communications.
          example: MIIBVgIBADANBgkqhkiG9w0BAQEFAASC...
        x509PublicKey:
          type: string
          nullable: true
          description: >-
            The public key associated with the private key, used in conjunction
            with the X.509 certificate for encryption and secure communication.
          example: MFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAE...
        keyGenerated:
          type: string
          format: date-time
          nullable: true
          description: >-
            The date and time when the encryption keys were generated, formatted
            according to the ISO 8601 standard.
          example: '2023-09-01T12:00:00Z'
    DeviceModels:
      enum:
        - CastlesSaturn1000
        - ZebraTC510K
      type: string
      description: The model of the point of sale device.
      example: CastlesSaturn1000
    FeatureSettings:
      type: object
      description: The feature settings for a point of sale device.
      properties:
        statusPacketsEnabled:
          type: boolean
          description: >-
            Indicates whether status packets, which provide real-time updates
            about the device's status, are enabled for the point of sale device.
          example: true
          nullable: true
        languageSelectionEnabled:
          type: boolean
          description: >-
            Whether the language selection feature is enabled, allowing users to
            choose their preferred language during transactions.
          example: true
          nullable: true
        gratuityEnabled:
          type: boolean
          description: >-
            Whether the gratuity (tip) feature is enabled, allowing customers to
            add a tip to their transactions.
          example: false
          nullable: true
        onlinePinEnabled:
          type: boolean
          description: >-
            Whether the online PIN feature is enabled, requiring customers to
            enter their PIN for card transactions.
          example: true
          nullable: true
        keyedEnabled:
          type: boolean
          description: >-
            Whether the keyed entry feature is enabled, allowing manual entry of
            card details for transactions.
          example: false
          nullable: true
        dccEnabled:
          type: boolean
          description: >-
            Whether the Dynamic Currency Conversion (DCC) feature is enabled,
            allowing customers to pay in their local card currency.
          example: false
          nullable: true
    GetAuthenticationSettingsResponse:
      type: object
      description: >-
        The response containing authentication settings for a point of sale
        device.
      properties:
        hmacKey:
          type: string
          nullable: true
          example: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
    GetFeatureSettingsResponse:
      type: object
      description: The response containing feature settings for a point of sale device.
      properties:
        merchantPointOfSaleId:
          type: string
          description: The unique merchant identifier for the point of sale device.
          example: POS-12345
        statusPacketsEnabled:
          type: boolean
          description: >-
            Indicates whether status packets, which provide real-time updates
            about the device's status, are enabled for the point of sale device.
        languageSelectionEnabled:
          type: boolean
          description: >-
            Specifies whether the language selection feature is enabled,
            allowing users to choose their preferred language during
            transactions.
        gratuityEnabled:
          type: boolean
          description: >-
            Indicates whether the gratuity (tip) feature is enabled, allowing
            customers to add a tip to their transactions.
        onlinePinEnabled:
          type: boolean
          description: >-
            Specifies whether the online PIN feature is enabled, requiring
            customers to enter their PIN for card transactions.
        keyedEnabled:
          type: boolean
          description: >-
            Indicates whether the keyed entry feature is enabled, allowing
            manual entry of card details for transactions.
    GetGeneralSettingsResponse:
      type: object
      description: The response containing general settings for a point of sale device.
      properties:
        site:
          type: string
          description: The ID of the site where the point of sale will be deployed.
          example: SITE-1
        serialNumber:
          type: string
          description: The serial number of the point of sale device
          example: SN1234567890
        merchantPointOfSaleId:
          type: string
          description: The unique merchant identifier for the point of sale device.
          example: POS-12345
        pointOfSaleId:
          description: The unique system identifier for the point of sale device.
          type: integer
          format: int64
          example: 123456789
        deviceModel:
          $ref: '#/components/schemas/DeviceModels'
        communicationProtocol:
          $ref: '#/components/schemas/CommunicationProtocols'
        communicationEndpoint:
          description: >-
            The URL or network endpoint where the point of sale device actively
            listens for incoming connections and communications from the
            merchant system.
          type: string
          example: http://pos.example.com
        status:
          $ref: '#/components/schemas/Status'
        createdOn:
          type: string
          format: date-time
          example: '2023-09-01T12:00:00Z'
        updatedOn:
          type: string
          format: date-time
          nullable: true
          example: '2023-09-10T15:00:00Z'
    GetHostUrlResponse:
      type: object
      description: The response containing host URL settings for a point of sale device.
      properties:
        url:
          type: string
          nullable: true
          example: https://transaction.example.com
        urlType:
          $ref: '#/components/schemas/HostUrlTypes'
    GetLogSettingsResponse:
      type: object
      description: The response containing log settings for a point of sale device.
      properties:
        verboseLoggingEnabled:
          type: boolean
          description: >-
            Indicates whether verbose logging is enabled for the point of sale
            device. When enabled, more detailed logs are generated, which can be
            useful for debugging and troubleshooting.
          example: true
        maximumLogSize:
          type: integer
          format: int32
          description: >-
            The maximum size of the log file in bytes. Once the log file reaches
            this size, older log entries may be removed or archived to prevent
            exceeding the size limit.
          example: 10485760
        logFileCleanUpDays:
          type: integer
          format: int32
          description: >-
            The number of days after which log files are cleaned up or archived.
            This helps manage storage by removing or archiving logs that are
            older than the specified number of days.
          example: 30
    GetPointOfSaleResponse:
      type: object
      description: The response containing point of sale device details.
      properties:
        site:
          type: string
          description: The ID of the site where the point of sale will be deployed.
          example: SITE-1
        serialNumber:
          type: string
          description: The serial number of the point of sale device
          example: SN1234567890
        merchantPointOfSaleId:
          type: string
          description: The unique merchant identifier for the point of sale device.
          example: POS-12345
        pointOfSaleId:
          description: The unique system identifier for the point of sale device.
          type: integer
          format: int64
          example: 123456789
        deviceModel:
          $ref: '#/components/schemas/DeviceModels'
        communicationProtocol:
          $ref: '#/components/schemas/CommunicationProtocols'
        communicationEndpoint:
          $ref: '#/components/schemas/CommunicationEndpoint'
        authenticationSettings:
          $ref: '#/components/schemas/AuthenticationSettings'
        hostUrls:
          type: array
          description: The endpoint URLs used by the PXP point of sale application
          items:
            $ref: '#/components/schemas/HostUrl'
          nullable: true
          example:
            - url: https://transaction.example.com
              urlType: Transaction
        logSettings:
          $ref: '#/components/schemas/LogSettings'
        featureSettings:
          $ref: '#/components/schemas/FeatureSettings'
        storeAndForwardSettings:
          $ref: '#/components/schemas/StoreAndForwardSettings'
        status:
          $ref: '#/components/schemas/Status'
        createdOn:
          type: string
          format: date-time
          example: '2023-09-01T12:00:00Z'
        updatedOn:
          type: string
          format: date-time
          nullable: true
          example: '2023-09-10T15:00:00Z'
    GetStoreAndForwardSettingsResponse:
      type: object
      description: >-
        The response containing store and forward settings for a point of sale
        device.
      properties:
        storeAndForwardEnabled:
          type: boolean
          description: >-
            Indicates whether the store and forward feature is enabled for the
            point of sale device. This feature allows transactions to be
            temporarily stored locally when there is no network connectivity and
            forwarded to the server once connectivity is restored.
          example: true
        transactionAmountThreshold:
          type: integer
          format: int32
          description: >-
            Specifies the maximum transaction amount (in the smallest currency
            unit, such as cents) that can be processed using the store and
            forward feature. Transactions exceeding this amount will not be
            stored for later forwarding.
          example: 10000
        throttlingLimit:
          type: integer
          format: int32
          description: >-
            Defines the maximum number of transactions that can be processed in
            a given time frame when the store and forward feature is enabled.
            This helps to manage the flow of transactions when connectivity is
            restored.
          example: 100
        processInterval:
          type: integer
          format: int32
          description: >-
            Indicates the interval (in seconds) between attempts to process and
            forward stored transactions once network connectivity is available.
          example: 300
        x509PrivateKey:
          type: string
          nullable: true
          description: >-
            The private key used for encryption of stored transaction data. This
            key is part of the X.509 certificate standard used for secure
            communications.
          example: MIIBVgIBADANBgkqhkiG9w0BAQEFAASC...
        x509PublicKey:
          type: string
          nullable: true
          description: >-
            The public key associated with the private key, used in the X.509
            certificate for encryption and secure communication.
          example: MFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAE...
        keyGenerated:
          type: string
          format: date-time
          description: >-
            The date and time when the encryption keys were generated, formatted
            in ISO 8601.
          example: '2023-09-01T12:00:00Z'
    HostUrl:
      type: object
      description: The host URL settings for a point of sale device.
      properties:
        url:
          type: string
          nullable: true
          example: https://transaction.example.com
        urlType:
          $ref: '#/components/schemas/HostUrlTypes'
    HostUrlTypes:
      enum:
        - Transaction
        - StoreAndForward
        - InStoreNotification
        - DCC
      type: string
      description: The type of URL.
      example: Transaction
    CommunicationProtocols:
      enum:
        - HTTP
      type: string
      description: The protocol used by the point of sale device.
      example: HTTP
    CommunicationEndpoint:
      type: string
      nullable: true
      description: >-
        The URL or network endpoint where the point of sale device actively
        listens for incoming connections and communications from the merchant
        system.
      example: http://pos.example.com
    LogSettings:
      type: object
      description: The log settings for a point of sale device.
      properties:
        verboseLoggingEnabled:
          type: boolean
          nullable: true
          description: >-
            Indicates whether verbose logging is enabled for the point of sale
            device. When enabled, more detailed logs are generated, which can be
            useful for debugging and troubleshooting.
          example: true
        maximumLogSize:
          type: integer
          format: int32
          nullable: true
          description: >-
            The maximum size of the log file in bytes. Once the log file reaches
            this size, older log entries may be removed or archived to prevent
            exceeding the size limit.
          example: 10485760
        logFileCleanUpDays:
          type: integer
          format: int32
          nullable: true
          description: >-
            The number of days after which log files are cleaned up or archived.
            This helps manage storage by removing or archiving logs that are
            older than the specified number of days.
          example: 30
    Status:
      enum:
        - New
        - Pending
        - Active
        - Disabled
      type: string
      description: The status of the point of sale device.
      example: Active
    StoreAndForwardSettings:
      type: object
      description: The store and forward settings for a point of sale device.
      properties:
        storeAndForwardEnabled:
          type: boolean
          description: >-
            Indicates whether the store and forward feature is enabled for the
            point of sale device. This feature allows transactions to be stored
            locally when there is no network connectivity and then forwarded to
            the server once connectivity is restored.
          example: true
          nullable: true
        transactionAmountThreshold:
          type: integer
          format: int32
          description: >-
            The maximum transaction amount, in the smallest currency unit (such
            as cents), that can be processed using the store and forward
            feature. Transactions exceeding this threshold will not be stored
            for later forwarding.
          example: 10000
          nullable: true
        throttlingLimit:
          type: integer
          format: int32
          description: >-
            The maximum number of transactions that can be processed within a
            specified time frame when the store and forward feature is enabled.
            This setting helps control the flow of transactions once network
            connectivity is restored.
          example: 100
          nullable: true
        processInterval:
          type: integer
          format: int32
          description: >-
            The time interval, in seconds, between attempts to process and
            forward stored transactions once network connectivity is available.
          example: 300
          nullable: true
        x509PrivateKey:
          type: string
          nullable: true
          description: >-
            The private key used for encrypting stored transaction data. This
            key is part of the X.509 certificate standard, which is used to
            ensure secure communications.
          example: MIIBVgIBADANBgkqhkiG9w0BAQEFAASC...
        x509PublicKey:
          type: string
          nullable: true
          description: >-
            The public key associated with the private key, used in conjunction
            with the X.509 certificate for encryption and secure communication.
          example: MFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAE...
        keyGenerated:
          type: string
          format: date-time
          description: >-
            The date and time when the encryption keys were generated, formatted
            according to the ISO 8601 standard.
          example: '2023-09-01T12:00:00Z'
          nullable: true
    UpdateAuthenticationSettingsRequest:
      type: object
      description: >-
        The request to update authentication settings for a point of sale
        device.
      properties:
        hmacKey:
          type: string
          nullable: true
          example: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
    UpdateFeatureSettingsRequest:
      type: object
      description: The request to update feature settings for a point of sale device.
      properties:
        merchantPointOfSaleId:
          type: string
          description: The unique merchant identifier for the point of sale device.
          nullable: true
          example: POS-12345
        statusPacketsEnabled:
          type: boolean
          description: >-
            Indicates whether status packets, which provide real-time updates
            about the device's status, are enabled for the point of sale device.
          example: true
          nullable: true
        languageSelectionEnabled:
          type: boolean
          description: >-
            Specifies whether the language selection feature is enabled,
            allowing users to choose their preferred language during
            transactions.
          example: true
          nullable: true
        gratuityEnabled:
          type: boolean
          description: >-
            Indicates whether the gratuity (tip) feature is enabled, allowing
            customers to add a tip to their transactions.
          example: false
          nullable: true
        onlinePinEnabled:
          type: boolean
          description: >-
            Specifies whether the online PIN feature is enabled, requiring
            customers to enter their PIN for card transactions.
          example: true
          nullable: true
        keyedEnabled:
          type: boolean
          description: >-
            Indicates whether the keyed entry feature is enabled, allowing
            manual entry of card details for transactions.
          example: false
          nullable: true
    UpdateGeneralSettingsRequest:
      type: object
      description: The request to update general settings for a point of sale device.
      properties:
        site:
          type: string
          description: The ID of the site where the point of sale will be deployed.
          example: SITE-1
          nullable: true
        serialNumber:
          type: string
          description: The serial number of the point of sale device
          example: SN1234567890
          nullable: true
        merchantPointOfSaleId:
          type: string
          description: The unique merchant identifier for the point of sale device.
          nullable: true
          example: POS-12345
        deviceModel:
          $ref: '#/components/schemas/DeviceModels'
        communicationProtocol:
          $ref: '#/components/schemas/CommunicationProtocols'
        communicationEndpoint:
          $ref: '#/components/schemas/CommunicationEndpoint'
        status:
          $ref: '#/components/schemas/Status'
    UpdateHostUrlRequest:
      type: object
      description: The request to update host URL settings for a point of sale device.
      properties:
        url:
          type: string
          nullable: true
          example: https://transaction.example.com
    UpdateLogSettingsRequest:
      type: object
      description: The request to update log settings for a point of sale device.
      properties:
        verboseLoggingEnabled:
          type: boolean
          description: >-
            Indicates whether verbose logging is enabled for the point of sale
            device. When enabled, more detailed logs are generated, which can be
            useful for debugging and troubleshooting.
          example: true
          nullable: true
        maximumLogSize:
          type: integer
          format: int32
          description: >-
            The maximum size of the log file in bytes. Once the log file reaches
            this size, older log entries may be removed or archived to prevent
            exceeding the size limit.
          example: 10485760
          nullable: true
        logFileCleanUpDays:
          type: integer
          format: int32
          description: >-
            The number of days after which log files are cleaned up or archived.
            This helps manage storage by removing or archiving logs that are
            older than the specified number of days.
          example: 30
          nullable: true
    UpdatePointOfSaleRequest:
      type: object
      description: The request to update a point of sale device's details.
      properties:
        status:
          $ref: '#/components/schemas/Status'
        site:
          type: string
          description: The ID of the site where the point of sale will be deployed.
          example: SITE-1
          nullable: true
        serialNumber:
          type: string
          description: The serial number of the point of sale device
          example: SN1234567890
          nullable: true
        merchantPointOfSaleId:
          type: string
          description: The unique merchant identifier for the point of sale device.
          nullable: true
          example: POS-12345
        deviceModel:
          $ref: '#/components/schemas/DeviceModels'
        communicationProtocol:
          $ref: '#/components/schemas/CommunicationProtocols'
        communicationEndpoint:
          $ref: '#/components/schemas/CommunicationEndpoint'
        authenticationSettings:
          $ref: '#/components/schemas/AuthenticationSettings'
        hostUrls:
          type: array
          description: The endpoint URLs used by the PXP point of sale application
          items:
            $ref: '#/components/schemas/HostUrl'
          nullable: true
          example:
            - url: https://transaction.example.com
              urlType: Transaction
        logSettings:
          $ref: '#/components/schemas/LogSettings'
        featureSettings:
          $ref: '#/components/schemas/FeatureSettings'
        storeAndForwardSettings:
          $ref: '#/components/schemas/StoreAndForwardSettings'
    UpdateStoreAndForwardSettingsRequest:
      type: object
      description: >-
        The request to update store and forward settings for a point of sale
        device.
      properties:
        storeAndForwardEnabled:
          type: boolean
          description: >-
            Specifies whether the store and forward feature should remain
            enabled or be disabled for the point of sale device. This feature
            allows transactions to be stored locally when there is no network
            connectivity and then forwarded to the server once connectivity is
            restored.
          example: true
          nullable: true
        transactionAmountThreshold:
          type: integer
          format: int32
          description: >-
            Defines the maximum transaction amount (in the smallest currency
            unit, such as cents) that can be processed using the store and
            forward feature. Transactions exceeding this amount will not be
            stored for later forwarding.
          example: 10000
          nullable: true
        throttlingLimit:
          type: integer
          format: int32
          description: >-
            Sets the maximum number of transactions that can be processed within
            a specific time frame when the store and forward feature is enabled.
            This helps to control the flow of transactions once network
            connectivity is restored.
          example: 100
          nullable: true
        processInterval:
          type: integer
          format: int32
          description: >-
            Specifies the time interval (in seconds) between attempts to process
            and forward stored transactions once network connectivity is
            available.
          example: 300
          nullable: true
        x509PrivateKey:
          type: string
          nullable: true
          description: >-
            The private key used for encrypting stored transaction data. This
            key is part of the X.509 certificate standard, which is used to
            ensure secure communications.
          example: MIIBVgIBADANBgkqhkiG9w0BAQEFAASC...
        x509PublicKey:
          type: string
          nullable: true
          description: >-
            The public key associated with the private key, used in conjunction
            with the X.509 certificate for encryption and secure communication.
          example: MFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAE...
        keyGenerated:
          type: string
          format: date-time
          description: >-
            The date and time when the encryption keys were generated, formatted
            according to the ISO 8601 standard.
          example: '2023-09-01T12:00:00Z'
          nullable: true
