> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paywise.de/llms.txt
> Use this file to discover all available pages before exploring further.

# List reported payments

> All payments of this invoice, newest value date first (unpaginated).

<Warning>
  **Draft documentation — API not yet rolled out.** This endpoint describes the preview contract and may change before release. Sandbox access is provided separately. See [access and limitations](/api-docs/mahnservice-api/introduction).
</Warning>


## OpenAPI

````yaml api-docs/mahnservice-api/openapi.json GET /mahnservice/v1/invoices/{uuid}/payments/
openapi: 3.0.3
info:
  title: paywise Mahnservice API
  version: v1
  description: >-
    Public REST API for the paywise Mahnservice (pre-collection dunning), an
    alternative input path to the bookkeeping integrations (Lexware Office,
    sevDesk) and the CSV import.


    Authentication uses a Bearer token (the same token works for the Inkasso
    API). Each token is bound to a company and a legacy access mode: `test` or
    `production`. Access mode is a data-isolation lane, not the API environment:
    modern credentials use `production` in both production and sandbox. Read
    `/info/`'s `environment` (`production` or `sandbox`) to identify the
    environment serving your request.


    Resources: token introspection (`/info/`), debtors (create/list/get), and
    the invoice lifecycle -- submit (held), upload the invoice PDF (multipart or
    base64; scanned asynchronously, poll the document `status`), release for
    dunning, report payments, cancel / write off, and read the dunning state
    (`dunning_state`, the dunning flow and the sent dunnings with their fees),
    pause and resume the dunning, and read the dunning-flow configuration
    (`/dunning-flows/`). Webhooks notify you about `invoice.created`,
    `invoice.paid`, `invoice.cancelled`, `invoice.written_off`,
    `dunning.level_advanced` and `dunning.handed_to_collection`. Test-mode
    invoices are visible everywhere but never dunned, and their events only
    reach test-mode endpoints.


    Contract: requests are JSON only (documents may also be multipart); unknown
    or read-only body fields and unknown query parameters are rejected with
    `400`; list pages take `limit` (1-100, default 10) and `offset`. Errors are
    English and machine-readable: every error body is `{detail, code[, errors]}`
    -- branch on `code` (`validation_error` with per-field `errors`,
    `not_authenticated`, `permission_denied` -- the token lacks the scope,
    `subscription_required` -- no active Mahnservice subscription (writes other
    than payment reporting), `company_locked` -- the account is locked by
    paywise (every write), `not_found`, `unsupported_media_type`,
    `request_too_large`, `throttled`, `unexpected_body`, and the documented
    `409` codes). A repeat submission of an invoice number that was cancelled,
    written off or archived is a `409` (`invoice_cancelled` /
    `invoice_written_off` / `invoice_archived`), not a replay. `HEAD` mirrors
    `GET` and never writes. Every response carries `X-Paywise-Request-Id`,
    `X-Paywise-Environment` and `Cache-Control: private, no-store`. Token scopes
    apply: `mahnservice:debtors:read` / `:write` and `mahnservice:invoices:read`
    / `:write` (a `:write` grant includes `:read`; keys minted with the full `*`
    grant have everything). Rate limits: 600 requests per minute per key and per
    company, shared with the Case Management API, plus per-operation windows of
    600 reads or 120 writes per minute; a `429` carries `Retry-After`.
servers:
  - url: https://api.paywise.de
    description: Production environment
security: []
tags:
  - name: Info
    description: The authenticated credential and its context.
  - name: Debtors
    description: Debtors invoices are addressed to.
  - name: Invoices
    description: Held invoices, their release, payments and documents.
  - name: Dunning flows
    description: Dunning flow configurations referenced by invoices.
externalDocs:
  url: https://docs.paywise.de/api-docs/mahnservice-api/introduction
