Step 2: B2C Onboarding & Verification

The Onboarding Object

For a B2C marketplace, Lemonway onboarding endpoints let you launch and manage the seller verification journey from your platform, so you are not starting from scratch. The main endpoint to use in our use case is the legal-entity onboarding.

Typical Onboarding flow

1. Start onboarding with POST https://onboarding-api.lemonway.com/onboardings/company.
2. Redirect the user to the Lemonway hosted onboarding URL shown in the response. This can be in the form of a link or button for the merchant.
3. Add documents as requested during the onboarding flow.
4. Use the resume endpoint if the seller exists before completion.

Kick off identity verification

• In our use case Step 1, the Seller's profileStatus returned AWAITING_INFORMATION.
• This means the account has been created, but onboarding is not yet complete.
• The next step is critical before the seller can start trading.
• As shown in our conceptual flow in Step 1, the seller must click the button to begin verification (the onboarding process).

What happens next?

When your platform calls the endpoint for creating a company onboarding, the API returns a JSON response containing a unique onboarding URL, which is our verification button in our use case.

When calling this endpoint, you need to submit the seller's data, along with the accountId Lemonway returned. Everything else is optional. Lemonway collects data directly from the seller during onboarding.

POST https://onboarding-api.lemonway.com/onboardings/company

Minimum Payload Request

{
    "accountId": "a35f9d5a-9d5b-4f1e-86b2-bfd067fd07d1",
    "redirectUrl": "https://www.yourcompany.com/success",
    "legalEntity": {
        "name": "Chloe Rossi Corp",
        "brandName": "Chloe brand",
        "registrationNumber": "246810-357",
        "registrationDate": "2021-06-15",
        "vatNumber": "VAT845726",
        "address": {
            "street": "45 Avenue Victor Hugo",
            "city": "Paris",
            "postalCode": "75008",
            "country": "FR"
        }
    },
    "legalRepresentative": {
        "firstName": "Louis",
        "lastName": "Bianchi",
        "birthDate": "1991-11-03",
        "birthCountry": "FR",
        "email": "[email protected]",
        "phoneNumber": "+33678787878",
        "nationalities": [
            "FR"
        ],
        "address": {
            "country": "PT"
        }
    }
}

Response:

{
  "id": "ff928147-d51e-4f22-b26c-d2c1a2sebd8d",
  "url": "https://onboarding.sandbox.lemonway.com/d6795611-e957-457f-83fc-dd1c03775c08/welcome"
}

This URL is a link to Lemonway’s hosted onboarding platform. Your platform redirects the seller to this URL so they can complete their KYC/KYB (Know Your Business) process, upload documents, and provide company details in a secure environment.
In our use case, the seller has completed step 1, and now they need to click the button to start the verification. This links to the Lemonway onboarding interface.

Conceptual View 3: The Seller's Journey - Start Onboarding

👍

Lemontip

You can rebrand the Online Onboarding interface with your platform colours, your company logo, buttons and links from the Dashboard. See: Onboarding Branding

From this point on, the merchant completes their KYB on Lemonway hosted pages. The process auto-saves as they go, and they can leave and come back at any point without losing progress. Lemonway reviews the submitted documents and either approves or denies the account.

Which documents does the seller need to provide?

For a legal entity to pass KYB, Lemonway requires the following core documents, the seller will be asked to provide these documents during the onboarding flow:

• A valid ID document for the legal representative of the company
• A valid ID document for each beneficial owner holding more than 25% of the company
• A certificate of incorporation (Kbis in France) dated less than three months old
• The company's signed Articles of Association
• A beneficial ownership register (type DBE-S1) showing individuals who own or control more than 25% of the shares
• Shareholding Structure

👍

Documents Acdepted

We accept KYC documents in French, English, Spanish, Italian and German. For other countries, we require an official translation in one of the above listed languages. ​

📘

Note

In some cases, Lemonway may request additional documents. All documents must be legible, undamaged, and not expired, blurry, pixelated, or cropped submissions will be refused.

Important Status Information

When managing accounts and onboarding, it is important to understand the different statuses you will encounter in the Dashboard or from webhooks to your systems. Each status dictates what actions you or your user (seller) should take next.

Conceptual View 4: The Seller's Journey - Onboarding Under Analysis

📘

Note

