API Reference
The wallee join APIs are part of the Web Service API v2.0. They cover two areas:
- Partnerships — create and manage the link between your partner account and your merchants' accounts.
- Merchant Applications — create, prefill and track the KYC applications of merchants you onboard.
Base URL
https://app-wallee.com/api/v2.0
Authentication & headers
All requests are authenticated with a JSON Web Token and executed in the context of your partner account:
| Header | Value | Description |
|---|---|---|
| Authorization | Bearer <JWT> | JWT issued for your application user |
| account | <YOUR_ACCOUNT_ID> | The partner account the request executes under |
| Content-Type | application/json | For requests with a body |
You need an application user with an authentication key and the JOIN_PROGRAM_ACCESS permission. See the Web Service API introduction for how to create the JWT and the permission concept for role management.
SDKs
All join endpoints are part of the wallee Web Service API, so you can use the official wallee SDKs to integrate the onboarding flow — or call the REST API directly from any language. All SDKs are open source and available on GitHub:
| Language | Repository | Package manager |
|---|---|---|
| PHP | wallee-payment/php-sdk | Composer |
| Java | wallee-payment/java-sdk | Maven |
| TypeScript / JS | wallee-payment/typescript-sdk | npm |
| Python | wallee-payment/python-sdk | pip |
| C# / .NET | wallee-payment/csharp-sdk | NuGet |
| Ruby | wallee-payment/ruby-sdk | RubyGems |
Tip: The SDKs handle JWT authentication, request signing and (de)serialisation of the data models for you. See each repository's README for installation and a quick start.
Testing your integration
- Use the interactive API client to explore requests and responses against your account before writing code — search for "partnership" or "application" to find the join endpoints, inspect the full request/response schemas and generate code snippets. Requests sent from the client are live requests.
- Set up webhook listeners to receive onboarding and transaction state changes in your platform.
Error handling
The APIs use standard HTTP status codes:
| Code | Meaning |
|---|---|
| 200 | Request successful |
| 201 | Resource created |
| 204 | Resource deleted (no content) |
| 400 | Invalid request — missing or invalid fields, invalid configuration |
| 401 | Authentication failed — check JWT and application user |
| 403 | Missing permission (JOIN_PROGRAM_ACCESS) |
| 404 | Resource not found |
| 409 | Conflict — e.g. the resource already exists |
| 500 | Unexpected server error |
Error responses contain a machine-readable error type and a human-readable message identifying the invalid field or condition.
Webhooks
For event-driven integrations, subscribe to webhooks instead of polling — e.g. to get notified when a merchant application changes state or a partnership becomes active.
Developer resources
- Developer documentation — space concept, permission concept, integration modes
- Web Service API reference
- Data models
- SDK overview on GitHub