Paymentsense PAC Reports API

openapi: 3.2.0
info:
  version: '3.1'
  title: Connect REST PAC Reports API
servers:
- url: https://your-host-here.test.connect.paymentsense.cloud/
security:
- connectBasicAuth: []
tags:
- name: PAC Reports
paths:
  /pac/terminals/{tpi}/reports:
    post:
      description: Starts a report on the terminal with the given TPI.
      tags:
      - PAC Reports
      operationId: RetailReportRequest
      parameters:
      - $ref: '#/components/parameters/tpiParam'
      responses:
        '201':
          description: Report has successfully started. Returns the report requestId and the location of an endpoint for further details.
          content:
            application/connect.v1+json:
              schema:
                $ref: '#/components/schemas/requestLocationResponse'
        '401':
          description: Authorization credentials must be provided in the request headers.
        '401 ':
          description: The provided authorization credentials were not correct.
        '422 ':
          description: Incorrect JSON received.
        '500 ':
          description: An internal Connect error has occurred.
      requestBody:
        content:
          application/connect.v1+json:
            schema:
              $ref: '#/components/schemas/reportRequest'
        required: true
  /pac/terminals/{tpi}/reports/{requestId}:
    get:
      description: Gets data for the report with the given requestId.
      tags:
      - PAC Reports
      operationId: RetailReportDetails
      parameters:
      - $ref: '#/components/parameters/tpiParam'
      - $ref: '#/components/parameters/requestIdParam'
      responses:
        '200':
          description: "Report details have been successfully returned.  \nProperties marked with an * are always returned. Other properties are only returned following a completed report (e.g. most recent notification is \"REPORT_FINISHED\"), however their values may be empty."
          content:
            application/connect.v1+json:
              schema:
                $ref: '#/components/schemas/reportResponsePAC'
        '401':
          description: Authorization credentials must be provided in the request headers.
        '401 ':
          description: The provided authorization credentials were not correct.
        '404':
          description: Unavailable terminal or no data available for terminal.
        '404 ':
          description: The requestId could not be found.
        '500':
          description: An internal Connect error has occurred.
