KYB/KYC Verification Integration... Frontend

[ManuelJG1999]

Frontend: KYB/KYC Verification Integration

Depends on: Backend KYB workflow (POST /kyb/session, GET /kyb/status/:organizationId)

Task Description

Connect the frontend to the backend KYB/KYC verification workflow so business users can start verification and see their status before creating high-value / enterprise agreements. The backend exposes a provider-agnostic Identity Provider abstraction; the frontend must consume it without knowing the specific provider.

Background / Current State

• The Thalos frontend already has a shared API client pattern in lib/api/ (each module reuses an apiRequest/apiClient helper and returns the { success, data, error } shape).
• Business features live in app/dashboard/business/page.tsx; the profile gating is already based on the business profile check.
• No KYB/KYC UI or client exists yet.

Deliverable

A KYB verification UI flow integrated with the backend endpoints, plus a status gate on enterprise agreement creation.

Requirements

• New lib/api/kyb.ts client (reusing the shared API client) with:
  • startKybSession() → POST /kyb/session
  • getKybStatus(organizationId) → GET /kyb/status/:organizationId
• A verification screen/section that:
  • Collects/displays business name, registration number, country.
  • Starts a verification session and handles the provider redirect/embedded flow.
  • Shows status states: pending, in_review, verified, rejected.
• A gate: block fund deposits / enterprise agreement creation unless status is verified, with a clear call to action to complete KYB.

Validation System

• Starting a session calls POST /kyb/session and transitions the UI to in_review.
• Status polling/refresh reflects verified/rejected from GET /kyb/status/:organizationId.
• Enterprise agreement creation is blocked when status is not verified.

Technical Requirements

• Reuse the shared apiRequest/apiClient (do not create a new fetch helper).
• Keep the UI provider-agnostic (no hardcoded provider assumptions).
• Handle loading/error and expired-session states.
• Gate lives in the business dashboard flow (app/dashboard/business/page.tsx), consistent with the existing business-profile check.

Additional Notes

Pairs with the backend KYB issue. Individual KYC (person) can reuse the same client pattern if a /kyc/* counterpart exists later.

Testing (required)

• Component/unit test: the KYB client calls the correct endpoints and maps the four status states.
• UI test: session start moves the UI to in_review; status refresh reflects verified/rejected.
• Gate test: enterprise agreement creation / fund deposit is blocked unless verified.
• Error-state test: expired/failed session shows a clear recovery CTA.

Proof of Completion (required)

• Link the merged PR.
• Attach screenshots/recording of the full flow: start → in_review → verified, plus the blocked-until-verified gate.
• Paste passing test output.
• Confirm (link/diff) that lib/api/kyb.ts reuses the shared API client, not a new fetch helper.

[ciynthia]

I'm interested in working on this issue. I have experience building secure, scalable backend systems and implementing authentication, data persistence, and API integrations. I'll deliver a clean, well-tested implementation that meets the acceptance criteria and project standards.

[Lspnjr1]

Hi @maintainers,

I’m Lspnjr1

I can implement the frontend integration for the KYB/KYC verification flow by connecting the UI to the backend verification endpoints. I’ll handle session creation, redirect users into the verification process, poll or refresh verification status, and update the interface based on the returned state. I’ll also add appropriate loading, success, and error states to provide a smooth user experience and ensure the verification flow works seamlessly end-to-end with the backend KYB workflow.

[Johnpii1]

Hello,

I'd like to work on this issue.

I have experience building Next.js and TypeScript applications, integrating frontend workflows with REST APIs, and implementing secure onboarding flows. I'm comfortable working with shared API client patterns and building provider-agnostic interfaces that integrate cleanly with backend services.

For this task, I will:

Create a new lib/api/kyb.ts client that reuses the existing shared apiRequest/apiClient pattern.
Implement:
startKybSession() → POST /kyb/session
getKybStatus(organizationId) → GET /kyb/status/:organizationId
Build a KYB verification interface that:
Collects and displays business information (business name, registration number, and country).
Starts a verification session through the backend.
Supports the provider redirect or embedded verification flow without introducing provider-specific logic.
Displays the verification states: pending, in_review, verified, and rejected.
Handle loading, error, and expired-session states with clear recovery actions.
Integrate a verification gate into app/dashboard/business/page.tsx that prevents enterprise agreement creation and fund deposits until the organization is verified.
Ensure the gate follows the existing business profile verification flow and maintains a consistent user experience.

Before submitting the pull request, I will:

Add unit tests verifying the KYB client calls the correct endpoints and correctly maps all status states.
Add UI tests covering:
Session creation transitioning the UI to in_review.
Status refresh updating the UI to verified or rejected.
Blocking enterprise agreement creation and fund deposits when verification is incomplete.
Error and expired-session recovery flows.
Verify that lib/api/kyb.ts reuses the existing shared API client rather than introducing a new fetch helper.
Ensure all project checks pass successfully.
Include Closes # in the PR description.

Thank you for considering my application!

[Glam26]

I'd be happy to take this on.

My plan is to:

Review the current implementation and reproduce the reported behavior.
Implement the requested changes while keeping them aligned with the project's existing patterns and conventions.
Update or add tests to cover the new behavior and prevent regressions.
Run formatting, linting, tests, and the build to ensure everything passes before submitting a PR.

If I encounter any design tradeoffs, I'll document them clearly in the PR description.

[Emmy6654]

Hi Team,

I am writing to apply for the task of building out our Frontend KYB/KYC Verification Integration.

User onboarding and identity verification are critical trust boundaries for our platform. From an engineering standpoint, compliance flows must balance strict user data security with an intuitive, frictionless user experience. Drop-offs during identity verification directly impact conversion rates, while improper handling of sensitive documents or status states can cause significant operational headaches.

I will build a clean, responsive, and type-safe verification workflow using React, TypeScript, and modern state management that guides users seamlessly through document submission, business verification (KYB), and identity checks (KYC) with clear error handling and real-time status tracking.

[Gozirimdev]

Hi Maintainer , I have reviewed this and it is something I can handle please can I work on this ?

[grantfox-oss]

🦊 GrantFox — @Johnpii1 has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #100)
2. Your PR will be reviewed by the Thalos-Infrastructure maintainers

Good luck! Track your progress on GrantFox.

[ManuelJG1999]

🎉 Congratulations @Johnpii1 ! This issue has been assigned to you.

Before you start, make sure you understand the requirements. If you have any questions, ask us in our community chat:
https://t.me/ThalosOSSCommunity

Please keep us updated on your progress. If there's no activity or communication within 48 hours, the issue may be reassigned to another contributor.

Happy coding, and thanks for contributing to Thalos! 🐉