paths:
  /mahnservice/v1/invoices/{uuid}/payments/:
    get:
      tags:
        - Invoices
      summary: List reported payments
      description: All payments of this invoice, newest value date first (unpaginated).
      operationId: list-invoice-payments
      parameters:
        - in: path
          name: uuid
          schema:
            type: string
            format: uuid
          required: true
          description: UUID of the invoice in this request.
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Payment'
          description: ''
          headers:
            X-Paywise-Request-Id:
              description: >-
                Fresh server-assigned correlation id for this response.
                Caller-provided request ids are ignored.
              schema:
                type: string
                format: uuid
            X-Paywise-Environment:
              description: Environment that produced the response.
              schema:
                enum:
                  - production
                  - sandbox
                type: string
            Cache-Control:
              description: >-
                Cacheability directive. Authenticated responses use `private,
                no-store`; the legal-form catalog may use `private,
                max-age=86400`.
              schema:
                type: string
        '401':
          description: Standard error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Paywise-Request-Id:
              description: >-
                Fresh server-assigned correlation id for this response.
                Caller-provided request ids are ignored.
              schema:
                type: string
                format: uuid
            X-Paywise-Environment:
              description: Environment that produced the response.
              schema:
                enum:
                  - production
                  - sandbox
                type: string
            Cache-Control:
              description: >-
                Cacheability directive. Authenticated responses use `private,
                no-store`; the legal-form catalog may use `private,
                max-age=86400`.
              schema:
                type: string
        '403':
          description: Standard error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Paywise-Request-Id:
              description: >-
                Fresh server-assigned correlation id for this response.
                Caller-provided request ids are ignored.
              schema:
                type: string
                format: uuid
            X-Paywise-Environment:
              description: Environment that produced the response.
              schema:
                enum:
                  - production
                  - sandbox
                type: string
            Cache-Control:
              description: >-
                Cacheability directive. Authenticated responses use `private,
                no-store`; the legal-form catalog may use `private,
                max-age=86400`.
              schema:
                type: string
        '404':
          description: Standard error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Paywise-Request-Id:
              description: >-
                Fresh server-assigned correlation id for this response.
                Caller-provided request ids are ignored.
              schema:
                type: string
                format: uuid
            X-Paywise-Environment:
              description: Environment that produced the response.
              schema:
                enum:
                  - production
                  - sandbox
                type: string
            Cache-Control:
              description: >-
                Cacheability directive. Authenticated responses use `private,
                no-store`; the legal-form catalog may use `private,
                max-age=86400`.
              schema:
                type: string
        '429':
          description: Standard error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Paywise-Request-Id:
              description: >-
                Fresh server-assigned correlation id for this response.
                Caller-provided request ids are ignored.
              schema:
                type: string
                format: uuid
            X-Paywise-Environment:
              description: Environment that produced the response.
              schema:
                enum:
                  - production
                  - sandbox
                type: string
            Cache-Control:
              description: >-
                Cacheability directive. Authenticated responses use `private,
                no-store`; the legal-form catalog may use `private,
                max-age=86400`.
              schema:
                type: string
            Retry-After:
              description: Integer seconds to wait before retrying a throttled request.
              schema:
                type: integer
                minimum: 1
        '500':
          description: Standard error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Paywise-Request-Id:
              description: >-
                Fresh server-assigned correlation id for this response.
                Caller-provided request ids are ignored.
              schema:
                type: string
                format: uuid
            X-Paywise-Environment:
              description: Environment that produced the response.
              schema:
                enum:
                  - production
                  - sandbox
                type: string
            Cache-Control:
              description: >-
                Cacheability directive. Authenticated responses use `private,
                no-store`; the legal-form catalog may use `private,
                max-age=86400`.
              schema:
                type: string
      security:
        - tokenAuth: []
components:
  schemas:
    Payment:
      type: object
      description: |-
        A payment reported against an invoice. A partial payment reduces the
        balance while dunning continues over the full amount; once the reported
        total covers the amount, the invoice is marked paid and dunning stops.
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        amount:
          type: string
          format: decimal
          pattern: ^[0-9]{1,10}(?:\.[0-9]{1,2})?$
          description: >-
            Amount received toward the invoice in its currency, expressed in
            major units and greater than zero. Partial payments reduce balance;
            covering the full invoice stops dunning unless it has already been
            handed to debt collection.
        value_date:
          type: string
          format: date
          description: >-
            Date the payment was received; must not be in the future. Together
            with amount and reference, it identifies an identical repeated
            payment report.
        reference:
          type: string
          nullable: true
          maxLength: 255
          description: >-
            Optional payment reference. Omitted, blank and null references are
            treated alike. A repeat with the same invoice, amount, value_date
            and nonempty reference (compared case-insensitively) returns the
            existing payment (200). An identical unreferenced payment returns
            409 duplicate_payment; use a distinct reference for a genuine second
            payment.
        created:
          type: string
          format: date-time
          readOnly: true
      required:
        - amount
        - created
        - id
        - value_date
    Error:
      type: object
      properties:
        detail:
          type: string
          description: Short human-readable summary of the error.
        code:
          type: string
          description: Machine-readable error category.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorItem'
          description: Field-level validation errors, when applicable.
      required:
        - detail
        - code
      additionalProperties: false
    ErrorItem:
      type: object
      properties:
        field:
          type: string
          nullable: true
          description: >-
            Path to the field that caused the error, using dots for objects and
            brackets for list indexes, for example `claims[0].amount`; null for
            an error without a field path.
        code:
          type: string
          description: Machine-readable field error code.
        message:
          type: string
          description: Human-readable explanation of the field error.
      required:
        - field
        - code
        - message
      additionalProperties: false
  securitySchemes:
    tokenAuth:
      type: http
      scheme: bearer

````