components:
  schemas:
    totalsBreakdown:
      type: object
      required:
      - currency
      - totalAmount
      - totalRefundsAmount
      - totalRefundsCount
      - totalSalesAmount
      - totalSalesCount
      properties:
        currency:
          $ref: '#/components/schemas/currency'
        totalAmount:
          description: Total amount that has been taken in the current session.
          type: integer
        totalRefundsAmount:
          description: Total amount of refunds (in pence) that have been taken in the current session.
          type: integer
        totalRefundsCount:
          description: Total number of refunds that have taken place in the current session.
          type: integer
        totalSalesAmount:
          description: Total amount of sales (in pence) that have been taken in the current session.
          type: integer
        totalSalesCount:
          description: Total number of sales that have taken place in the current session.
          type: integer
    receiptLine:
      type: object
      required:
      - value
      properties:
        format:
          description: Defines any special formatting applied to this line.
          type: array
          items:
            $ref: '#/components/schemas/format'
          example:
          - BOLD
        type:
          description: The type of the content contained in the value field.
          type: string
          enum:
          - TEXT
          - BOX_DECLINE
          - BOX_VOID
          - CARRIAGE_RETURN
          - LINE_SEPARATOR_SINGLE
          - LINE_SEPARATOR_DOUBLE
          - TICKET_FEED
          example: TEXT
        value:
          description: Raw content of the line.
          type: string
          example: John's Shop
    currency:
      description: Currency of the request. The textual representation from ISO 4217 is used.
      type: string
      enum:
      - GBP
      - EUR
      example: GBP
    reportBalances:
      description: Local totals for the current terminal session. Only contained in X_BALANCE, Z_BALANCE and END_OF_DAY.
      type: object
      required:
      - currency
      - issuerTotals
      - totalAmount
      - totalCashbackAmount
      - totalCashbackCount
      - totalGratuityAmount
      - totalGratuityCount
      - totalRefundsAmount
      - totalRefundsCount
      - totalSalesAmount
      - totalSalesCount
      - totalsSince
      - waiterTotals
      properties:
        currency:
          $ref: '#/components/schemas/currency'
        issuerTotals:
          $ref: '#/components/schemas/issuerTotals'
        totalAmount:
          description: Total amount that has been taken in the current session.
          type: integer
          example: '1000'
        totalCashbackAmount:
          description: Total amount of cashback (in pence) that has been taken in the current session.
          type: integer
          example: '100'
        totalCashbackCount:
          description: Total number of transactions with cashback that have taken place in the current session.
          type: integer
          example: '2'
        totalGratuityAmount:
          description: Total amount of gratuity (in pence) that has been taken in the current session.
          type: integer
          example: '100'
        totalGratuityCount:
          description: Total number of transactions with gratuity that have taken place in the current session.
          type: integer
          example: '3'
        totalRefundsAmount:
          description: Total amount of refunds (in pence) that have been taken in the current session.
          type: integer
          example: '400'
        totalRefundsCount:
          description: Total number of refunds that have taken place in the current session.
          type: integer
          example: '9'
        totalSalesAmount:
          description: Total amount of sales (in pence) that have been taken in the current session.
          type: integer
          example: '1200'
        totalSalesCount:
          description: Total number of sales that have taken place in the current session.
          type: integer
          example: '14'
        totalsSince:
          description: Time at which the terminal totals were last reset.
          type: string
          example: INSTALLATION
        waiterTotals:
          $ref: '#/components/schemas/waiterTotals'
    reportType:
      description: Type of the report.
      type: string
      enum:
      - END_OF_DAY
      - BANKING
      - X_BALANCE
      - Z_BALANCE
      example: END_OF_DAY
    reportBanking:
      type: object
      required:
      - currency
      - currentSessionIssuerTotals
      - previousSessionIssuerTotals
      - currentSessionTotals
      - previousSessionTotals
      - currentSessionTransactionNumbers
      - previousSessionTransactionNumbers
      properties:
        currency:
          $ref: '#/components/schemas/currency'
        currentSessionIssuerTotals:
          $ref: '#/components/schemas/issuerTotals'
        previousSessionIssuerTotals:
          $ref: '#/components/schemas/issuerTotals'
        currentSessionTotals:
          $ref: '#/components/schemas/totalsBreakdown'
        previousSessionTotals:
          $ref: '#/components/schemas/totalsBreakdown'
        currentSessionTransactionNumbers:
          description: Range of transaction numbers within the current terminal session.
          type: array
          items:
            type: string
          example:
          - '0076'
          - '0123'
        previousSessionTransactionNumbers:
          description: Range of transaction numbers within the previous terminal session.
          type: array
          items:
            type: string
          example:
          - '0000'
          - '0075'
    reportsBanking:
      type: object
      description: Banking totals for the current terminal session (these are reset in line with the banking window). Only contained in BANKING and END_OF_DAY. Consists of a dictionary of reports keyed by acquirer name. '{acquirerName}' is an example key
      properties:
        '{acquirerName}':
          $ref: '#/components/schemas/reportBanking'
    receiptLineList:
      type: array
      items:
        $ref: '#/components/schemas/receiptLine'
    waiterTotals:
      type: object
      description: A dictionary of totals split by waiter. {waiterId} is an example key.
      properties:
        '{waiterId}':
          $ref: '#/components/schemas/totalsBreakdown'
    reportRequest:
      type: object
      properties:
        reportType:
          $ref: '#/components/schemas/reportType'
    reportResponsePAC:
      type: object
      required:
      - requestId
      - location
      - notifications
      properties:
        balances:
          $ref: '#/components/schemas/reportBalances'
        banking:
          $ref: '#/components/schemas/reportsBanking'
        reportLines:
          $ref: '#/components/schemas/receiptLineList'
        reportTime:
          description: Time at which the report took place.
          type: string
          format: YYYY-MM-DDThh:mm:ss
          example: '2019-03-04T16:12:00'
        reportType:
          description: Type of the report.
          type: string
          enum:
          - END_OF_DAY
          - BANKING
          - X_BALANCE
          - Z_BALANCE
          example: END_OF_DAY
        reportResult:
          description: Outcome of the report.
          type: string
          enum:
          - TIMED_OUT
          - COMPLETE
          example: COMPLETE
        tpi:
          description: Terminal Public Identifier (unique identifier assigned to a terminal) of the terminal used in this request.
          type: string
          example: '12345678'
        requestId:
          description: UUID for this request, which can be used in other endpoints.
          type: string
          example: d19912ad-11a3-4af3-86e0-d6eb2ebea63c
        location:
          description: URI where information about this report can be found.
          type: string
          format: URI
          example: https://your-host-here.test.connect.paymentsense.cloud/terminals/{tpi}/report/{requestId}
        notifications:
          description: Notifications indicating the progress of the report.
          type: array
          items:
            type: string
            enum:
            - REPORT_FINISHED
            - REPORT_STARTED
            example:
            - REPORT_FINISHED
            - REPORT_STARTED
    requestLocationResponse:
      type: object
      properties:
        requestId:
          description: UUID for this request, which can be used in other endpoints.
          type: string
          example: d19912ad-11a3-4af3-86e0-d6eb2ebea63c
        location:
          description: URI where information about this request can be found.
          type: string
          format: URI
          example: https://your-host-here.test.connect.paymentsense.cloud/terminals/{tpi}/{requestType}/{requestId}
    format:
      type: string
      enum:
      - BOLD
      - DOUBLE_HEIGHT
      - DOUBLE_WIDTH
    issuerTotals:
      type: object
      description: A dictionary of totals split by issuer. {issuerName} is an example key.
      properties:
        '{issuerName}':
          $ref: '#/components/schemas/totalsBreakdown'
  parameters:
    requestIdParam:
      name: requestId
      description: Request Id (UUID assigned to a terminal request) of the terminal request to use in this request.
      in: path
      required: true
      schema:
        type: string
    tpiParam:
      name: tpi
      description: Terminal Public Identifier (unique identifier assigned to a terminal) of the terminal to use in this request.
      in: path
      required: true
      schema:
        type: string
  securitySchemes:
    connectBasicAuth:
      type: http
      scheme: basic