openapi: 3.0.0
info:
  title: Paystar API
  version: 1.0.0
paths:
  /integrations/checkout/session:
    get:
      operationId: getPaymentSessionByClientReference
      summary: Get payment session details by client provided reference
      parameters:
        - in: query
          name: clientReference
          required: true
          schema:
            type: string
          description: Client provided reference for the payment session
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiClientPaymentSessionDetailResponse'
  /integrations/checkout/session/{sessionIdentifier}:
    get:
      operationId: getPaymentSessionByIdentifier
      summary: Get payment session identifier
      parameters:
        - in: path
          name: sessionIdentifier
          required: true
          schema:
            type: string
          description: Unique session identifier
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiClientPaymentSessionDetailResponse'
  /integrations/sync/query/payments:
    get:
      summary: Query Payments
      description: Query Payments
      operationId: query-payments
      parameters:
        - name: StartDate
          in: query
          schema:
            type: string
        - name: EndDate
          in: query
          schema:
            type: string
        - name: ReferenceNumber
          in: query
          schema:
            type: string
        - name: Page
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryPaymentsResponse'
  /integrations/sync/query/line-items:
    get:
      summary: Query Line Items
      description: Query Line Items
      operationId: query-line-items
      parameters:
        - name: StartDate
          in: query
          schema:
            type: string
        - name: EndDate
          in: query
          schema:
            type: string
        - name: ReferenceNumber
          in: query
          schema:
            type: string
        - name: Page
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryLineItemsResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Paystar-Api-Key
  schemas:
    ApiClientPaymentSessionDetailResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ApiClientPaymentSessionDetailDto'
        hasErrors:
          type: boolean
        errors:
          type: array
          items:
            type: object
    ApiClientPaymentSessionDetailDto:
      type: object
      properties:
        paymentSession:
          $ref: >-
            #/components/schemas/ApiClientPaymentSessionDetailDto_PaymentSessionDto
        paymentFields:
          type: object
          additionalProperties:
            type: string
        payment:
          $ref: '#/components/schemas/ApiClientPaymentSessionDetailDto_PaymentDto'
        paymentSource:
          $ref: >-
            #/components/schemas/ApiClientPaymentSessionDetailDto_PaymentSourceDto
        lineItems:
          type: array
          items:
            $ref: '#/components/schemas/ApiClientPaymentSessionDetailDto_LineItemDto'
        canProcessSession:
          type: boolean
          readOnly: true
    ApiClientPaymentSessionDetailDto_LineItemDto:
      type: object
      properties:
        lineItemType:
          type: string
        description:
          type: string
        priceMinor:
          format: int32
          type: integer
        accountNumber:
          type: string
        subAccountNumber:
          type: string
        productSku:
          type: string
        productName:
          type: string
    ApiClientPaymentSessionDetailDto_PaymentDto:
      type: object
      properties:
        status:
          type: string
        paymentDate:
          format: date-time
          description: |
            `yyyy-mm-ddThh:mm:ssz`\
            `yyyy-mm-ddThh:mm:ss±hh:mm`
          type: string
        amountMinor:
          format: int32
          type: integer
        serviceFeeAmountMinor:
          format: int32
          type: integer
        paymentDescriptor:
          type: string
        referenceNumber:
          type: string
        authCode:
          type: string
        gatewayResponseDescription:
          type: string
    ApiClientPaymentSessionDetailDto_PaymentSessionDto:
      type: object
      properties:
        identifier:
          format: uuid
          type: string
        createdDateUtc:
          format: date-time
          description: |
            `yyyy-mm-ddThh:mm:ssz`\
            `yyyy-mm-ddThh:mm:ss±hh:mm`
          type: string
        businessUnitSlug:
          type: string
        channel:
          type: string
        status:
          type: string
        subtotal:
          format: int32
          type: integer
        serviceFeeCalculation:
          $ref: '#/components/schemas/ServiceFeeCalculationDto'
    ApiClientPaymentSessionDetailDto_PaymentSourceDto:
      type: object
      properties:
        paymentSourceType:
          type: string
        accountHolderName:
          type: string
        accountType:
          type: string
        accountNumberLast4:
          type: string
    ServiceFeeCalculationDto:
      type: object
      properties:
        tier:
          $ref: '#/components/schemas/ServiceFeeTierGetDto'
        amount:
          format: int32
          type: integer
    ServiceFeeTierGetDto:
      type: object
      properties:
        paymentChannel:
          type: string
        paymentSourceType:
          type: string
        startRange:
          format: int32
          type: integer
        endRange:
          format: int32
          type: integer
        flatFee:
          format: int32
          type: integer
        percentageFee:
          format: double
          type: number
        id:
          format: int32
          type: integer
    QueryPaymentsResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            page:
              type: integer
              format: int64
            pageSize:
              type: integer
              format: int64
            pageCount:
              type: integer
              format: int64
            totalItemCount:
              type: integer
              format: int64
            items:
              type: array
              items:
                type: object
                properties:
                  slug:
                    type: string
                  paymentReferenceNumber:
                    type: string
                  sessionIdentifier:
                    type: string
                  lineItemType:
                    type: string
                  description:
                    type: string
                  priceMinor:
                    type: integer
                    format: int32
                  accountNumber:
                    type: string
                  subAccountNumber:
                    type: string
                  productSku:
                    type: string
                  productName:
                    type: string
                  amountMinor:
                    type: integer
                    format: int64
                  serviceFeeAmountMinor:
                    type: integer
                    format: int64
                  status:
                    type: string
                  paymentDate:
                    type: string
                    format: date-time
        hasErrors:
          type: boolean
        errors:
          type: array
          items:
            type: object
    QueryLineItemsResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            page:
              type: integer
              format: int64
            pageSize:
              type: integer
              format: int64
            pageCount:
              type: integer
              format: int64
            totalItemCount:
              type: integer
              format: int64
            items:
              type: array
              items:
                type: object
                properties:
                  slug:
                    type: string
                  paymentReferenceNumber:
                    type: string
                  sessionIdentifier:
                    type: string
                  lineItemType:
                    type: string
                  description:
                    type: string
                  priceMinor:
                    type: integer
                    format: int32
                  accountNumber:
                    type: string
                  subAccountNumber:
                    type: string
                  productSku:
                    type: string
                  productName:
                    type: string
        hasErrors:
          type: boolean
        errors:
          type: array
          items:
            type: object
servers:
  - url: https://dev-gateway.paystar.io
security:
  - ApiKeyAuth: []
