Release Notes

​

October 2026

​

October 01

• The country field of addresses now accepts XK (Kosovo), in requests and in responses, wherever a country code is used — for example on debtor addresses in Create Debtor (POST /v1/debtors/) and Create Claim (POST /v1/claims/). Kosovo has no official ISO 3166-1 code; XK is the user-assigned code in common use (for example in IBANs). Previously a Kosovo address had to be sent with a neighbouring country’s code.
• No existing value was removed or renamed. If your integration validates responses against a fixed list of country codes, add XK.

​

September 2026

​

September 25

• submission_state gains cancelled. When a client cancels an order before paywise accepts it — in the paywise portal or through the current Case Management API — every claim of that order reads submission_state=cancelled on List Claims and Retrieve a Claim, and the submission_state filter accepts the value. The state is final and read-only; you cannot set it through this API. Clients that validate the enum strictly must accept the new value.
• The webhook signing secret is returned only once. secret_key is part of the response that creates an endpoint (POST /v1/webhooks/, new schema WebhookEndpointCreate) and no longer of any list, retrieve or update response, as Manage Endpoints already described. Store it when you create the endpoint; for a new secret, delete the endpoint and create it again.
• Webhook deliveries identify the event and the environment. Every payload carries two new top-level fields: event_id, the UUID of the event, which every delivery and retry of that event repeats, and environment, which is production, or sandbox for deliveries from the paywise sandbox. Deliveries also send the same value in an X-Paywise-Environment header. The body is compact JSON with sorted keys; verify the signature over the raw request body as received, never over a re-serialized copy. See Delivery & Retries.
• Delivery idempotency keys are stable per event. A delivery created for an event now has the idempotency_key event: followed by a SHA-256 hash of the endpoint, the event type and the event: it stays the same across retries, and each endpoint gets exactly one delivery per event. Deliveries created by POST /v1/webhooks/{id}/test/ keep the {webhook}:{event}:{timestamp} form. Deduplicate on the X-Paywise-Delivery-ID header or the payload’s event_id.
• The payload examples in the webhook guides now show the actual envelope: the company is data.company, and there is no data.access_mode.
• No other endpoint, field or webhook event changed.

​

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