openapi: 3.0.3
info:
  title: Pay at Counter REST API
  version: '1'
  description: Documentation for the yetipay Pay at Counter REST API (v1).
servers:
  - url: https://connect.yeti.host
security:
  - connectBasicAuth: []
components:
  securitySchemes:
    connectBasicAuth:
      type: http
      scheme: basic
  schemas:
    Terminal:
      type: object
      properties:
        tpi:
          type: string
          example: '12345678'
        status:
          type: string
          enum:
            - AVAILABLE
            - BUSY
        currency:
          type: string
          enum:
            - GBP
            - EUR
        capabilities:
          type: array
          items:
            type: string
          example:
            - SALE
            - REFUND
        location:
          type: string
    StartTransactionRequest:
      type: object
      required:
        - transactionType
      properties:
        transactionType:
          type: string
          enum:
            - SALE
            - REFUND
            - DUPLICATE
          description: Type of the transaction.
        amount:
          type: integer
          description: Base amount for the transaction (in pence).
        currency:
          type: string
          enum:
            - GBP
            - EUR
          description: >-
            Currency for the request. Uses the textual representation from ISO
            4217.
    TransactionAcceptedResponse:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
          example: d19912ad-11a3-4af3-86e0-d6eb2ebea63c
        location:
          type: string
    ReceiptLine:
      type: object
      properties:
        format:
          type: array
          items:
            type: string
        type:
          type: string
        value:
          type: string
    TransactionStatusResponse:
      type: object
      properties:
        amountBase:
          type: string
          example: '100'
        amountCashback:
          type: string
          example: '30'
        amountGratuity:
          type: string
          example: '20'
        amountTotal:
          type: string
          example: '150'
        applicationId:
          type: string
          example: A0000000031010
        applicationLabel:
          type: string
          example: VISA
        authCode:
          type: string
          example: 78YT6RS0
        cardSchemeName:
          type: string
          example: VISA
        cardHolderVerificationMethod:
          type: string
          example: PIN
        currency:
          type: string
          enum:
            - GBP
            - EUR
        dateOfExpiry:
          type: string
          example: 01/25
        dateOfStart:
          type: string
          example: 01/19
        location:
          type: string
        notifications:
          type: array
          items:
            type: string
          example:
            - TRANSACTION_FINISHED
            - APPROVED
            - CONNECTION_MADE
            - CONNECTING
            - PIN_ENTRY
            - PLEASE_WAIT
            - PRESENT_CARD
            - TRANSACTION_STARTED
        paymentMethod:
          type: string
          example: ICC_CHIP
        primaryAccountNumber:
          type: string
          example: '************1234'
        primaryAccountNumberSequence:
          type: string
          example: '01'
        receiptLines:
          type: object
          properties:
            MERCHANT:
              type: array
              items:
                $ref: '#/components/schemas/ReceiptLine'
            CUSTOMER:
              type: array
              items:
                $ref: '#/components/schemas/ReceiptLine'
        requestId:
          type: string
          format: uuid
        transactionId:
          type: string
          example: '1234567'
        transactionNumber:
          type: string
          example: '0012'
        transactionResult:
          type: string
          example: SUCCESSFUL
        transactionTime:
          type: string
          example: '2019-03-04T16:12:00'
        transactionType:
          type: string
          enum:
            - SALE
            - REFUND
            - DUPLICATE
    RequestReportRequest:
      type: object
      required:
        - reportType
      properties:
        reportType:
          type: string
          enum:
            - END_OF_DAY
            - BANKING
            - X_BALANCE
            - Z_BALANCE
          description: Type of the report.
    IssuerTotal:
      type: object
      properties:
        currency:
          type: string
        totalAmount:
          type: integer
        totalRefundsAmount:
          type: integer
        totalRefundsCount:
          type: integer
        totalSalesAmount:
          type: integer
        totalSalesCount:
          type: integer
    SessionTotals:
      type: object
      properties:
        currency:
          type: string
        totalAmount:
          type: integer
        totalRefundsAmount:
          type: integer
        totalRefundsCount:
          type: integer
        totalSalesAmount:
          type: integer
        totalSalesCount:
          type: integer
    ReportStatusResponse:
      type: object
      properties:
        balances:
          type: object
          properties:
            currency:
              type: string
            issuerTotals:
              type: object
              additionalProperties:
                $ref: '#/components/schemas/IssuerTotal'
            totalAmount:
              type: string
            totalCashbackAmount:
              type: string
            totalCashbackCount:
              type: string
            totalGratuityAmount:
              type: string
            totalGratuityCount:
              type: string
            totalRefundsAmount:
              type: string
            totalRefundsCount:
              type: string
            totalSalesAmount:
              type: string
            totalSalesCount:
              type: string
            totalsSince:
              type: string
            waiterTotals:
              type: object
              additionalProperties:
                $ref: '#/components/schemas/IssuerTotal'
        banking:
          type: object
          additionalProperties:
            type: object
            properties:
              currency:
                type: string
              currentSessionTotals:
                $ref: '#/components/schemas/SessionTotals'
              previousSessionTotals:
                $ref: '#/components/schemas/SessionTotals'
              currentSessionIssuerTotals:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/IssuerTotal'
              previousSessionIssuerTotals:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/IssuerTotal'
              currentSessionTransactionNumbers:
                type: array
                items:
                  type: string
              previousSessionTransactionNumbers:
                type: array
                items:
                  type: string
        reportLines:
          type: array
          items:
            $ref: '#/components/schemas/ReceiptLine'
        reportTime:
          type: string
          example: '2019-03-04T16:12:00'
        reportType:
          type: string
          enum:
            - END_OF_DAY
            - BANKING
            - X_BALANCE
            - Z_BALANCE
        reportResult:
          type: string
          example: COMPLETE
        tpi:
          type: string
        requestId:
          type: string
          format: uuid
        location:
          type: string
        notifications:
          type: array
          items:
            type: string
  parameters:
    tpi:
      name: tpi
      in: path
      required: true
      schema:
        type: string
      description: Unique identifier of the terminal to use in this request.
    requestId:
      name: requestId
      in: path
      required: true
      schema:
        type: string
      description: >-
        Request Id (a UUID assigned to a terminal request) for the terminal
        request to use in this request.
