Skip to main content
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.
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.
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.
Follow the quickstart and the lifecycle and integration rules.

​
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 to inspect the contract or generate a client. The export uses OpenAPI 3.0.3 and includes 22 operations, descriptions, and examples.
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.
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.