diff --git a/openapi.yaml b/openapi.yaml
new file mode 100644
index 0000000..8197210
--- /dev/null
+++ b/openapi.yaml
@@ -0,0 +1,305 @@
+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)