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

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

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.

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:

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):

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

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 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 — search for "merchant application".