> For the complete documentation index, see [llms.txt](https://wallee.gitbook.io/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wallee.gitbook.io/documentation/wallee-join/api-reference.md).

# API Reference

The wallee join APIs are part of the Web Service API v2.0. They cover two areas:

* [Partnerships](https://claude.ai/cowork/partnerships.md) — create and manage the link between your partner account and your merchants' accounts.
* [Merchant Applications](https://claude.ai/cowork/merchant-applications.md) — 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](https://app-wallee.com/doc/api/web-service) for how to create the JWT and the [permission concept](https://app-wallee.com/en-us/doc/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](https://github.com/wallee-payment/php-sdk)               | Composer        |
| Java            | [wallee-payment/java-sdk](https://github.com/wallee-payment/java-sdk)             | Maven           |
| TypeScript / JS | [wallee-payment/typescript-sdk](https://github.com/wallee-payment/typescript-sdk) | npm             |
| Python          | [wallee-payment/python-sdk](https://github.com/wallee-payment/python-sdk)         | pip             |
| C# / .NET       | [wallee-payment/csharp-sdk](https://github.com/wallee-payment/csharp-sdk)         | NuGet           |
| Ruby            | [wallee-payment/ruby-sdk](https://github.com/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](https://app-wallee.com/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](https://app-wallee.com/en-us/doc/webhooks) listeners to receive onboarding and transaction state changes in your platform.

## Error handling

The APIs use standard HTTP status codes:

<table data-search="false"><thead><tr><th>Code</th><th>Meaning</th></tr></thead><tbody><tr><td>200</td><td>Request successful</td></tr><tr><td>201</td><td>Resource created</td></tr><tr><td>204</td><td>Resource deleted (no content)</td></tr><tr><td>400</td><td>Invalid request — missing or invalid fields, invalid configuration</td></tr><tr><td>401</td><td>Authentication failed — check JWT and application user</td></tr><tr><td>403</td><td>Missing permission (JOIN_PROGRAM_ACCESS)</td></tr><tr><td>404</td><td>Resource not found</td></tr><tr><td>409</td><td>Conflict — e.g. the resource already exists</td></tr><tr><td>500</td><td>Unexpected server error</td></tr></tbody></table>

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](https://app-wallee.com/en-us/doc/webhooks) instead of polling — e.g. to get notified when a merchant application changes state or a partnership becomes active.

## Developer resources

* [Developer documentation](https://app-wallee.com/doc) — space concept, permission concept, integration modes
* [Web Service API reference](https://app-wallee.com/doc/api/web-service)
* [Data models](https://app-wallee.com/en-us/doc/api/model)
* [SDK overview on GitHub](https://github.com/wallee-payment)