openapi: 3.0.3
info:
  title: Pay at Counter REST API
  version: '2'
  description: Documentation for the yetipay Pay at Counter REST API.
servers:
  - url: https://connect.yeti.host
security:
  - connectBasicAuth: []
components:
  securitySchemes:
    connectBasicAuth:
      type: http
      scheme: basic
  schemas:
    Terminal:
      type: object
      properties:
        tid:
          type: string
          example: '12345678'
        status:
          type: string
          enum:
            - AVAILABLE
            - BUSY
        currency:
          type: string
          enum:
            - GBP
            - EUR
        location:
          type: string
    StartTransactionRequest:
      type: object
      required:
        - transactionType
      properties:
        transactionType:
          type: string
          enum:
            - SALE
            - REFUND
            - DUPLICATE
            - PRE_AUTH
            - COMPLETION
            - ACCOUNT_VERIFICATION
          description: Type of the transaction.
        currency:
          type: string
          enum:
            - GBP
            - EUR
          description: >-
            Currency for the request. Uses the textual representation from ISO
            4217.
        amount:
          type: integer
          minimum: 1
          maximum: 99999999
          description: >-
            Accepted for all transactions except duplicates. Base amount for the
            transaction (in pence).
        amountCashback:
          type: integer
          minimum: 0
          maximum: 10000
          description: >-
            Only accepted for sale transactions. Amount of cashback to attempt
            to include in this transaction (in pence).
        cardholderNotPresent:
          type: boolean
          description: >-
            Indicates whether this transaction should be completed as CNP (e.g.
            manual entry of card details). If set, the PDQ will skip the present
            card screen and immediately prompt for manual entry.
        authCode:
          type: string
          description: >-
            Required for completion transactions. Should contain the
            authorization code of the first pre-auth transaction.
        amountPreAuthorisedTotal:
          type: integer
          minimum: 1
          maximum: 99999999
          description: >-
            Required for completion transactions. Should contain the sum of all
            pre-auth transactions performed on a customer's card.
    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
            - REPLACE_PAPER
        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
            - PRE_AUTH
            - COMPLETION
            - ACCOUNT_VERIFICATION
        userMessage:
          type: string
    RequestReportRequest:
      type: object
      required:
        - reportType
      properties:
        reportType:
          type: string
          enum:
            - END_OF_DAY
            - BANKING
            - X_BALANCE
            - Z_BALANCE
          description: The type of 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
        tid:
          type: string
        requestId:
          type: string
          format: uuid
        location:
          type: string
        notifications:
          type: array
          items:
            type: string
    ErrorResponse:
      type: object
      properties:
        userMessage:
          type: string
          example: >-
            This is an example error message. The string here should be
            displayed to the user.
  parameters:
    tid:
      name: tid
      in: path
      required: true
      schema:
        type: string
      description: Unique identifier of the terminal to use.
    requestId:
      name: requestId
      in: path
      required: true
      schema:
        type: string
      description: Id (a UUID assigned to a terminal request) for the request to use.
  responses:
    Unauthorized:
      description: |-
        Request could not be authorized:
        - The authorization credentials provided were incorrect
        - Authorization credentials were not included in the request headers
      content:
        application/connect.v2+json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unprocessable:
      description: >-
        Request could not be processed:

        - Missing Software-House-Id or Installer-Id header

        - The JSON received was invalid (e.g. missing field, invalid value in
        field)
      content:
        application/connect.v2+json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalError:
      description: >-
        An internal error occurred within the API. The request should be
        retried, and if the problem persists, support should be contacted.
    NotFound:
      description: |-
        Terminal could not be found:
        - No data is available for the terminal
        - Terminal is unavailable
      content:
        application/connect.v2+json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
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 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: 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.v2+json:
              schema:
                type: object
                properties:
                  terminals:
                    type: array
                    items:
                      $ref: '#/components/schemas/Terminal'
              example:
                terminals:
                  - tid: '12345678'
                    status: AVAILABLE
                    currency: GBP
                    location: ''
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '500':
          $ref: '#/components/responses/InternalError'
  /pac/terminals/{tid}:
    get:
      tags:
        - Terminals
      summary: Get Terminal by ID
      description: Retrieves details for a specific terminal.
      parameters:
        - $ref: '#/components/parameters/tid'
      responses:
        '200':
          description: Information about the requested terminal is returned
          content:
            application/connect.v2+json:
              schema:
                $ref: '#/components/schemas/Terminal'
              example:
                tid: '12345678'
                status: AVAILABLE
                currency: GBP
                location: ''
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '500':
          $ref: '#/components/responses/InternalError'
  /pac/terminals/{tid}/transactions:
    post:
      tags:
        - Transactions
      summary: Start Transaction
      description: >-
        Initiates a transaction on the terminal identified by the given terminal
        identifier.
      parameters:
        - $ref: '#/components/parameters/tid'
      requestBody:
        required: true
        content:
          application/connect.v2+json:
            schema:
              $ref: '#/components/schemas/StartTransactionRequest'
            examples:
              Sale:
                value:
                  transactionType: SALE
                  amount: 100
                  amountCashback: 50
                  currency: GBP
                  cardholderNotPresent: true
              Refund:
                value:
                  transactionType: REFUND
                  amount: 100
                  currency: GBP
              Duplicate:
                value:
                  transactionType: DUPLICATE
              AccountVerification:
                value:
                  transactionType: ACCOUNT_VERIFICATION
                  currency: GBP
              PreAuth:
                value:
                  transactionType: PRE_AUTH
                  amount: 100
                  currency: GBP
              Completion:
                value:
                  transactionType: COMPLETION
                  amount: 100
                  currency: GBP
                  authCode: 78YT6RS0
                  amountPreAuthorisedTotal: 100
      responses:
        '201':
          description: >-
            Transaction request has been accepted. Polling should begin on the
            returned requestId to determine the progress and result of the
            transaction.
          content:
            application/connect.v2+json:
              schema:
                $ref: '#/components/schemas/TransactionAcceptedResponse'
              example:
                requestId: d19912ad-11a3-4af3-86e0-d6eb2ebea63c
                location: ''
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          description: >-
            Request could not be processed:

            - Missing Software-House-Id or Installer-Id header

            - Terminal is currently busy processing another request

            - The JSON received was invalid (e.g. missing field, invalid value
            in field)
          content:
            application/connect.v2+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalError'
  /pac/terminals/{tid}/transactions/{requestId}:
    get:
      tags:
        - Transactions
      summary: Get Transaction Status
      description: Retrieves data for the transaction identified by the given requestId.
      parameters:
        - $ref: '#/components/parameters/tid'
        - $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.v2+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
                  - REPLACE_PAPER
                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
                userMessage: >-
                  Signature check not actioned before timeout. When required,
                  signatures must be verified within 80 seconds.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: |-
            Terminal or transaction could not be found:
            - Transaction requestId was not found
            - No data is available for the terminal
            - Terminal is unavailable
          content:
            application/connect.v2+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      tags:
        - Transactions
      summary: Cancel Transaction
      description: Attempts to cancel the transaction identified by the given requestId.
      parameters:
        - $ref: '#/components/parameters/tid'
        - $ref: '#/components/parameters/requestId'
      responses:
        '202':
          description: >-
            Request to attempt cancellation of the transaction has been
            accepted. The outcome of this request should be determined from
            standard transaction polling.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: |-
            Terminal or transaction could not be found:
            - Transaction requestId was not found
            - No data is available for the terminal
            - Terminal is unavailable
          content:
            application/connect.v2+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '500':
          $ref: '#/components/responses/InternalError'
  /pac/terminals/{tid}/reports:
    post:
      tags:
        - Reports
      summary: Request Report
      description: >-
        Initiates a report on the terminal identified by the given terminal
        identifier.
      parameters:
        - $ref: '#/components/parameters/tid'
      requestBody:
        required: true
        content:
          application/connect.v2+json:
            schema:
              $ref: '#/components/schemas/RequestReportRequest'
            example:
              reportType: END_OF_DAY
      responses:
        '201':
          description: >-
            Report request has been accepted. Polling should begin on the
            returned requestId to determine the progress and result of the
            report.
          content:
            application/connect.v2+json:
              schema:
                $ref: '#/components/schemas/TransactionAcceptedResponse'
              example:
                requestId: d19912ad-11a3-4af3-86e0-d6eb2ebea63c
                location: ''
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          description: >-
            Request could not be processed:

            - Missing Software-House-Id or Installer-Id header

            - Terminal is currently busy processing another request

            - The JSON received was invalid (e.g. missing field, invalid value
            in field)
          content:
            application/connect.v2+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalError'
  /pac/terminals/{tid}/reports/{requestId}:
    get:
      tags:
        - Reports
      summary: Retrieve Report
      description: Retrieves data for the report identified by the given requestId.
      parameters:
        - $ref: '#/components/parameters/tid'
        - $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.v2+json:
              schema:
                $ref: '#/components/schemas/ReportStatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: |-
            Terminal or report could not be found:
            - Report requestId was not found
            - No data is available for the terminal
            - Terminal is unavailable
          content:
            application/connect.v2+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '500':
          $ref: '#/components/responses/InternalError'
