Skip to main content

​
Unreleased — Mahnservice API (DEVPW-1352)

This change accompanies the Mahnservice API release under review and is not yet available in production.
  • Six new invoice and dunning webhook event types carry only company and invoice UUIDs. Retrieve the invoice and its dunning state through the Mahnservice API when processing an event.
  • Mahnservice documents are uploaded to POST /mahnservice/v1/invoices/{uuid}/documents/ as multipart file or JSON base64, with an optional filename. URL ingestion (document_url or url) is not supported. Poll the invoice’s document summary or the documents endpoint for public status pending, ready, failed or rejected; download_url is available only when ready.
  • Releasing an invoice with a supplied document that is not ready returns 409 document_not_ready. Replace failed documents by uploading again while the invoice is held. There is no document retry endpoint. Replacement removes the previous PDF; failure or rejection does not restore it. Terminal failures discard quarantined bytes. Invoices without a supplied document retain their existing behavior.
  • Document IDs and created_at remain stable across replacements; updated_at reflects resource changes. has_document includes PDFs from bookkeeping integrations; document describes an API ingestion record and can be null even when a bookkeeping PDF exists.
  • Scanning uses the shared document scanner. If no scanner is configured and DOCUMENT_SCANNER_REQUIRED is false, documents pass without antivirus scanning and system checks warn. Enabling the flag requires a configured, reachable scanner; rejected documents never become ready.
  • Dunning fees apply only when both the flow’s fees_enabled and the level’s fee_enabled are true. A level flag may remain true while the flow’s master switch is off.
  • Document-list entries retain filename and size: both are null for pending/failed documents and populated for ready documents.
  • Dunning-flow lists include historical versions referenced by existing invoices. The current is_default configuration sorts first; is_active controls whether a flow may run and does not identify the latest version.
  • Changing a held invoice’s amount or currency after any payment has been reported returns 409 with invoice_has_payments. Other permitted metadata edits remain available.

​
September 2026

​
September 02

  • Create Claim (POST /v1/claims/), Create Debtor (POST /v1/debtors/) and Release Claim for Processing (PATCH /v1/claims/{id}/) now answer 400 instead of 500 when data stored on your paywise account or company profile fails validation while the case is being created. The most common cause is an invalid contact email address on the paywise user the API token belongs to; it is copied onto the case and validated there. Previously this produced a server error with no usable information. The error is returned as non_field_errors and reads: “Some data in your paywise account or company profile is invalid. Please correct it in paywise or contact paywise support.”, followed by the underlying validation message. Nothing is stored when this happens; the request can be repeated unchanged once the account data is corrected. Requests that already succeeded, and validation errors on fields you send yourself, are unaffected.

​
September 01

  • New filter document_reference on the Mandate Details endpoint: find the mandate details of a statement by the document number of one of its claims, usually your invoice number. Matching is case-insensitive and also finds partial values.
  • Clarified the your_reference filter on the same endpoint: it searches the free-form claim reference you assigned to the claim (e.g. an order or contract reference), not the invoice number. Its behavior is unchanged; the previous parameter description and examples wrongly suggested that it matches invoice numbers. Use the new document_reference filter for those.
  • No existing endpoint, field or webhook event changed.

​
August 2026

​
August 29

  • New status update search across all of your cases: GET /v1/statusupdates/ returns a single paginated feed of every status update paywise has published to you, instead of paginating each case separately:
    • Overview: what the feed contains, how search and filters combine, and how a result identifies its case
    • Search with q over the status title and the visible text of its description — HTML markup and entities in a rich-text description do not affect matching. The same parameter also matches an event code, exactly and case-insensitively. Search terms need at least three characters.
    • Filter by mandate, reference_number (current or historical, case-insensitive), legal_stage, processing_state, created_after and created_before
    • Results cover main cases and sub-cases. Every row carries the publishing case in mandate and the main case’s reference in reference_number, because sub-cases have no reference number of their own.
    • Ordering is newest first by the business-effective date (custom_date where paywise supplied one, otherwise the creation timestamp), with a stable secondary order so a row never moves between pages. Up to 200 updates per page.
    • Attachment download URLs are unchanged and keep working. Entries in this collection omit file_size, so listing updates never triggers one storage lookup per attachment.
  • No existing endpoint, field or webhook event changed.

