openapi: 3.0.3
info:
  title: Classic Models API — Payments domain
  version: 4.7.0
  description: 'Customer payments and their allocation. Payments domain subset of the shared classic-models-api backend, as exposed by the payments domain''s Kong gateway. Paths and server below are the gateway''s, not the backend''s: the gateway rewrites /payments/v1/... onto /classic-models/api/v1/... upstream. Requires a bearer token from the classic-models realm.'
paths:
  /payments/v1/payments/:
    get:
      operationId: list_payments
      description: Retrieve a paginated list of all customer payment records with amounts and dates.
      summary: List all payments
      parameters:
        - name: page
          required: false
          in: query
          description: A page number within the paginated result set.
          schema:
            type: integer
        - name: page_size
          required: false
          in: query
          description: Number of results to return per page.
          schema:
            type: integer
      tags:
        - Payments
      security:
        - ApiKeyAuth: []
        - JWTAuth: []
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedPaymentList'
          description: ""
    post:
      operationId: create_payment
      description: Record a new customer payment with check number, amount, and payment date.
      summary: Create a new payment
      tags:
        - Payments
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PaymentRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PaymentRequest'
        required: true
      security:
        - ApiKeyAuth: []
        - JWTAuth: []
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
          description: ""
  /payments/v1/payments/{customernumber}/{checknumber}/:
    delete:
      operationId: delete_payment
      description: Remove a payment record from the system.
      summary: Delete a payment
      parameters:
        - in: path
          name: checknumber
          schema:
            type: string
          description: The check number
          required: true
        - in: path
          name: customernumber
          schema:
            type: integer
          description: The customer number
          required: true
      tags:
        - Payments
      security:
        - ApiKeyAuth: []
        - JWTAuth: []
      responses:
        "204":
          description: No response body
    patch:
      operationId: patch_payment
      description: Update specific fields of an existing payment record.
      summary: Partially update a payment
      parameters:
        - in: path
          name: checknumber
          schema:
            type: string
          description: The check number
          required: true
        - in: path
          name: customernumber
          schema:
            type: integer
          description: The customer number
          required: true
      tags:
        - Payments
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchedPaymentRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PatchedPaymentRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PatchedPaymentRequest'
      security:
        - ApiKeyAuth: []
        - JWTAuth: []
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
          description: ""
    put:
      operationId: update_payment
      description: Update all fields of an existing payment record.
      summary: Update a payment
      parameters:
        - in: path
          name: checknumber
          schema:
            type: string
          description: The check number
          required: true
        - in: path
          name: customernumber
          schema:
            type: integer
          description: The customer number
          required: true
      tags:
        - Payments
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PaymentRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PaymentRequest'
        required: true
      security:
        - ApiKeyAuth: []
        - JWTAuth: []
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
          description: ""
    get:
      operationId: get_payment
      description: Retrieve detailed information about a specific payment by customer number and check number.
      summary: Get a specific payment
      parameters:
        - in: path
          name: checknumber
          schema:
            type: string
          description: The check number
          required: true
        - in: path
          name: customernumber
          schema:
            type: integer
          description: The customer number
          required: true
      tags:
        - Payments
      security:
        - ApiKeyAuth: []
        - JWTAuth: []
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
          description: ""
components:
  schemas:
    PaginatedPaymentList:
      type: object
      properties:
        count:
          type: integer
          example: 123
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=4
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=2
        results:
          type: array
          items:
            $ref: '#/components/schemas/Payment'
    PatchedPaymentRequest:
      type: object
      description: Customer payment records
      properties:
        checknumber:
          type: string
          minLength: 1
          maxLength: 50
        paymentdate:
          type: string
          format: date
        amount:
          type: string
          format: decimal
          pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
        customernumber:
          type: integer
          maximum: 2147483647
          minimum: -2147483648
    Payment:
      type: object
      description: Customer payment records
      properties:
        id:
          type: integer
          readOnly: true
        checknumber:
          type: string
          maxLength: 50
        paymentdate:
          type: string
          format: date
        amount:
          type: string
          format: decimal
          pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
        customernumber:
          type: integer
          maximum: 2147483647
          minimum: -2147483648
      required:
        - amount
        - checknumber
        - customernumber
        - id
        - paymentdate
    PaymentRequest:
      type: object
      description: Customer payment records
      properties:
        checknumber:
          type: string
          minLength: 1
          maxLength: 50
        paymentdate:
          type: string
          format: date
        amount:
          type: string
          format: decimal
          pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
        customernumber:
          type: integer
          maximum: 2147483647
          minimum: -2147483648
      required:
        - amount
        - checknumber
        - customernumber
        - paymentdate
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key authentication using X-API-Key header
    JWTAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
servers:
  - url: https://payments-dev.sttlab.local
    description: Payments gateway (dev)