Skip to main content
paywise versions each API in its path, and only changes the version when the contract changes in a way that would break a correctly written client. Inside one version the contract grows; it does not shrink or change meaning.

​
Path-based versions

There is no version header, query parameter, or per-key version pin. The prefix you call is the contract you get, on both api.paywise.de and api-sandbox.paywise.de.

​
Non-breaking changes

The following may appear inside the current version at any time. They are announced in the changelog but require no action, so build your client to tolerate them from day one:
  • New optional request fields and new response fields. Ignore fields you do not know; do not fail on them.
  • New members in error bodies and webhook data. The published OpenAPI leaves response, error, and event objects open; configure generated clients and validators to allow additional properties.
  • New enum values where the field is documented as open (for example order and mandate states, event types, error codes). Treat an unknown value as “other” rather than as an error.
  • New endpoints and new operations on existing resources.
  • New webhook event types. A subscription created with "*" receives them automatically; one created with an explicit list does not. Answer 2xx for a type you do not recognise and skip it; never fail the delivery.
  • New response headers.
  • Relaxed validation — a request that was accepted before stays accepted; a request that was rejected before may now succeed.
  • Documentation-only changes: descriptions, examples, summaries.

​
Breaking changes

These never happen inside a version. They wait for the next version prefix, with a migration page and the notice period below:
  • Removing or renaming a path, field, header, or enum value.
  • Changing a field’s type, format, or meaning; changing a default.
  • Tightening validation so that a previously valid request is rejected.
  • Changing which status code or error type an outcome produces.
  • Changing authentication, access, or tenant-selection rules.
  • Removing a webhook event type, or removing, renaming, or retyping a member of its payload.

​
API v1 deprecation

With the initial v2 release, the Case Management and Partner v1 APIs become deprecated. They remain available during migration; no shutdown date has been announced. The v1 contracts are frozen and receive only security and critical fixes. Their documentation is preserved unchanged under Legacy APIs. Build new integrations against the current prefixes and move existing ones with the migration pages: The new Mahnservice API uses /mahnservice/v1/ and is not deprecated.

​
Deprecation policy

No endpoint is scheduled for retirement, and no current response carries the Deprecation or Sunset headers described here.
When paywise retires a version or an individual endpoint:
  1. The retirement is announced in the changelog with the date on which the affected operations stop working.
  2. A migration page describes what replaces the retired contract, what stays the same, and what changes.
  3. Affected responses carry a Deprecation header from the announcement onwards and a Sunset header naming the retirement date, so a client can detect the notice at runtime instead of relying on someone reading the changelog.
  4. The notice period is at least six months between announcement and retirement.
  5. Retired pages stay in the documentation, labelled as retired, until the last migration window has passed.
Until a deprecation is announced, the changelog is the only signal you need to watch; once one is, the headers above let your client detect it at runtime.