> ## 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.

# Create mandate payment

> Immutable client payment reports under a main mandate or subcase.



## OpenAPI

````yaml /api-docs/case-management-api/openapi.json post /v2/mandates/{mandate_id}/payments/
openapi: 3.0.3
info:
  description: >-
    Submit orders and manage their complete lifecycle through the current API at
    the `/v2/` HTTP path.
  title: paywise Case Management API
  version: current
servers:
  - description: Production environment
    url: https://api.paywise.de
  - description: Sandbox environment
    url: https://api-sandbox.paywise.de
security: []
tags:
  - description: Submit orders and manage them until acceptance.
    name: Orders
  - description: Stable claim resources and their current relationships.
    name: Claims
  - description: 'Accepted cases: state, published history and documents.'
    name: Mandates
  - description: Debtor master data reused across orders.
    name: Debtors
  - description: Payments reported by you and booked by paywise.
    name: Payments
  - description: Files attached to claims and other resources.
    name: Documents
  - description: Collective statements (Sammelabrechnungen).
    name: Statements
  - description: Per-case statements (Aktenabrechnungen).
    name: Single mandate statements
  - description: Webhook endpoints and their signing secrets.
    name: Webhooks
  - description: Delivery log and redelivery of webhook events.
    name: Webhook deliveries
  - description: Ordered feed of the events webhooks deliver.
    name: Events
  - description: Reference catalog of legal forms.
    name: Legal forms
  - description: The authenticated credential and its context.
    name: Info
  - description: Rate-limit headroom of the credential.
    name: Usage
  - description: Availability of the API.
    name: Health
externalDocs:
  url: https://docs.paywise.de/api-docs/case-management-api/introduction
