Aller au contenu principal

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

MethodPathDescription
POST/Create a merchant application (empty draft or full data)
GET/List all merchant applications
GET/searchSearch merchant applications
GET/{id}Retrieve a merchant application
PATCH/{id}Update a merchant application
DELETE/{id}Delete a merchant application (permanent)
PATCH/{id}/stepsUpdate a merchant application step
DELETE/{id}/stepsDelete a merchant application step
GET/{id}/submission-urlReturn the hosted submission URL
GET/{id}/statusRetrieve the application status
POST/{id}/submitSubmit 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.

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".