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

# Mahnservice API — developer preview

> Prepare a Mahnservice integration before the beta test environment is released.

<Warning>
  **Draft documentation — API not yet rolled out.** These documents are published in advance so you can prepare your integration. The contract and examples may change before release. Sandbox access will be provided separately; publication of these documents does not mean the API is available for testing or production use.
</Warning>

The Mahnservice API submits invoices to your company's dunning workflow. Creating an invoice does **not** start dunning: it stays held until you explicitly release it. Configure and activate the company's workflow in the Mahnservice portal.

## Access and authentication

Use the **sandbox API origin supplied with your beta access**, followed by `/mahnservice/v1/`. Do not substitute the app/portal host or add an `/api/` prefix. There is no confirmed beta host or access date in this preview.

Authenticate every business request with `Authorization: Bearer <your-key>`. Keys are company-bound and shared with the Case Management API; there is no separate per-product key. Request the appropriate `mahnservice:debtors:read`, `mahnservice:debtors:write`, `mahnservice:invoices:read` and `mahnservice:invoices:write` scopes. A write scope includes its corresponding read scope.

Use `GET /info/` to verify the company and `environment` before submitting data. The legacy `access_mode` field is **not** the environment indicator: modern keys can report `access_mode: production` in the sandbox too. Check `environment: sandbox` and the `X-Paywise-Environment` response header.

Production access, when released, additionally requires the applicable subscription and API terms acceptance for gated writes. Reads and payment reporting remain available through a subscription lapse, subject to authorization and administrative restrictions. The beta does not authorize live reminders to real debtors.

## Intended beta scope

* Create and retrieve debtors and invoices; list them with pagination.
* Correct an invoice while held, before release.
* Upload an optional PDF, observe asynchronous processing, and download it once ready.
* Release an invoice into the company's configured workflow.
* Read dunning status, pause/resume dunning, and report payments.
* Cancel or write off eligible invoices before Inkasso handover.
* Read dunning-flow configuration and consume the supported invoice/dunning webhook events.

## Known limitations

* One PDF per invoice; no multiple attachments or JPEG/PNG uploads. No URL ingestion or document-retry endpoint.
* No debtor update/delete endpoints, and no invoice delete endpoint.
* Workflow configuration stays in the portal. Release uses the company default, matching the existing app behavior.
* No `Verzugspauschale` support in this preview.
* No dedicated failed-send or paused-process webhook; query invoice/dunning state for those changes.
* The Inkasso claim ID is not exposed through this API after handover. Handover itself is supported.
* Partial payments reduce the reported balance, but the current dunning process continues over the full invoice amount. Verify that this behavior meets your requirements before any production use.
* After handover, the collection case owns settlement: reporting a payment does not change the Mahnservice process back from its Inkasso state. Cancellation/write-off through this API is refused at that point.

## Start building

You can use this preview now to map your debtor and invoice data, generate a client from the OpenAPI schema, and prepare request handling and webhook processing with mocks. Running requests against paywise requires separately supplied sandbox access.

<Note>
  **Multiple PDFs per invoice are planned but are not supported by this published preview contract.** The current upload replaces the existing PDF; repeated uploads do not add attachments. If your integration requires several PDFs, keep that part of the integration pending until the multi-document contract and updated schema are published. Document limits and add/replace/delete behavior are not yet committed here.
</Note>

Follow the [quickstart](/api-docs/mahnservice-api/quickstart) and the [lifecycle and integration rules](/api-docs/mahnservice-api/lifecycle).

## Endpoint reference

Browse the endpoint pages in the sidebar under **Debtors**, **Invoices**, **Documents**, **Payments**, **Dunning**, **Dunning flows**, and **Info**. Each page includes the request parameters, response schemas, and examples from the draft OpenAPI specification.

## OpenAPI download

[Download the OpenAPI schema](/api-docs/mahnservice-api/openapi.json) to inspect the contract or generate a client. The export uses OpenAPI **3.0.3** and includes 22 operations, descriptions, and examples.

<Warning>
  The exported schema preserves the implementation's production server metadata (`https://api.paywise.de`). **Override the server/base URL with the sandbox API origin supplied with your beta access.** The schema paths already include `/mahnservice/v1/`; do not add that prefix again in a generated client. Downloading this preview does not grant production access.
</Warning>

This draft schema may change before release. It has not yet been verified against a deployed beta environment; sandbox access will be provided separately.

The runtime reference will be available on the supplied API origin at `/mahnservice/v1/docs/`, with its schema at `/mahnservice/v1/schema/?format=json&lang=en`.