How do I handle KYC Updates?

What is it?

KYC updates are a core component of maintaining accurate user records at Lemonway, forming part of an ongoing, periodic process that ensures compliance and data integrity throughout the entire account lifecycle. As part of the process, we invite users to review and refresh their KYC data at the defined intervals outlined in this document. This document helps understand the process and outlines who is and is not concerned, and what can be done to ensure smooth updates for your clients.

Who is concerned?

All users with an active business relationship and a validated account are required to participate. Categories include:

📘

Note

• Migrated Accounts: Clients that have opened a payment account before the online onboarding activation and that have been linked to an Account via the migration process are included in the KYC Update process.
• Premium Accounts: Included in the KYC Update process with specific communication workflow. See your account manager.

Who is excluded?

• Users with technical wallets only
  • Buyers
  • Donors
  • Operators
  • Payers *(Visa Application account activity))

KYC Refresh Rate

KYC updates at Lemonway are based on an event-driven model. Rather than being fixed at onboarding, the next KYC update due date evolves throughout the account lifecycle. Each time a relevant event occurs, the system:

• Identifies a reference date (linked to the triggering event).
• Applies the current risk level of the end-user.
• Recalculates the next KYC Update due date accordingly.

Why is this essential?

It ensures that KYC obligations remain:

• Aligned with Lemonway's regulatory requirements.
• Information changes according to the latest risk profile.
• Information is synchronised with the most recent business activity.

KYC refresh depends on the risk level associated with the account holder.

🧰

Important

The next due date is recalculated:

• After each KYC validation
• If risk level changes
• If the account structure changes

What information is updated?

📘

Note

The data collected depends on the user profile and is gathered as part of the onboarding process. If an account includes multiple profiles, all information collected during onboarding (both at account creation and when adding profiles) will be included in the KYC update form.

Rules

How it works (High Level)

KYC Update Status Flow

The KYC Update process follows a structured lifecycle, where each request moves through a series of statuses until it reaches an outcome or a restriction state.

API Overview

Account object additions

{
  "requirements": [
    {
      "id": "uuid",
      "type": "KYC_UPDATE",
      "dueDate": "2026-04-11T18:01:33.908Z",
      "status": "REQUESTED"
    }
  ],
  "restrictions": [
    {
      "id": "uuid",
      "category": "KYC",
      "reason": "KYC_OUTDATED",
      "activatedAt": "2026-03-12T19:02:06.269Z",
      "requirementIds": ["uuid"]
    }
  ]
}

Key endpoints

GET /accounts
GET /accounts/{id}
GET /onboardings/{onboardingId}/resume

• requirements → track KYC update progress
• restrictions → indicate account limitations

Webhooks

Requirement updates (Notification 53)

Triggered on any status change:

{
  "Type": "KYC_UPDATE",
  "Status": "REQUESTED",
  "NotifCategory": "53",
  "RequirementID": "uuid",
  "AccountID": "uuid",
  "DueDate": "2026-01-12"
}

Restriction updates (Notification 54)

Triggered when the account is restricted:

{
  "Category": "KYC",
  "Reason": "KYC_OUTDATED",
  "NotifCategory": "54",
  "RestrictionID": "uuid",
  "AccountID": "uuid",
  "RequirementIDs": ["uuid"]
}

Account Restriction Logic

If KYC is not completed before the deadline:

→ Account becomes KYC_OUTDATED

Two modes

Example restriction logic

Investors / Lenders

{
  payIn: 0,
  payOut: 0,
  p2pOut: 0,
  p2pIn: "allowed"
}

Project Holders

{
  payIn: "allowed",
  payOut: 0,
  p2pOut: "allowed",
  p2pIn: 0
}

📌 Custom rules can be configured per partner.

Recertification Link

Used to redirect users to complete their KYC update.

GET /onboardings/{onboardingId}/resume

Rules

• Valid for 7 days
• Single-use
• Can be regenerated anytime

Partner Responsibilities

On REQUESTED

• Generate and share the recertification link
• Monitor due date

On UNDER_ANALYSIS

• Update UI (e.g. "Under review")

On REJECTED

• Notify user to resubmit

On KYC_OUTDATED

• Block or restrict user actions
• Prompt immediate completion

On completion

• Detect:

"requirements": []
"restrictions": []