Get Started
Your first steps with the paywise Partner API
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_TOKENin your request header.
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:
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.
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.
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
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.
Add additional Users (optional)
Repeating steps 2 - 4 you can onboard additional users to the company if required.
Start handing over Claims
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.
Create a Company
Create a Company. In this step you MUST provide all input data that is relevant for your company.
data_submission_completed flag on the company.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.
skip_email_validation flag.Start handing over Claims
Next Steps
Once you decided on a high-level onboarding approach, you can start following the detailed guides: