> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paywise.de/llms.txt
> Use this file to discover all available pages before exploring further.

# SDKs

> Official TypeScript and Python SDKs for the Case Management API and the Partner API

paywise publishes official SDKs for TypeScript/JavaScript and Python. Each SDK covers the [Case Management API](/api-docs/case-management-api/introduction) and the [Partner API](/api-docs/partner-api/introduction) with one client, typed requests and responses, automatic retries and pagination.

| Language | Package | Source |
| - | - | - |
| TypeScript / JavaScript | [`@paywise/sdk`](https://www.npmjs.com/package/@paywise/sdk) on npm | [paywise-gmbh/paywise-typescript](https://github.com/paywise-gmbh/paywise-typescript) |
| Python | [`paywise`](https://pypi.org/project/paywise/) on PyPI | [paywise-gmbh/paywise-python](https://github.com/paywise-gmbh/paywise-python) |

> [!NOTE]
>
> The SDKs are in beta (version `0.x`). Until `1.0.0`, a minor version may contain breaking changes; pin the version you test against.

## Install

```bash TypeScript theme={null}
npm install @paywise/sdk
```

```bash Python theme={null}
pip install paywise
```

The TypeScript SDK requires Node.js 18 or newer and has no runtime dependencies. The Python SDK requires Python 3.10 or newer and ships a synchronous and an asynchronous client.

## Create a client

Create an API key in the paywise portal under **Für Entwickler**, see [Authentication and environments](/api-docs/essentials/authentication-and-environments). Choose the environment that matches the key: sandbox keys start with `pw_sbx_` and only work against the sandbox.

```ts TypeScript theme={null}
import { PaywiseClient, PaywiseEnvironment } from "@paywise/sdk";

const client = new PaywiseClient({
  environment: PaywiseEnvironment.Sandbox, // PaywiseEnvironment.Production for live keys
  token: process.env.PAYWISE_API_KEY,
});

const health = await client.caseManagement.health.check();
```

```python Python theme={null}
import os
from paywise import Paywise, PaywiseEnvironment

client = Paywise(
    environment=PaywiseEnvironment.SANDBOX,  # PaywiseEnvironment.PRODUCTION for live keys
    token=os.environ["PAYWISE_API_KEY"],
)

health = client.case_management.health.check()
```

One client serves both APIs: Case Management operations live under `caseManagement` (Python: `case_management`), Partner operations under `partner`. A key can only call the operations its type and [permission scopes](/api-docs/essentials/authentication-and-environments#permission-scopes) allow.

## Partner keys: act on behalf of a company

A Partner key calls the Case Management API for one of its managed companies by sending the `X-On-Behalf-Of-Company` header. Set it on the client; use one client per company. Direct Case Management keys must not send this header.

```ts TypeScript theme={null}
const companyClient = new PaywiseClient({
  environment: PaywiseEnvironment.Sandbox,
  token: process.env.PAYWISE_PARTNER_API_KEY,
  onBehalfOfCompany: "<company id>",
});
```

```python Python theme={null}
company_client = Paywise(
    environment=PaywiseEnvironment.SANDBOX,
    token=os.environ["PAYWISE_PARTNER_API_KEY"],
    on_behalf_of_company="<company id>",
)
```

## Pagination

List operations return a pager that follows the `next` link of each page, see [Pagination and synchronization](/api-docs/essentials/pagination-and-synchronization).

```ts TypeScript theme={null}
const claims = await client.caseManagement.claims.listClaims({ limit: 50 });
for await (const claim of claims) {
  console.log(claim.id);
}
```

```python Python theme={null}
for claim in client.case_management.claims.list_claims(limit=50):
    print(claim.id)
```

## Errors, retries and idempotency

Non-2xx responses raise a typed error per status code, for example `UnauthorizedError` for `401`. All errors expose the status code and the parsed [error body](/api-docs/essentials/errors-and-safe-retries).

The SDKs retry `408`, `429` and `5xx` responses twice by default and honour `Retry-After`; the Python SDK also retries `409`. Change the limit with `maxRetries` (Python: `max_retries`) on the client or per request.

Operations that create something take the `Idempotency-Key` as a required parameter. Retries reuse the same key, so a repeated request returns the original result instead of creating a second record. Generate one key per logical operation and keep it when you retry yourself.

## Versions and support

The SDKs are generated from the published OpenAPI contracts on this site and follow them closely. New API fields and operations reach the SDKs in a new release; see the release notes in each repository. Report problems with the SDKs at [support@paywise.de](mailto:support@paywise.de) or as an issue in [paywise-gmbh/developer-resources](https://github.com/paywise-gmbh/developer-resources).

The full list of methods is in the `reference.md` of each SDK repository.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.