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. We ask users to review and refresh their KYC data at defined intervals, which are outlined in this document. This document helps you understand the process, who is and is not concerned, and what can be done to ensure smooth updates for your clients.p

Who is concerned?

All users with an active business relationship and a validated account are required to participate, including the following categories:

📘

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

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:

📘

Note

🧰

Important

The next due date is recalculated:

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

What is updated?

How it works (High Level)

flowchart LR
    A[REQUESTED] --> B[UNDER_ANALYSIS]
    B --> C[ACCEPTED]
    B --> D[REJECTED]
    A --> E[OUTDATED → Restriction]
    D --> B

Status lifecycle

📌 Acceptance is not a status — the requirement disappears.

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": []

→ Restore access

Key Behaviours to Know

• Account status remains ACCEPTED throughout
• KYC Update is handled via requirements & restrictions, not account status
• Users can still complete KYC even if restricted
• Each KYC update generates a new onboarding flow

FAQ (Short Version)

How do I detect a KYC update? → Check requirements or listen to webhook 53

How do I know it's completed? → requirements and restrictions are empty

Can users submit after being blocked? → Yes, via recertification link

Can I manage communication myself? → Yes (disable Lemonway emails and use webhooks)

Summary

KYC Update is a lifecycle process built around:

• Requirements → what needs to be done
• Restrictions → what happens if not done

As a partner, your role is simple:

• Listen to webhooks
• Guide the user
• Trigger the recertification flow

Everything else is handled by Lemonway.