paths:
  /v2/mandates/{mandate_id}/payments/:
    post:
      tags:
        - Mandates
      summary: Create mandate payment
      description: Immutable client payment reports under a main mandate or subcase.
      operationId: create-mandate-payment
      parameters:
        - description: >-
            Required when a Partner key calls the Case Management API; rejected
            for direct Case keys. Contains the entitled paywise company UUID.
          in: header
          name: X-On-Behalf-Of-Company
          schema:
            format: uuid
            type: string
        - description: UUID of the parent accepted case in this request.
          in: path
          name: mandate_id
          required: true
          schema:
            format: uuid
            type: string
        - description: >-
            Required client-supplied command key scoped to the selected Case
            company or Partner owner, method, operation and path. An exact retry
            replays the original response while it is retained, including after
            credential rotation or replacement. Current permissions are
            required.
          in: header
          name: Idempotency-Key
          required: true
          schema:
            maxLength: 255
            type: string
      requestBody:
        content:
          application/json:
            examples:
              payment-report:
                value:
                  amount:
                    currency: EUR
                    value: '50.00'
                  metadata:
                    - type: transaction:reference
                      value: BANK-TRANSACTION-99812
                  value_date: '2026-07-17'
                  your_reference: BANK-TRANSACTION-99812
            schema:
              $ref: '#/components/schemas/PaymentWriteRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRead'
          description: ''
          headers:
            Cache-Control:
              description: >-
                Cacheability directive. Authenticated responses use `private,
                no-store`; the legal-form catalog may use `private,
                max-age=86400`.
              schema:
                type: string
            X-Paywise-Environment:
              description: Environment that produced the response.
              schema:
                enum:
                  - production
                  - sandbox
                type: string
            X-Paywise-Request-Id:
              description: >-
                Fresh server-assigned correlation id for this response.
                Caller-provided request ids are ignored.
              schema:
                format: uuid
                type: string
        '400':
          content:
            application/json:
              examples:
                validation-error:
                  value:
                    code: validation_error
                    detail: The request contains invalid data.
                    errors:
                      - code: invalid
                        field: claims[0].due_date
                        message: Due date must not precede the document date.
              schema:
                $ref: '#/components/schemas/Error'
          description: Standard error response.
          headers:
            Cache-Control:
              description: >-
                Cacheability directive. Authenticated responses use `private,
                no-store`; the legal-form catalog may use `private,
                max-age=86400`.
              schema:
                type: string
            X-Paywise-Environment:
              description: Environment that produced the response.
              schema:
                enum:
                  - production
                  - sandbox
                type: string
            X-Paywise-Request-Id:
              description: >-
                Fresh server-assigned correlation id for this response.
                Caller-provided request ids are ignored.
              schema:
                format: uuid
                type: string
        '401':
          content:
            application/json:
              examples:
                authentication-error:
                  value:
                    code: not_authenticated
                    detail: Authentication credentials were not provided.
              schema:
                $ref: '#/components/schemas/Error'
          description: Standard error response.
          headers:
            Cache-Control:
              description: >-
                Cacheability directive. Authenticated responses use `private,
                no-store`; the legal-form catalog may use `private,
                max-age=86400`.
              schema:
                type: string
            X-Paywise-Environment:
              description: Environment that produced the response.
              schema:
                enum:
                  - production
                  - sandbox
                type: string
            X-Paywise-Request-Id:
              description: >-
                Fresh server-assigned correlation id for this response.
                Caller-provided request ids are ignored.
              schema:
                format: uuid
                type: string
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Standard error response.
          headers:
            Cache-Control:
              description: >-
                Cacheability directive. Authenticated responses use `private,
                no-store`; the legal-form catalog may use `private,
                max-age=86400`.
              schema:
                type: string
            X-Paywise-Environment:
              description: Environment that produced the response.
              schema:
                enum:
                  - production
                  - sandbox
                type: string
            X-Paywise-Request-Id:
              description: >-
                Fresh server-assigned correlation id for this response.
                Caller-provided request ids are ignored.
              schema:
                format: uuid
                type: string
        '404':
          content:
            application/json:
              examples:
                not-found-error:
                  value:
                    code: not_found
                    detail: The requested resource was not found.
              schema:
                $ref: '#/components/schemas/Error'
          description: Standard error response.
          headers:
            Cache-Control:
              description: >-
                Cacheability directive. Authenticated responses use `private,
                no-store`; the legal-form catalog may use `private,
                max-age=86400`.
              schema:
                type: string
            X-Paywise-Environment:
              description: Environment that produced the response.
              schema:
                enum:
                  - production
                  - sandbox
                type: string
            X-Paywise-Request-Id:
              description: >-
                Fresh server-assigned correlation id for this response.
                Caller-provided request ids are ignored.
              schema:
                format: uuid
                type: string
        '409':
          content:
            application/json:
              examples:
                conflict-error:
                  value:
                    code: conflict
                    detail: The resource changed state and cannot accept this command.
              schema:
                $ref: '#/components/schemas/Error'
          description: Standard error response.
          headers:
            Cache-Control:
              description: >-
                Cacheability directive. Authenticated responses use `private,
                no-store`; the legal-form catalog may use `private,
                max-age=86400`.
              schema:
                type: string
            X-Paywise-Environment:
              description: Environment that produced the response.
              schema:
                enum:
                  - production
                  - sandbox
                type: string
            X-Paywise-Request-Id:
              description: >-
                Fresh server-assigned correlation id for this response.
                Caller-provided request ids are ignored.
              schema:
                format: uuid
                type: string
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Standard error response.
          headers:
            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:
                minimum: 1
                type: integer
            X-Paywise-Environment:
              description: Environment that produced the response.
              schema:
                enum:
                  - production
                  - sandbox
                type: string
            X-Paywise-Request-Id:
              description: >-
                Fresh server-assigned correlation id for this response.
                Caller-provided request ids are ignored.
              schema:
                format: uuid
                type: string
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Standard error response.
          headers:
            Cache-Control:
              description: >-
                Cacheability directive. Authenticated responses use `private,
                no-store`; the legal-form catalog may use `private,
                max-age=86400`.
              schema:
                type: string
            X-Paywise-Environment:
              description: Environment that produced the response.
              schema:
                enum:
                  - production
                  - sandbox
                type: string
            X-Paywise-Request-Id:
              description: >-
                Fresh server-assigned correlation id for this response.
                Caller-provided request ids are ignored.
              schema:
                format: uuid
                type: string
      security:
        - caseBearerAuth: []
        - partnerBearerAuth: []
