> 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/merchant-applications-api.md).

# Merchant Applications API

A **merchant application** carries the KYC data of a merchant you onboard: company details, legal form, beneficial owners, bank details and the merchant's product/pricing context. Applications are structured in **steps** that can be filled and updated individually, and end with the merchant's own legal confirmation via the hosted submission flow.

**Base path:** `/api/v2.0/onboarding/merchant-applications` · **Permission:** JOIN\_PROGRAM\_ACCESS

<table data-search="false"><thead><tr><th>Method</th><th>Path</th><th>Description</th></tr></thead><tbody><tr><td>POST</td><td>/</td><td>Create a merchant application (empty draft or full data)</td></tr><tr><td>GET</td><td>/</td><td>List all merchant applications</td></tr><tr><td>GET</td><td>/search</td><td>Search merchant applications</td></tr><tr><td>GET</td><td>/{id}</td><td>Retrieve a merchant application</td></tr><tr><td>PATCH</td><td>/{id}</td><td>Update a merchant application</td></tr><tr><td>DELETE</td><td>/{id}</td><td>Delete a merchant application (permanent)</td></tr><tr><td>PATCH</td><td>/{id}/steps</td><td>Update a merchant application step</td></tr><tr><td>DELETE</td><td>/{id}/steps</td><td>Delete a merchant application step</td></tr><tr><td>GET</td><td>/{id}/submission-url</td><td>Return the hosted submission URL</td></tr><tr><td>GET</td><td>/{id}/status</td><td>Retrieve the application status</td></tr><tr><td>POST</td><td>/{id}/submit</td><td>Submit the application and create an organization</td></tr></tbody></table>

## Typical lifecycle

```
create (draft) ──▶ update / update steps ──▶ submission URL ──▶ merchant confirms ──▶ status: active
                                        └──▶ submit & create organization (API-completed flow)
```

## Create a merchant application

The request body is optional: send an **empty body** to create a draft application, or send the **full application payload** to create it with initial data. Prefill everything you already know about your customer — they will not have to re-enter it.

```bash
curl -X POST "https://app-wallee.com/api/v2.0/onboarding/merchant-applications" \
  -H "Authorization: Bearer <JWT>" \
  -H "account: <YOUR_ACCOUNT_ID>" \
  -H "Content-Type: application/json" \
  -d '{ ...merchant application data... }'
```

Response: `201 Created` with the application including its `id`.

## Retrieve, list and search

```
GET /api/v2.0/onboarding/merchant-applications/{id}
GET /api/v2.0/onboarding/merchant-applications
GET /api/v2.0/onboarding/merchant-applications/search
```

Use list/search to build your own overview of onboarding pipelines — e.g. all applications still in draft, or all applications submitted in the last week.

## Update a merchant application

Applications can be updated while they are in draft:

```bash
curl -X PATCH "https://app-wallee.com/api/v2.0/onboarding/merchant-applications/{id}" \
  -H "Authorization: Bearer <JWT>" \
  -H "account: <YOUR_ACCOUNT_ID>" \
  -H "Content-Type: application/json" \
  -d '{ ...updated fields... }'
```

## Update or delete a single step

Applications are divided into steps (e.g. company details, beneficial owners). Steps can be updated or removed individually — useful when your platform collects the data across several screens:

```
PATCH  /api/v2.0/onboarding/merchant-applications/{id}/steps
DELETE /api/v2.0/onboarding/merchant-applications/{id}/steps
```

## Get the submission URL

The merchant must review and legally confirm the application themselves. Fetch the hosted submission URL and redirect the merchant (or embed the link in your product):

```bash
curl "https://app-wallee.com/api/v2.0/onboarding/merchant-applications/{id}/submission-url" \
  -H "Authorization: Bearer <JWT>" \
  -H "account: <YOUR_ACCOUNT_ID>"
```

## Retrieve the application status

```bash
curl "https://app-wallee.com/api/v2.0/onboarding/merchant-applications/{id}/status" \
  -H "Authorization: Bearer <JWT>" \
  -H "account: <YOUR_ACCOUNT_ID>"
```

Use this to show onboarding progress inside your own product, or subscribe to [webhooks](https://app-wallee.com/en-us/doc/webhooks) for state changes instead of polling.

## Submit the application and create an organization

Completes the application programmatically and creates the merchant's organization:

```
POST /api/v2.0/onboarding/merchant-applications/{id}/submit
```

> Regardless of how the application is completed, wallee runs the full KYC/AML and PSD2 checks and remains the regulated entity. The merchant's legal confirmation is always required.

## Delete a merchant application

```
DELETE /api/v2.0/onboarding/merchant-applications/{id}
```

Response: `204 No Content`

> **Warning:** Deletion is permanent and cannot be undone. Only draft applications should be deleted.

Full request/response schemas for every endpoint: [interactive API client](https://app-wallee.com/api/client) — search for "merchant application".