​
About the API

The paywise Partner API is based on REST best practices. Our API tries to provide predictable resource-oriented URLs, accepts JSON request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. Depending on the endpoint and/or the entity that is managed with this endpoint, some operations may not be available due to procedural and/or legal restrictinos. You can use the paywise API in test mode, which doesn’t affect your live data. The API key you use to authenticate the request determines whether the request is live mode or test mode. See the Authentication guide paywise APIs don’t support bulk updates. You can work on only one object per request.

​
Authentication

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail. All API endpoints are authenticated using Bearer tokens.
  • There are separate token types for test and production environments. Always start with test keys first.
  • Generate a new API Key in your Account
  • Use the Authorization: Bearer YOUR_TOKEN in your request header.
$ curl -X GET https://api.paywise.de/partners/v1/info/ -H 'Authorization: Bearer YOUR_TOKEN'

​
Postman

To kickstart development you can download the current API Specification file from our resources and import it to Postman as a collection. We also provide an environment that you can import alongside the collection to quickly start trying our API.

​
Onboarding Approaches

In the context of the partner API we distinguish between two separate approaches to onboarding a new Company and its Users.

Understanding the Entities

Make sure to make yourself acquainted with the Entities section before deciding on an onboarding approach.

​
Onboarding Web Flow

The Web Flow onboarding approach is the default that is applicable for most usecases as it does mitigate the need for you to provide all data we need while also providing a transparent and secure user experience. Onboarding a new Company and user works in the following steps:
1

Create a Company

Create a Company. In this step you can provide as many of the data fields as possible - but you don’t have to.
2

Start User onboarding

Using the new Company you can start onboarding the first User. To do this, Create a User Invite using the User Invites endpoint. The result of this operation is a URL on paywise that is used to complete the Onboarding process.
3

Redirect the User to the Onboarding URL

The user will be prompted for their personal data and can set a personal password for their paywise Account. Additionally, the first user that is onboarded to a new Company will be prompted to review and add any missing data on their company
4

Handle Onboarding Result

Once the user successfully completes providing their data, they will be redirected to a success_url you provided in Step 2. Now the onboarding of the company as a paywise client is considered complete.
You also need to handle user cancellation and / or error cases appropriately.
5

Add additional Users (optional)

Repeating steps 2 - 4 you can onboard additional users to the company if required.
6

Start handing over Claims

The client is onboarded successfully and you can start handing over data using the Case Management API

​
API-only Onboarding

In certain usecases it is not possible to guide the user through a web-based onboarding flow. For these use cases, you can use the API-only onboarding flow.
Your Account will require special permissions for this onboarding flow.
1

Create a Company

Create a Company. In this step you MUST provide all input data that is relevant for your company.
To validate that you submitted all relevant information you can check the data_submission_completed flag on the company.
2

Create users

Using the new Company you can create the first User. Again, you must provide all relevant data for the user.
3

Wait for user to confirm their Email

All newly created users will be issued an invitation email that serves both as a validation that the user actually owns this email address and as a means for the user to set a password for their new account.
Depending on your usecase you can skip this step using the skip_email_validation flag.
4

Start handing over Claims

The client is onboarded successfully and you can start handing over data using the Case Management API

​
Next Steps

Once you decided on a high-level onboarding approach, you can start following the detailed guides:

Onboarding Web Flow

Detailed guide to onboarding users via the Onboarding Web Flow

API-only Onboarding

Detailed guide to onboarding users using the API only