components:
  schemas:
    PaymentWriteRequest:
      description: Payment input; the target is supplied exclusively by the URL.
      properties:
        amount:
          allOf:
            - $ref: '#/components/schemas/PaymentAmountWriteRequest'
          description: Amount received.
        metadata:
          description: >-
            Metadata supplied when reporting the payment; duplicate types are
            allowed.
          items:
            $ref: '#/components/schemas/PaymentMetadataWriteRequest'
          type: array
        value_date:
          description: Date on which the payment was credited; must not be in the future.
          format: date
          type: string
        your_reference:
          description: Your reference for reconciling this payment.
          maxLength: 255
          nullable: true
          type: string
      required:
        - amount
        - value_date
      type: object
    PaymentRead:
      description: Read representation of one reported payment.
      properties:
        amount:
          allOf:
            - $ref: '#/components/schemas/PaymentAmountRead'
          description: Amount received.
          nullable: true
          readOnly: true
        claim:
          allOf:
            - $ref: '#/components/schemas/PaymentClaimReference'
          description: Claim to which the payment was reported.
          nullable: true
          readOnly: true
        created_at:
          description: Time at which the payment was reported.
          format: date-time
          readOnly: true
          type: string
        id:
          description: Stable identifier of this reported payment.
          format: uuid
          readOnly: true
          type: string
        mandate:
          allOf:
            - $ref: '#/components/schemas/PaymentMandateReference'
          description: Accepted case containing the claim.
          nullable: true
          readOnly: true
        metadata:
          description: Stored metadata entries; duplicate types remain separate entries.
          items:
            $ref: '#/components/schemas/LegacyMetadataRead'
          readOnly: true
          type: array
        updated_at:
          description: Time at which the payment record was last updated.
          format: date-time
          readOnly: true
          type: string
        value_date:
          description: Date on which the payment was credited.
          format: date
          readOnly: true
          type: string
        your_reference:
          description: Your reference for reconciling this payment.
          nullable: true
          readOnly: true
          type: string
      required:
        - amount
        - claim
        - created_at
        - id
        - mandate
        - metadata
        - updated_at
        - value_date
        - your_reference
      type: object
    Error:
      properties:
        code:
          description: Machine-readable error category.
          type: string
        detail:
          description: Short human-readable summary of the error.
          type: string
        errors:
          description: Field-level validation errors, when applicable.
          items:
            $ref: '#/components/schemas/ErrorItem'
          type: array
      required:
        - detail
        - code
      type: object
    PaymentAmountWriteRequest:
      description: |-
        Base for every nested EUR amount object; subclasses override `value`
        through :func:`amount_value_field` to set their own digit/floor limits.
      properties:
        currency:
          allOf:
            - $ref: '#/components/schemas/CurrencyEnum'
          default: EUR
          description: |-
            Currency of the payment; currently always EUR.

            * `EUR` - EUR
        value:
          description: >-
            Amount received in major currency units, with at most two decimal
            places; must be at least 0.01.
          format: decimal
          pattern: ^-?\d{0,14}(?:\.\d{0,2})?$
          type: string
      required:
        - value
      type: object
    PaymentMetadataWriteRequest:
      description: One creation-time metadata row; duplicate types are intentional.
      properties:
        type:
          allOf:
            - $ref: '#/components/schemas/PaymentMetadataWriteTypeEnum'
          description: |-
            Payment metadata type.

            * `comment` - comment
            * `invoice:reference` - invoice:reference
            * `invoice:update_and_capture` - invoice:update_and_capture
            * `transaction:reference` - transaction:reference
            * `contract:reference` - contract:reference
            * `report:reference` - report:reference
            * `contravention:reference` - contravention:reference
        value:
          description: Metadata value; duplicate types remain separate entries.
          maxLength: 255
          minLength: 1
          type: string
      required:
        - type
        - value
      type: object
    PaymentAmountRead:
      properties:
        currency:
          description: Currency of the payment.
          readOnly: true
          type: string
        value:
          description: Amount received, expressed with two decimal places.
          format: decimal
          pattern: ^-?\d{0,14}(?:\.\d{0,2})?$
          readOnly: true
          type: string
      required:
        - currency
        - value
      type: object
    PaymentClaimReference:
      properties:
        document_reference:
          description: Invoice, contract, or source-document number of the claim.
          nullable: true
          readOnly: true
          type: string
        id:
          description: Identifier of the claim receiving the payment.
          format: uuid
          readOnly: true
          type: string
        your_reference:
          description: Your reference for the claim.
          nullable: true
          readOnly: true
          type: string
      required:
        - document_reference
        - id
        - your_reference
      type: object
    PaymentMandateReference:
      properties:
        id:
          description: Identifier of the accepted case receiving the payment.
          format: uuid
          readOnly: true
          type: string
        reference_number:
          description: paywise case-file reference number.
          readOnly: true
          type: string
      required:
        - id
        - reference_number
      type: object
    LegacyMetadataRead:
      description: Stored types may predate today's resource-specific input choices.
      properties:
        type:
          description: >-
            Stored metadata type; historical values may be outside today's input
            enum.
          readOnly: true
          type: string
        value:
          description: Stored metadata value.
          readOnly: true
          type: string
      required:
        - type
        - value
      type: object
    ErrorItem:
      properties:
        code:
          description: Machine-readable field error code.
          type: string
        field:
          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.
          nullable: true
          type: string
        message:
          description: Human-readable explanation of the field error.
          type: string
      required:
        - field
        - code
        - message
      type: object
    CurrencyEnum:
      description: '* `EUR` - EUR'
      enum:
        - EUR
      type: string
    PaymentMetadataWriteTypeEnum:
      description: |-
        * `comment` - comment
        * `invoice:reference` - invoice:reference
        * `invoice:update_and_capture` - invoice:update_and_capture
        * `transaction:reference` - transaction:reference
        * `contract:reference` - contract:reference
        * `report:reference` - report:reference
        * `contravention:reference` - contravention:reference
      enum:
        - comment
        - invoice:reference
        - invoice:update_and_capture
        - transaction:reference
        - contract:reference
        - report:reference
        - contravention:reference
      type: string
  securitySchemes:
    caseBearerAuth:
      description: >-
        Company-bound Case Management API key — the standard credential for this
        API.
      scheme: bearer
      type: http
    partnerBearerAuth:
      description: >-
        Partner API key acting for one entitled company; every Case request must
        then also carry the X-On-Behalf-Of-Company header.
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.