paths:
  /pac/terminals:
    get:
      tags:
        - Terminals
      summary: List Terminals
      description: >-
        Retrieves a list of all currently connected card terminals. Results can
        be filtered by currency, capabilities, and status.
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum:
              - AVAILABLE
              - BUSY
          description: >-
            Restricts the response to show only available or only busy
            terminals.
        - name: capabilities
          in: query
          schema:
            type: string
          description: >-
            Restricts the response to terminals that have specific capabilities.
            Values should be provided as a comma-separated list.
        - name: currency
          in: query
          schema:
            type: string
            enum:
              - GBP
              - EUR
          description: >-
            Restricts the response to terminals configured for a specific
            currency.
      responses:
        '200':
          description: A list of terminals is returned
          content:
            application/connect.v1+json:
              schema:
                type: object
                properties:
                  terminals:
                    type: array
                    items:
                      $ref: '#/components/schemas/Terminal'
              example:
                terminals:
                  - tpi: '12345678'
                    status: AVAILABLE
                    currency: GBP
                    capabilities:
                      - SALE
                      - REFUND
                    location: ''
        '401':
          description: Request headers must include authorization credentials.
        '500':
          description: An internal error occurred within the API.
  /pac/terminals/{tpi}:
    get:
      tags:
        - Terminals
      summary: Get Terminal by ID
      description: Retrieves details for a specific terminal.
      parameters:
        - $ref: '#/components/parameters/tpi'
      responses:
        '200':
          description: Information about the requested terminal is returned
          content:
            application/connect.v1+json:
              schema:
                $ref: '#/components/schemas/Terminal'
              example:
                tpi: '12345678'
                status: AVAILABLE
                currency: GBP
                capabilities:
                  - SALE
                  - REFUND
                location: ''
        '401':
          description: Request headers must include authorization credentials.
        '404':
          description: Terminal is unavailable or no data is available for the terminal.
        '500':
          description: An internal error occurred within the API.
  /pac/terminals/{tpi}/transactions:
    post:
      tags:
        - Transactions
      summary: Start Transaction
      description: >-
        Initiates a transaction on the terminal identified by the given terminal
        identifier.
      parameters:
        - $ref: '#/components/parameters/tpi'
      requestBody:
        required: true
        content:
          application/connect.v1+json:
            schema:
              $ref: '#/components/schemas/StartTransactionRequest'
            example:
              transactionType: SALE
              amount: 1234
              currency: GBP
      responses:
        '201':
          description: >-
            Transaction was successfully initiated. The response includes the
            transaction requestId and an endpoint location for retrieving
            additional details.
          content:
            application/connect.v1+json:
              schema:
                $ref: '#/components/schemas/TransactionAcceptedResponse'
              example:
                requestId: d19912ad-11a3-4af3-86e0-d6eb2ebea63c
                location: ''
        '401':
          description: Request headers must include authorization credentials.
        '404':
          description: Terminal is unavailable or no data is available for the terminal.
        '422':
          description: >-
            The card terminal is currently busy or the JSON received was
            invalid.
        '500':
          description: An internal error occurred within the API.
  /pac/terminals/{tpi}/transactions/{requestId}:
    get:
      tags:
        - Transactions
      summary: Get Transaction Status
      description: Retrieves data for the transaction identified by the given requestId.
      parameters:
        - $ref: '#/components/parameters/tpi'
        - $ref: '#/components/parameters/requestId'
      responses:
        '200':
          description: >-
            Transaction details have been returned successfully. Properties
            marked with an * are always included in the response. Additional
            properties are only included after a transaction has completed (e.g.
            when the most recent notification is "TRANSACTION_FINISHED"), though
            their values may be empty.
          content:
            application/connect.v1+json:
              schema:
                $ref: '#/components/schemas/TransactionStatusResponse'
              example:
                amountBase: '100'
                amountCashback: '30'
                amountGratuity: '20'
                amountTotal: '150'
                applicationId: A0000000031010
                applicationLabel: VISA
                authCode: 78YT6RS0
                cardSchemeName: VISA
                cardHolderVerificationMethod: PIN
                currency: GBP
                dateOfExpiry: 01/25
                dateOfStart: 01/19
                location: ''
                notifications:
                  - TRANSACTION_FINISHED
                  - APPROVED
                  - CONNECTION_MADE
                  - CONNECTING
                  - PIN_ENTRY
                  - PLEASE_WAIT
                  - PRESENT_CARD
                  - TRANSACTION_STARTED
                paymentMethod: ICC_CHIP
                primaryAccountNumber: '************1234'
                primaryAccountNumberSequence: '01'
                receiptLines:
                  MERCHANT:
                    - format:
                        - BOLD
                      type: TEXT
                      value: John's Shop
                  CUSTOMER:
                    - format:
                        - BOLD
                      type: TEXT
                      value: John's Shop
                requestId: d19912ad-11a3-4af3-86e0-d6eb2ebea63c
                transactionId: '1234567'
                transactionNumber: '0012'
                transactionResult: SUCCESSFUL
                transactionTime: '2019-03-04T16:12:00'
                transactionType: SALE
        '401':
          description: Request headers must include authorization credentials.
        '404':
          description: Terminal is unavailable or no data is available for the terminal.
        '500':
          description: An internal error occurred within the API.
    delete:
      tags:
        - Transactions
      summary: Cancel Transaction
      description: Attempts to cancel the transaction identified by the given requestId.
      parameters:
        - $ref: '#/components/parameters/tpi'
        - $ref: '#/components/parameters/requestId'
      responses:
        '204':
          description: The transaction associated with the requestId has been cancelled.
        '401':
          description: Request headers must include authorization credentials.
        '404':
          description: The specified requestId was not found.
        '422':
          description: The transaction could not be cancelled.
        '500':
          description: An internal error occurred within the API.
  /pac/terminals/{tpi}/reports:
    post:
      tags:
        - Reports
      summary: Request Report
      description: >-
        Initiates a report on the terminal identified by the given terminal
        identifier.
      parameters:
        - $ref: '#/components/parameters/tpi'
      requestBody:
        required: true
        content:
          application/connect.v1+json:
            schema:
              $ref: '#/components/schemas/RequestReportRequest'
            example:
              reportType: END_OF_DAY
      responses:
        '201':
          description: >-
            Report was successfully initiated. The response includes the report
            requestId and an endpoint location for retrieving additional
            details.
          content:
            application/connect.v1+json:
              schema:
                $ref: '#/components/schemas/TransactionAcceptedResponse'
              example:
                requestId: d19912ad-11a3-4af3-86e0-d6eb2ebea63c
                location: ''
        '401':
          description: Request headers must include authorization credentials.
        '422':
          description: The JSON received was invalid.
        '500':
          description: An internal error occurred within the API.
  /pac/terminals/{tpi}/reports/{requestId}:
    get:
      tags:
        - Reports
      summary: Retrieve Report
      description: Retrieves data for the report identified by the given requestId.
      parameters:
        - $ref: '#/components/parameters/tpi'
        - $ref: '#/components/parameters/requestId'
      responses:
        '200':
          description: >-
            Report details have been returned successfully. Properties marked
            with an * are always included in the response. Additional properties
            are only included after a report has completed (e.g. when the most
            recent notification is "REPORT_FINISHED"), though their values may
            be empty.
          content:
            application/connect.v1+json:
              schema:
                $ref: '#/components/schemas/ReportStatusResponse'
        '401':
          description: Request headers must include authorization credentials.
        '404':
          description: Terminal is unavailable or no data is available for the terminal.
        '500':
          description: An internal error occurred within the API.
