Introduction

This guide details how to integrate Lemonway’s webhook notifications into your application to manage both individual and/or legal entity onboarding. It encompasses the entire flow—from account creation to final status updates and includes best practices for ensuring reliability.

Overview

Webhooks let Lemonway notify your application when important events occur, such as account creation, profile status changes, and KYC compliance decisions. By listening for these events, you can:

• Track onboarding progress in near real-time.
• Update your internal records and user interfaces automatically.
• Take appropriate actions (e.g., sending reminders or restricting functionality) if the onboarding stalls or is denied.

Account Creation and Status

Endpoints

• Individual Accounts: POST /accounts/individual
• Legal Entity Accounts: POST /accounts/legal-entity

Typical Flow

1. Create an Account: You call the relevant endpoint to register an individual or legal entity.
2. Account Creation Response: Lemonway responds with:
   • accountId: The unique identifier for the account.
   • accountStatus: Usually created, meaning the account was created.
3. Possible Account Status Values:
   • created: Account is successfully registered but not yet validated.
   • accepted: Account is activated; a wallet is created. Onboarding is complete.
   • denied: Account is refused due to regulatory or compliance reasons. Onboarding process ends.

Webhook Notifications (ID: 50)

When an account status changes, a webhook is sent:

{
  "EventDate": "2025-03-14T16:44:55.883",
  "AccountID": "37373",
  "ProfileID": "93843",
  "IntId": "32",
  "ExtId": "jdkc",
  "Status": "2"
}

Where Status can be:

• 1 = Created
• 2 = Accepted
• 3 = Denied

Onboarding Profiles

Onboarding Endpoints

If the account requires additional data, call one of the onboarding endpoints:

• POST /onboardings/individual
• POST /onboardings/company
• POST /onboardings/association
• POST /onboardings/sole-trader

Response:

• onboardingID: Unique ID
• onboardingUrl: A link for collecting further information and documentation.

Profile Status

Once the onboarding is initiated, a profile is created to track the specific onboarding steps. Lemonway will notify you when the profile progresses through various stages.

Common Profile Statuses:

1. creation_in_progress: No onboarding required.
2. awaiting_information: Onboarding required.
3. information_collection_in_progress: The end-user is in the process of providing data/documents.
4. identity_verification_in_progress: The end-user is completing an identity verification workflow.
5. under_analysis: The end-user has submitted the form, and Lemonway’s team is reviewing.
6. accepted: Lemonway approved the profile.
7. denied: Lemonway declined onboarding.
8. rejected: Additional info is still needed; the end-user must resubmit.

Webhook Notifications (ID: 49)

When a profile status changes, a webhook is sent:

{
  "EventDate": "2025-03-14T16:44:55.883",
  "AccountID": "37373",
  "ProfileID": "454545",
  "IntId": "32",
  "ExtId": "jdkc",
  "Status": "2"
}

Where Status can be:

• 1 = Onboarding in progress
• 2 = Under analysis
• 3 = Accepted
• 4 = Denied
• 5 = Rejected

Webhook Handling Strategy

1. Set Up Webhook Endpoints: Configure URL endpoints in your system to receive the Account status (ID 50) and Profile status (ID 49) notifications.
2. Authentication & Security:
   • Use HTTPS and verify that requests originate from Lemonway.
3. Process Incoming Webhooks:
   • Parse the JSON payload.
   • Identify the Status and update your database records.
4. Follow Up:
   • If Status is accepted, enable relevant user functionality.
   • If Status is denied, notify the user or mark the process as closed.
   • If Status is rejected, prompt the user to provide missing documents.
5. Error Handling:
   • Implement retries and handle potential duplicate notifications.
   • Store logs for troubleshooting.

Best Practices

• Perform a GET after receiving a notification if real-time accuracy is crucial, as some notifications may arrive with a delay.
• Poll if Needed: If webhooks are delayed, consider periodic checks for status updates.
• Track Timelines: KYC processing may take minutes or up to 48 hours.

By integrating Lemonway webhooks effectively, you ensure that your platform remains in sync with the latest onboarding events. This reduces friction for end-users and helps maintain compliance with regulatory requirements. If you have any questions about handling specific statuses or require further assistance, consult the official Lemonway documentation or contact our support team.