Skip to main content
All API requests use a Bearer key:
Production and sandbox have different hosts and credentials but the same contract. Production is https://api.paywise.de; the sandbox is https://api-sandbox.paywise.de. A credential works only in its own environment: sandbox keys carry the pw_sbx_ prefix and are rejected by the production host, and vice versa. There is no access_mode field or environment-switch header, and API keys cannot create, rotate, enumerate, or mint other API keys.

​
Select the company context

A direct Case key is permanently bound to one company and must not send an on-behalf-of header. A Partner key can manage every company entitled to that Partner. When it calls the Case Management API, it must select one of those companies:
Direct Case keys reject X-On-Behalf-Of-Company. Partner-management endpoints under /partner/v2/ reject it too. There is no on-behalf-of-user header. The tenant-independent legal-form catalog (GET /v2/legal-forms/) is the one Case operation a Partner key may call without the header; a header sent there is still validated.

​
Permission scopes

Top-level order, claim, enforceable-title, and their document routes use the case:orders permissions. Claim payment routes ride case:payments in every lifecycle state: listing needs case:payments:read, while reporting and deleting need case:payments:write. Inline payments[] on order or claim creation remain part of the create command and stay under case:orders:write. A key without the required payment permission receives 403 permission_denied; case:payments:write also satisfies the read.

​
Credential ownership

API keys belong to the company — Case Management and Mahnservice keys — or to the Partner — Partner keys — not to the person who created them. The creator is recorded for information only. A key keeps working when that person leaves: when their membership is removed, their account is deactivated, or their account is deleted. A key stops working only when it is deleted or rotated in the developer portal, when paywise suspends the key or the company’s API access, or when the company is offboarded. A person who has left may still hold a copy of a key. The developer portal therefore shows who created each key and marks keys whose creator has left, and when a creator leaves, the company’s administrators and developers (or, if there are none, all of its members) receive an e-mail listing that person’s keys. Rotate a key if the person may still have it. The sandbox sends no such e-mail. The Mahnservice API records its changes in the name of a person of your company: the key’s creator while they are an active member, otherwise another active member, administrators first and never a paywise staff account. When the company has no active member left, Mahnservice requests answer 401. The Case Management and Partner APIs need no such person.

​
Recover from authentication and context failures

  • 401: check the Bearer key, API host, and environment pairing.
  • 400: for a Partner-to-Case call, validate the company UUID and header.
  • 403: the credential is known but not permitted for this operation. Follow the returned error code and contact paywise support if access is unexpectedly denied.
  • 404: do not assume the resource exists elsewhere; verify the selected company before retrying. Resources outside the selected tenant are deliberately hidden with 404.
Use Case credential info or Partner credential info to inspect the authenticated context, and consult the orders list reference for the company-selection header on a Case operation.