Onboarding via API

The entire merchant onboarding can be driven through the wallee Web Service API (v2.0) — ideal if you already hold your customers' company data and want to embed onboarding seamlessly into your platform.

Prerequisites: an application user with an authentication key and the JOIN_PROGRAM_ACCESS permission. All join endpoints expect your account ID in the account header. See the API Reference for authentication (JWT), headers and error handling.

Flow overview

1. Create a partnership for the merchant (affiliate, ISV or existing account).
2. Create a merchant application and submit the KYC data you already have.
3. Hand over to the merchant via the submission URL for review and legal confirmation.
4. Track the application status until the account is active.

sequenceDiagram
    autonumber
    participant P as Your platform
    participant W as wallee
    participant M as Merchant

    P->>W: POST /join-program/partnerships/create-…
    W-->>P: Partnership created
    P->>W: POST /onboarding/merchant-applications
    W-->>P: Application created (draft)
    P->>W: PATCH /merchant-applications/{id} (prefill KYC data)
    P->>W: GET /merchant-applications/{id}/submission-url
    W-->>P: Hosted submission URL
    P->>M: Redirect merchant to submission URL
    M->>W: Review & legally confirm application
    Note over W: KYC / AML checks by wallee
    W-->>P: Status update (GET /status or webhook)
    Note over P,W: Merchant account active

1. Create a partnership

Model	Endpoint
join account (Affiliate)	POST /api/v2.0/join-program/partnerships/create-affiliate
join platform (ISV)	POST /api/v2.0/join-program/partnerships/create-isv
Existing wallee account	POST /api/v2.0/join-program/partnerships/create-simple

Example — create an affiliate partnership:

curl -X POST "https://app-wallee.com/api/v2.0/join-program/partnerships/create-affiliate" \
  -H "Authorization: Bearer <JWT>" \
  -H "account: <YOUR_ACCOUNT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantEmailAddress": "merchant@example.com",
    "pricingProfileSellRateId": 123,
    "subscriptionProductId": 456,
    "emailMessage": "Optional personal message"
  }'

The pricing profile and subscription product IDs come from your partner configuration. You can try this endpoint in the interactive API client.

What happens next differs by model:

• Affiliate — the merchant receives an email with a "Join Program" button and goes through the wallee signup. The partnership is created during that signup and confirmed once signup is finished.
• ISV — the partnership and the sub-account (with a space) are created immediately. The merchant is invited as a user of the new sub-account and receives a confirmation email once they accept the invitation.

All CRUD operations on partnerships (list, retrieve, search, update, delete) are documented in the Partnerships API reference.

2. Submit KYC data (merchant application)

Create a merchant application — either as an empty draft or directly with the full payload (company details, legal form, beneficial owners, etc.):

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... }'

Update an application at any time while it is 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... }'

Because you prefill the application, your customers do not have to re-enter data you already hold. wallee runs the full KYC/AML and PSD2 compliance checks in the background. Applications are structured in steps (company details, beneficial owners, etc.) that can also be updated individually — see the Merchant Applications API reference.

3. Hand over to the merchant

The merchant must review and legally confirm the application themselves. Fetch the hosted submission URL and present it to your customer (e.g. redirect or embedded link):

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

4. Track the status

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

For event-driven integrations, use webhooks to get notified about state changes instead of polling.

Reference

• Merchant Applications API — all application endpoints
• Partnerships API — all partnership endpoints
• Interactive API client
• Data models