​
August 19

  • New Aktenabrechnungen (per-case statements) endpoints available. An Aktenabrechnung settles exactly one case, alongside the existing statements endpoint, which settles a whole clearing run:
    • Overview: What an Aktenabrechnung is, how it differs from a statement, the sign convention of total_balance, filters and the PDF download
    • List Aktenabrechnungen: List all released per-case statements, filterable by case reference, your own customer number, settlement type and booking date
    • Retrieve an Aktenabrechnung: Retrieve a single per-case statement with its principal claims, VAT breakdown and cost burden
    • The PDF is available at /v1/single-mandate-statements/{id}/download/full-pdf/
  • Two new webhook event types, single_mandate_statement.created and single_mandate_statement.updated, notify you when a per-case settlement is released to you or changes.
  • No existing endpoint, field or webhook event changed.

​
May 2026

​
May 04

  • Webhooks are now available. Subscribe to events and receive real-time notifications for changes to your claims, mandates, payments, statements, and requests to client. This allows you to react instantly to updates instead of polling the API:
    • Overview: Introduction, how it works, and a quick example
    • Event Types: Complete list of available event types
    • Signature Verification: HMAC SHA-256 verification with Python, Node.js, and PHP examples
    • Manage Endpoints: API reference for creating, updating, and deleting webhook endpoints, plus test events and delivery inspection
    • Delivery & Retries: Payload format, retry schedule, auto-disable behavior, and best practices

​
November 2025

​
November 25

  • New Request to Client endpoints available for handling inquiries from paywise (“Rückfragen”). These endpoints allow you to fully automate the process of receiving and answering questions from paywise during the debt collection process:
    • List requests to client: Get all requests for a mandate, with optional filtering by answered/unanswered status
    • Get request details: Retrieve full details of a specific request including file attachments
    • Submit answer: Submit your response to a request (supports yes/no answers, free text, and file uploads depending on the request type)
    • Upload documents: Attach document files (PDF, JPEG, PNG) to your answer

​
August 2025

​
August 21

  • New field related_statements added to the Mandate Details endpoint: Shows all other statements containing the same mandate with their hrefs, mandate_details_hrefs, IDs, and clearing numbers. This allows you to track a mandate across multiple statements and see its complete history.

​
May 2025

​
June 04

  • Added File Download Links for Mandate Status Updates: Download any file attachements that our status updates may have (our letters to the debtor, court documents, etc.)

​
May 22

  • Beta access for the new statements endpoint available. Use it to get full insight into our periodic client statements (“Abrechnungen”) via the API. All the information from our statements which you receive in PDF- and Excel-format is now available. This allows for end-to-end automation of your entire debt collection process.

​
October 2024

​
October 14

  • New field send_order_confirmation available for the Release Claim for Processing endpoint. This allows you to specify whether or not you want to receive an order confirmation for the claim you submitted. If you submit multiple claims with the same debtor at the same time it is best to only set this flag to true on the last claim to avoid receiving multiple emails.

​
October 10

  • New endpoint info available. This endpoint allows you to get details on the currently used API key in order to test successful authentication.
  • Bugfix: Empty lists on the claims sub objects caused an error on the API. This is fixed now.

​
May 2024

​
May 06

  • New field legal_claim_balances available for the Mandate object. This gives you information on the Legal Claim Balance of the mandate (“Forderungsstand”).
  • New field further_reference_numbers available for Mandate object.

​
January 2024

​
January 30

  • Changing the type of the field quantity for a claim’s item from Integer to Double.
  • New field unit available for claim’s items object. Use it to specify the unit used to measure the quantity of an item belonging to a claim.

​
January 08

  • New field created available for the Mandate object.
  • New field created available for mandate’s Status Update object.

​
November 2023

​
November 28

  • New field reference_number (“Aktenzeichen”) available for the Mandate object.

​
June 2023

​
June 8

  • Adding the new payments endpoint. Use it to create, list and retrieve payments which you received directly from your debtors.
  • New field payment available for the claim object to allow payment object creation along with claim creation.
  • New field payment available when retrieving Claim and Mandate objects.

​
November 2022

​
November 28

  • Initial release