The average oboarding is between 24hrs to 48hrs. During this time the merchant is able to create a catalog of good / services however they should not be allowed to start selling.

Seller approved - wallet is ready

Once verification passes, two things happen automatically:

• You will receive a webhook when the account status changes to ACCEPTED. This is visible in the Dashboard profile name.
• A wallet is created and linked to the merchant.

The good news is that the merchant can now receive funds, meaning that they are officially open for business on your marketplace platform.

Conceptual View 4: The Seller's Journey - Onboarding Accepted

Setting up a Seller's bank account API

To request a Pay-Out on a payment account, the payment account must first be linked to a bank account.

Step 1 Register the bank account details

Provide the seller's bank account details using POST: /v2/moneyouts/iban end point.

• Register the main IBAN for the payment account.
• Optionally register an additional bank account if needed.

Step 2 — Upload the proof of IBAN

Upload a supporting bank document using the POST: v2/accounts/{accountid}/documents/upload..

• For proof of IBAN, use document type 2.

Validation requirements

The following rules apply for validation:

• The bank account holder must match the payment account holder.
• For legal entities, only the company bank account is accepted.
• The document must clearly show:
  • account number / IBAN
  • account holder full name
  • bank name or logo

Accepted documents include:

• Proof of IBAN / bank account document
• Bank statement
• Digital bank screenshot (if all required fields are visible)

KYC review

KYC review is typically completed within 48 hours.

Checks performed:

1. The account number submitted via API matches the one shown on the proof.
2. The payment account holder matches the bank account holder shown on the proof.

👍

Information

Keep the account holder name exactly as it appears on official bank records to avoid KYC mismatch.

Setting up a seller's bank account in the Dashboard

To add a bank account in the Lemonway Dashboard, do this:

1. Go to Wallets in the left menu.
2. Open the target wallet/entity.
3. Click the Bank accounts tab.
4. Click + Add bank account (top right).

Then complete the wizard:

Step 1 — Bank account holder

• Choose whether the wallet holder is also the bank account holder (Yes/No).
• Fill in holder details (company/name, address, city, postal code, country).
• Click Continue.

Step 2 — Bank country

• Select the country where the bank account is held.
• Click Continue.

Step 3 — Bank account

• Enter bank details (typically IBAN/account number, BIC/SWIFT, account type, and any local fields like sort code/routing if requested).
• Click Continue.

Step 4 — Confirmation

• Review everything.
• Confirm to create the bank account.

After saving, the account appears in the Bank accounts list for that wallet. The bank account still has to be reviewed by our KYC team?.

Step 5 - Upload Bank account documents

To upload documents related to the bank account, go to the Documents tab on the seller's wallet page:

• Click the Add Documents button.
• Select 2 Bank Statements from the menu.
• Upload the related documentation.

Onboarding Link: Using Lemonway Dashboard

To generate an onboarding link via the interface, you must first create an account. Creating an account via the Lemonway Dashboard is straightforward and is the easiest way to get started in your environment.

However, you should really only use this method if you are creating a small number of accounts and have not yet industrialized the account creation process on your platform. You will require specific information for the Legal Entity or individuals for whom you are creating the account.

1. Sign in to your account.
2. Click Accounts.
3. Click Accounts list (this will display all accounts in your environment).
4. Click Create Account and select the account type you want to create from the list.
5. After completing the account creation form, you will be prompted with the option to create an onboarding link immediately. Alternatively, you can use the Account List: Navigate to the Accounts List table, click on the specific Account ID, and select the option to create a link from the account details page.

Onboarding Webhooks: Using Lemonway Dashboard

A dedicated page explains how to set up Account and Onboarding webhooks here. These can be configured in your environment from the Lemonway Dashboard.

Two important webhooks:

1. Webhook Event ID: 49 for Account creation and status updates
2. Webhook Event ID: 50 for Onboarding Profile Statuses

Implementation Steps

• Set Up Webhooks: Configure webhook endpoints to receive notifications for both account and profile status changes.
• Handle Notifications: Implement logic to process different notification types and update your systems accordingly.
• Monitor Status Continuously Regularly check account and profile statuses to ensure onboarding is progressing as expected.

👍

Lemontip

Enable these notifications in the Dashboard to receive all required account and document updates for your end users.

Delivery options include: email (HTML) or webhooks/callbacks (HTTP POST or GET).