Skip to content

VERO Compliance (KYC) - Use Case Documentation

📋 Table of Contents

  1. System Overview
  2. System Architecture
  3. Actors and Roles
  4. Use Case Catalog
  5. KYC Management
  6. Risk Management
  7. Transaction Monitoring
  8. Case Management
  9. Alert Management
  10. Workflow Configuration
  11. Questionnaire Management
  12. Document Management
  13. Administration
  14. API Integration
  15. Use Case Details

System Overview

Purpose

MetaKYC is a comprehensive Know Your Customer (KYC) and Anti-Money Laundering (AML) compliance platform designed to help financial institutions, fintech companies, and other regulated entities manage customer due diligence, risk assessment, transaction monitoring, and regulatory compliance.

Components

  • Host API: RESTful API backend built with ABP Framework (.NET Core)
  • Admin Panel: Next.js/React web application for compliance officers and administrators
  • MVC Web: ASP.NET MVC application for legacy admin functionality

Key Capabilities

  • Multi-tenant SaaS architecture
  • Flexible workflow engine for KYC processes
  • Risk-based compliance assessment
  • Real-time transaction monitoring
  • Case management for compliance decisions
  • Integration with third-party verification providers (Sumsub, Sardin, Onfido)
  • Automated alert generation and escalation
  • Comprehensive audit logging

System Architecture

┌─────────────────────────────────────────────────────────────┐
│                    External Systems                          │
│  (Client Applications, Third-party Providers, Webhooks)      │
└───────────────────────┬─────────────────────────────────────┘
                        │
                        ↓ REST API / Webhooks
┌─────────────────────────────────────────────────────────────┐
│                    Host API (Backend)                        │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  Application Services Layer                          │  │
│  │  • Applicant Management  • Risk Scoring              │  │
│  │  • Transaction Monitoring • Alert Management         │  │
│  │  • Case Management       • Workflow Engine           │  │
│  │  • Questionnaires        • Document Management       │  │
│  └──────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  Domain Layer (Business Logic & Rules)               │  │
│  └──────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  Entity Framework Core + SQL Server                  │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                        ↑
                        │ HTTPS / JWT Auth
                        │
┌─────────────────────────────────────────────────────────────┐
│              Admin Panel (Frontend)                          │
│  • Dashboard         • KYC Management                        │
│  • Risk Management   • Transaction Monitoring                │
│  • Case Management   • Alert Management                      │
│  • Configuration     • User Management                       │
└─────────────────────────────────────────────────────────────┘

Actors and Roles

Primary Actors

1. Host Administrator (Super Admin)

  • Description: System-wide administrator managing the entire platform
  • Access Level: Full system access across all tenants
  • Responsibilities:
  • Tenant management and provisioning
  • System configuration
  • Feature management per tenant
  • Global user management
  • Infrastructure monitoring

2. Tenant Administrator

  • Description: Organization-level administrator managing a single tenant
  • Access Level: Full access within their tenant
  • Responsibilities:
  • User and role management
  • Workflow configuration
  • Risk criteria setup
  • Provider configuration
  • Organization settings

3. Compliance Officer

  • Description: Operational staff managing KYC and compliance processes
  • Access Level: Operational access to compliance functions
  • Responsibilities:
  • Review applicant submissions
  • Make compliance decisions
  • Manage cases and alerts
  • Generate compliance reports
  • Monitor risk assessments

4. Case Manager

  • Description: Specialist handling complex compliance cases
  • Access Level: Case management and decision-making
  • Responsibilities:
  • Investigate flagged applicants
  • Make case decisions (approve/reject/escalate)
  • Document case actions
  • Coordinate with other departments
  • Handle escalated cases

5. Risk Analyst

  • Description: Specialist focused on risk assessment and monitoring
  • Access Level: Risk management and transaction monitoring
  • Responsibilities:
  • Configure risk scoring rules
  • Monitor transaction alerts
  • Analyze risk patterns
  • Update risk criteria
  • Generate risk reports

6. Auditor

  • Description: Internal or external auditor reviewing compliance activities
  • Access Level: Read-only access to audit logs and reports
  • Responsibilities:
  • Review audit logs
  • Generate compliance reports
  • Verify regulatory adherence
  • Document audit findings

Secondary Actors

7. API Client / Tenant Client

  • Description: External system or application integrating with MetaKYC
  • Access Level: API access with API key authentication
  • Responsibilities:
  • Submit KYC applications
  • Retrieve applicant status
  • Receive webhook notifications
  • Query compliance data

8. Applicant (End User)

  • Description: Individual or company undergoing KYC verification
  • Access Level: Limited access to submission and status
  • Responsibilities:
  • Provide personal information
  • Upload required documents
  • Complete questionnaires
  • Respond to information requests

9. Third-party Provider Systems

  • Description: External verification services (Sumsub, Sardin, Onfido)
  • Access Level: API integration with webhook callbacks
  • Responsibilities:
  • Perform identity verification
  • Conduct transaction monitoring
  • Send verification results
  • Provide risk assessments

Use Case Catalog

KYC Management

ID Use Case Primary Actor Priority
UC-KYC-001 Create Natural Person Application Compliance Officer / API Client High
UC-KYC-002 Create Legal Entity Application Compliance Officer / API Client High
UC-KYC-003 Review Applicant Progress Compliance Officer High
UC-KYC-004 Update Applicant Status Compliance Officer High
UC-KYC-005 Search and Filter Applicants Compliance Officer Medium
UC-KYC-006 View Applicant Details Compliance Officer High
UC-KYC-007 Manage Company Representatives Compliance Officer Medium
UC-KYC-008 Manage Company UBOs Compliance Officer Medium
UC-KYC-009 Request Additional Information Compliance Officer Medium
UC-KYC-010 Cancel Application Compliance Officer Low

Risk Management

ID Use Case Primary Actor Priority
UC-RISK-001 Configure Risk Scoring Plans Risk Analyst High
UC-RISK-002 Define Risk Criteria Risk Analyst High
UC-RISK-003 Set Risk Weights and Thresholds Risk Analyst High
UC-RISK-004 Evaluate Applicant Risk Score System / Risk Analyst High
UC-RISK-005 View Risk Assessment Results Compliance Officer High
UC-RISK-006 Override Risk Assessment Risk Analyst Medium
UC-RISK-007 Configure Risk Providers Tenant Administrator Medium
UC-RISK-008 Generate Risk Reports Risk Analyst Medium
UC-RISK-009 Map Risk Criteria to Countries Risk Analyst Low
UC-RISK-010 Review High-Risk Applicants Compliance Officer High

Transaction Monitoring

ID Use Case Primary Actor Priority
UC-TXN-001 Submit Transaction for Monitoring API Client High
UC-TXN-002 Configure Monitoring Rules Risk Analyst High
UC-TXN-003 Configure External Provider Tenant Administrator Medium
UC-TXN-004 Evaluate Transaction Against Rules System High
UC-TXN-005 Generate Transaction Alert System High
UC-TXN-006 Review Transaction Alerts Risk Analyst High
UC-TXN-007 Process Provider Webhook System High
UC-TXN-008 View Transaction History Compliance Officer Medium
UC-TXN-009 Test Monitoring Configuration Tenant Administrator Low
UC-TXN-010 Generate Transaction Reports Risk Analyst Medium

Case Management

ID Use Case Primary Actor Priority
UC-CASE-001 Create Case for Applicant System / Compliance Officer High
UC-CASE-002 Assign Case to Officer Case Manager High
UC-CASE-003 Review Case Details Case Manager High
UC-CASE-004 Make Case Decision Case Manager High
UC-CASE-005 Add Case Notes Case Manager Medium
UC-CASE-006 Escalate Case Case Manager Medium
UC-CASE-007 Request Additional Documents Case Manager Medium
UC-CASE-008 Close Case Case Manager High
UC-CASE-009 View Case History Compliance Officer Medium
UC-CASE-010 Generate Case Reports Case Manager Low

Alert Management

ID Use Case Primary Actor Priority
UC-ALERT-001 Configure Alert Rules Risk Analyst High
UC-ALERT-002 Define Alert Conditions Risk Analyst High
UC-ALERT-003 Generate Automatic Alert System High
UC-ALERT-004 View Alert Dashboard Compliance Officer High
UC-ALERT-005 Review Alert Details Compliance Officer High
UC-ALERT-006 Acknowledge Alert Compliance Officer Medium
UC-ALERT-007 Resolve Alert Compliance Officer High
UC-ALERT-008 Create Case from Alert Compliance Officer High
UC-ALERT-009 Configure Alert Notifications Tenant Administrator Low
UC-ALERT-010 Search and Filter Alerts Compliance Officer Medium

Workflow Configuration

ID Use Case Primary Actor Priority
UC-WF-001 Create KYC Workflow Tenant Administrator High
UC-WF-002 Configure Workflow Steps Tenant Administrator High
UC-WF-003 Set Step Order and Dependencies Tenant Administrator Medium
UC-WF-004 Configure Step Types Tenant Administrator High
UC-WF-005 Define Workflow Rules Tenant Administrator High
UC-WF-006 Set Rule Conditions Tenant Administrator Medium
UC-WF-007 Activate/Deactivate Workflow Tenant Administrator Medium
UC-WF-008 Clone Workflow Tenant Administrator Low
UC-WF-009 Test Workflow Logic Tenant Administrator Medium
UC-WF-010 Map Workflow to Applicant Type Tenant Administrator High

Questionnaire Management

ID Use Case Primary Actor Priority
UC-QUEST-001 Create Questionnaire Tenant Administrator High
UC-QUEST-002 Define Question Groups Tenant Administrator Medium
UC-QUEST-003 Add Questions Tenant Administrator High
UC-QUEST-004 Set Question Types Tenant Administrator Medium
UC-QUEST-005 Configure Conditional Logic Tenant Administrator Low
UC-QUEST-006 Map Questionnaire to Countries Tenant Administrator Medium
UC-QUEST-007 Assign to Workflow Step Tenant Administrator High
UC-QUEST-008 Review Questionnaire Responses Compliance Officer High
UC-QUEST-009 Create Appropriateness Test Tenant Administrator Medium
UC-QUEST-010 Evaluate Test Results System High

API Integration

ID Use Case Primary Actor Priority
UC-API-001 Generate API Key Tenant Administrator High
UC-API-002 Submit Applicant via API API Client High
UC-API-003 Query Applicant Status API Client High
UC-API-004 Receive Webhook Notification API Client High
UC-API-005 Submit Transaction via API API Client High
UC-API-006 Retrieve Risk Assessment API Client Medium
UC-API-007 Update Applicant Data API Client Medium
UC-API-008 Query Workflow Progress API Client Medium
UC-API-009 Upload Documents via API API Client Medium
UC-API-010 Authenticate API Request System High

Use Case Details

UC-KYC-001: Create Natural Person Application

Primary Actor: Compliance Officer / API Client
Scope: KYC Management
Level: User Goal
Stakeholders: Compliance team, applicant, business operations

Description

Submit a new KYC application for an individual person through the admin panel or API, initiating the verification workflow.

Preconditions

  • User is authenticated and has appropriate permissions
  • At least one workflow is configured for natural persons
  • Tenant has necessary provider configurations

Main Success Scenario

  1. User initiates new applicant creation
  2. System displays applicant form with required fields
  3. User selects target workflow
  4. User enters applicant information:
  5. First name, last name
  6. Date of birth
  7. Nationality
  8. Contact information
  9. Address details
  10. User submits the application
  11. System validates input data
  12. System creates applicant record
  13. System initializes workflow progress
  14. System triggers first workflow step
  15. System returns applicant ID and initial status
  16. System sends notification to configured webhooks

Postconditions

  • Applicant record created in database
  • Workflow progress initialized
  • Initial workflow step triggered
  • Audit log entry created
  • Webhook notification sent (if configured)

Alternative Flows

  • 3a. No workflow available: System displays error, prompts admin to create workflow first
  • 6a. Validation fails: System displays validation errors, user corrects and resubmits
  • 9a. First step is Identity SDK: System calls external provider for identity verification

Business Rules

  • Email and phone number must be unique per tenant
  • Date of birth must indicate applicant is at least 18 years old
  • All mandatory fields must be provided
  • Workflow must be active and applicable to natural persons

Non-functional Requirements

  • Response time: < 2 seconds for creation
  • API rate limit: 100 requests per minute per API key
  • Data encryption: All PII encrypted at rest

Primary Actor: Compliance Officer / API Client
Scope: KYC Management
Level: User Goal
Stakeholders: Compliance team, company applicant, business operations

Description

Submit a new KYC application for a company or legal entity, including company details, representatives, directors, and ultimate beneficial owners (UBOs).

Preconditions

  • User is authenticated and has appropriate permissions
  • At least one workflow is configured for legal entities
  • Company registration documents available

Main Success Scenario

  1. User initiates new company applicant creation
  2. System displays company application form
  3. User selects target workflow
  4. User enters company information:
  5. Company name and registration number
  6. Country of incorporation
  7. Business type and industry
  8. Registered address
  9. User adds company representatives:
  10. Name, position, contact details
  11. Authorized signatory status
  12. User adds directors (if applicable)
  13. User adds Ultimate Beneficial Owners (UBOs):
  14. Name, ownership percentage
  15. Control type (direct/indirect)
  16. User submits the application
  17. System validates all data
  18. System creates company applicant record
  19. System creates related entity records (representatives, directors, UBOs)
  20. System initializes workflow progress
  21. System triggers first workflow step
  22. System returns company applicant ID
  23. System sends webhook notification

Postconditions

  • Company applicant record created
  • All related entities (representatives, directors, UBOs) created
  • Workflow progress initialized
  • Audit log entries created
  • Webhook notification sent

Alternative Flows

  • 9a. Validation fails: System displays errors, user corrects data
  • 11a. UBO ownership < 100%: System displays warning but allows submission
  • 13a. Representative KYC required: System creates child applicant records for each representative

Business Rules

  • Company must have at least one authorized representative
  • Total UBO ownership should equal 100%
  • At least one UBO with ≥25% ownership must be identified
  • Each UBO may trigger individual KYC verification

UC-RISK-001: Configure Risk Scoring Plans

Primary Actor: Risk Analyst
Scope: Risk Management
Level: User Goal
Stakeholders: Compliance team, management, regulators

Description

Create and configure risk scoring plans that define how applicants are assessed for risk levels based on various criteria.

Preconditions

  • User has risk management permissions
  • Risk criteria are defined in the system

Main Success Scenario

  1. Risk Analyst navigates to Risk Management > Scoring Plans
  2. System displays existing scoring plans
  3. Analyst clicks "Create Scoring Plan"
  4. System displays plan configuration form
  5. Analyst enters:
  6. Plan name and description
  7. Applicable entity type (natural person/company)
  8. Risk level thresholds:
    • Low risk: 0-30 points
    • Medium risk: 31-60 points
    • High risk: 61-100 points
  9. Analyst adds risk criteria:
  10. Selects criteria (e.g., "Country Risk")
  11. Sets weight (e.g., 20%)
  12. Defines scoring rules
  13. Analyst repeats step 6 for all criteria
  14. System validates total weight = 100%
  15. Analyst saves the plan
  16. System creates risk scoring plan
  17. System displays success message
  18. Plan becomes available for workflow configuration

Postconditions

  • Risk scoring plan created and active
  • Plan available for assignment to workflows
  • Audit log entry created

Alternative Flows

  • 8a. Total weight ≠ 100%: System displays error, analyst adjusts weights
  • 9a. Plan name already exists: System displays error, analyst changes name

Business Rules

  • Total weight of all criteria must equal 100%
  • At least one criterion must be defined
  • Risk thresholds must not overlap
  • Low risk threshold must start at 0
  • High risk threshold must end at 100

UC-TXN-002: Configure Monitoring Rules

Primary Actor: Risk Analyst
Scope: Transaction Monitoring
Level: User Goal
Stakeholders: Risk team, compliance team, management

Description

Create and configure transaction monitoring rules that automatically flag suspicious transactions based on defined conditions.

Preconditions

  • User has transaction monitoring permissions
  • Transaction types are defined

Main Success Scenario

  1. Risk Analyst navigates to Transaction Monitoring > Rules
  2. System displays existing monitoring rules
  3. Analyst clicks "Create Rule"
  4. System displays rule configuration form
  5. Analyst enters:
  6. Rule name and description
  7. Rule type (velocity, threshold, pattern)
  8. Severity level (low, medium, high, critical)
  9. Analyst configures conditions:
  10. For Velocity Rule:
    • Number of transactions
    • Time window (e.g., 10 transactions in 24 hours)
  11. For Threshold Rule:
    • Amount threshold (e.g., > $10,000)
    • Currency
  12. For Pattern Rule:
    • Transaction pattern to detect
  13. Analyst sets alert action:
  14. Generate alert
  15. Create case automatically
  16. Send notification
  17. Analyst sets rule priority
  18. Analyst activates the rule
  19. System validates configuration
  20. System saves the rule
  21. Rule becomes active for new transactions

Postconditions

  • Monitoring rule created and active
  • Rule will evaluate future transactions
  • Audit log entry created

Alternative Flows

  • 10a. Validation fails: System displays errors, analyst corrects configuration
  • 12a. Testing mode: Analyst can test rule before activation

Business Rules

  • Rule name must be unique
  • At least one condition must be defined
  • Threshold amounts must be positive
  • Time windows must be reasonable (1 hour to 365 days)
  • Critical rules must create cases automatically

UC-CASE-004: Make Case Decision

Primary Actor: Case Manager
Scope: Case Management
Level: User Goal
Stakeholders: Compliance team, applicant, management

Description

Review a compliance case and make a final decision on the applicant's status (approve, reject, request more information, or escalate).

Preconditions

  • Case exists and is assigned to the case manager
  • All required information has been gathered
  • Case is in "InReview" or "InProgress" status

Main Success Scenario

  1. Case Manager opens case details
  2. System displays:
  3. Applicant information
  4. Risk assessment results
  5. Alert history
  6. Document review status
  7. Previous case notes
  8. Case Manager reviews all information
  9. Case Manager makes decision:
  10. Option A: Approve
  11. Option B: Reject
  12. Option C: Request More Information
  13. Option D: Escalate
  14. Case Manager enters decision notes
  15. Case Manager submits decision
  16. System validates decision
  17. System updates case status:
  18. Approve → Case status: Resolved, Applicant: Approved
  19. Reject → Case status: Closed, Applicant: Rejected
  20. Request More Info → Case status: OnHold
  21. Escalate → Case status: Escalated
  22. System creates decision record
  23. System updates applicant review status
  24. System sends notification to applicant (if configured)
  25. System triggers webhook with decision
  26. System displays confirmation

Postconditions

  • Case decision recorded
  • Case status updated
  • Applicant status updated (if approved/rejected)
  • Notification sent
  • Webhook triggered
  • Audit log entry created

Alternative Flows

  • 5a. Request documents: Case Manager selects specific documents needed, system creates document request
  • 5b. Escalate: System notifies senior compliance officer, case assigned to escalation queue
  • 7a. Notes required: System requires minimum 10 characters for rejection notes

Business Rules

  • Only assigned case manager can make decisions
  • Rejection must include detailed notes
  • Approved applicants cannot be rejected without creating new case
  • Escalated cases require senior officer approval
  • High-risk applicants require two-level approval

UC-ALERT-003: Generate Automatic Alert

Primary Actor: System
Scope: Alert Management
Level: Subfunction
Stakeholders: Compliance team, risk team

Description

System automatically generates an alert when predefined conditions are met during applicant processing or transaction monitoring.

Preconditions

  • Alert rules are configured and active
  • Applicant or transaction data is being processed

Main Success Scenario

  1. System processes applicant/transaction data
  2. System evaluates applicable alert rules
  3. System detects rule condition match
  4. System creates alert record:
  5. Alert type (risk, transaction, document, status)
  6. Severity level (from rule)
  7. Applicant/transaction reference
  8. Rule that triggered the alert
  9. Timestamp
  10. System calculates alert priority
  11. System assigns alert to appropriate queue
  12. If severity is "Critical":
  13. System creates case automatically
  14. System sends immediate notification
  15. System publishes alert event
  16. System updates dashboard statistics
  17. System triggers configured notifications:
    • Email to compliance officers
    • System notification
    • Webhook to external systems

Postconditions

  • Alert created and visible in dashboard
  • Case created (if critical severity)
  • Notifications sent
  • Alert appears in assigned officer's queue
  • Audit log entry created

Alternative Flows

  • 3a. Multiple rules match: System creates separate alerts for each rule
  • 6a. No officers available: Alert assigned to default compliance queue
  • 10a. Notification fails: System logs error but continues processing

Business Rules

  • Critical alerts must create cases automatically
  • Duplicate alerts suppressed within 24 hours
  • High-risk applicant alerts escalated automatically
  • Transaction alerts require immediate review
  • Alert retention: 5 years minimum

UC-WF-002: Configure Workflow Steps

Primary Actor: Tenant Administrator
Scope: Workflow Configuration
Level: User Goal
Stakeholders: Compliance team, operations

Description

Configure the individual steps that make up a KYC workflow, defining what actions are performed at each stage of the verification process.

Preconditions

  • Workflow has been created
  • User has workflow configuration permissions

Main Success Scenario

  1. Administrator navigates to workflow configuration
  2. System displays workflow details and existing steps
  3. Administrator clicks "Add Step"
  4. System displays step configuration form
  5. Administrator enters:
  6. Step name and description
  7. Step order/sequence
  8. Step type:
    • Identity SDK: Third-party identity verification
    • Questionnaire: Custom questionnaire completion
    • Risk Scoring: Risk assessment evaluation
    • Upload Document: Document collection
    • Appropriateness Test: Suitability assessment
    • Manual Review: Human review required
  9. Administrator configures step-specific settings:
  10. For Identity SDK:
    • Provider selection (Sumsub, Onfido, Sardin)
    • Verification level
  11. For Questionnaire:
    • Questionnaire selection
    • Country mapping
  12. For Risk Scoring:
    • Scoring plan selection
  13. For Upload Document:
    • Required document types
    • Country-specific requirements
  14. For Appropriateness Test:
    • Test selection
  15. Administrator sets step behavior:
  16. Required or optional
  17. Timeout duration
  18. Failure handling (stop workflow / continue / create case)
  19. Administrator saves step configuration
  20. System validates step configuration
  21. System adds step to workflow
  22. System updates workflow structure

Postconditions

  • Workflow step created and configured
  • Step added to workflow sequence
  • Workflow updated
  • Audit log entry created

Alternative Flows

  • 9a. Validation fails: System displays errors, administrator corrects configuration
  • 10a. Provider not configured: System prompts to configure provider first

Business Rules

  • At least one step must be required
  • Identity verification step recommended as first step
  • Manual review step cannot be first step
  • Maximum 10 steps per workflow
  • Step order must be unique within workflow

UC-API-002: Submit Applicant via API

Primary Actor: API Client (External System)
Scope: API Integration
Level: User Goal
Stakeholders: API client application, tenant, applicant

Description

External system submits a new KYC applicant through the RESTful API, enabling headless integration with MetaKYC.

Preconditions

  • API client has valid API key
  • API key has applicant creation permissions
  • Workflow ID is known

Main Success Scenario

  1. Client application prepares applicant data (JSON)
  2. Client application includes:
  3. API key in Authorization header
  4. Tenant ID in Abp-TenantId header (if multi-tenant)
  5. Client makes POST request to: POST /api/services/app/Applicant/CreateApplicant
  6. System validates API key
  7. System validates tenant context
  8. System validates request payload
  9. System creates applicant record
  10. System initializes workflow
  11. System triggers first workflow step
  12. System returns response: json { "result": { "id": 12345, "workflowId": 1, "status": "ProviderResultPending", "reviewStatus": "New", "externalRefId": "client-ref-123" }, "success": true }
  13. Client application stores applicant ID
  14. System triggers webhook notification to client

Postconditions

  • Applicant created in MetaKYC
  • Workflow initiated
  • Applicant ID returned to client
  • Webhook notification queued
  • Audit log entry created

Alternative Flows

  • 4a. Invalid API key: System returns 401 Unauthorized
  • 5a. Invalid tenant: System returns 400 Bad Request
  • 6a. Validation fails: System returns 400 with validation errors
  • 12a. Webhook endpoint unavailable: System retries with exponential backoff

Business Rules

  • API key must be active and not expired
  • Rate limit: 100 requests per minute per API key
  • Maximum payload size: 10MB
  • Required fields must be present
  • ExternalRefId must be unique per tenant

API Request Example

POST /api/services/app/Applicant/CreateApplicant HTTP/1.1
Host: api.metakyc.com
Authorization: Bearer {api-key}
Abp-TenantId: 2
Content-Type: application/json

{
  "workflowId": 1,
  "externalRefId": "client-ref-123",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "dateOfBirth": "1990-01-15",
  "nationality": "US",
  "address": {
    "street": "123 Main St",
    "city": "New York",
    "country": "US",
    "postalCode": "10001"
  }
}

API Response Example

{
  "result": {
    "id": 12345,
    "workflowId": 1,
    "status": 0,
    "reviewStatus": 5,
    "externalRefId": "client-ref-123",
    "creationTime": "2024-01-15T10:30:00Z"
  },
  "targetUrl": null,
  "success": true,
  "error": null,
  "unAuthorizedRequest": false,
  "__abp": true
}

UC-API-004: Receive Webhook Notification

Primary Actor: API Client (External System)
Scope: API Integration
Level: User Goal
Stakeholders: API client application, tenant

Description

API client receives real-time webhook notifications from MetaKYC when significant events occur (applicant status changes, workflow completion, alerts generated).

Preconditions

  • Webhook endpoint configured in tenant settings
  • Webhook URL is accessible via HTTPS
  • Webhook secret configured for signature verification

Main Success Scenario

  1. Event occurs in MetaKYC (e.g., applicant approved)
  2. System creates webhook job
  3. System prepares webhook payload: json { "event": "applicant.approved", "tenantId": 2, "timestamp": "2024-01-15T10:30:00Z", "data": { "applicantId": 12345, "externalRefId": "client-ref-123", "reviewStatus": "Approved", "workflowId": 1, "riskLevel": "Low" } }
  4. System generates HMAC signature using webhook secret
  5. System makes POST request to client webhook URL:
  6. Header: X-Webhook-Signature: sha256=...
  7. Header: X-Webhook-Event: applicant.approved
  8. Client receives webhook
  9. Client validates signature using shared secret
  10. Client parses webhook payload
  11. Client processes event (updates local database)
  12. Client returns HTTP 200 OK
  13. System marks webhook as delivered
  14. System logs successful delivery

Postconditions

  • Event delivered to client
  • Client updated with latest information
  • Webhook marked as delivered
  • Delivery logged in audit trail

Alternative Flows

  • 7a. Signature validation fails: Client returns 401, logs security alert
  • 10a. Client returns error (4xx/5xx): System retries with backoff:
  • Retry 1: 1 minute later
  • Retry 2: 5 minutes later
  • Retry 3: 30 minutes later
  • Retry 4: 2 hours later
  • Retry 5: 24 hours later (final)
  • 10b. Timeout (30 seconds): System treats as failed delivery, initiates retry
  • 11a. All retries fail: System marks webhook as failed, sends alert to tenant administrator

Business Rules

  • Webhooks sent only for subscribed events
  • Maximum retry attempts: 5
  • Webhook timeout: 30 seconds
  • Signature algorithm: HMAC-SHA256
  • Webhooks sent in order of occurrence
  • Failed webhooks do not block subsequent webhooks

Webhook Events

  • applicant.created
  • applicant.approved
  • applicant.rejected
  • applicant.status_changed
  • workflow.step_completed
  • workflow.completed
  • alert.created
  • alert.resolved
  • case.created
  • case.decision_made
  • transaction.flagged
  • risk.assessment_completed

Signature Verification (Client-side)

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = 'sha256=' + 
    crypto
      .createHmac('sha256', secret)
      .update(JSON.stringify(payload))
      .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

UC-ADMIN-002: Configure Tenant Features

Primary Actor: Host Administrator
Scope: Administration
Level: User Goal
Stakeholders: Host, tenant, users

Description

Host administrator controls which features are available to specific tenants, enabling flexible licensing and feature gating.

Preconditions

  • User is authenticated as host administrator
  • Tenant exists in the system

Main Success Scenario

  1. Host Administrator navigates to Tenant Management
  2. System displays list of tenants
  3. Administrator clicks feature management icon (shield) for target tenant
  4. System displays feature management modal with all available features:
  5. KYC Management
  6. Risk Management
  7. Questionnaires
  8. Appropriateness Tests
  9. Document Management
  10. Case Management
  11. Alert Management
  12. Transaction Monitoring
  13. Administration
  14. System Configuration
  15. Development (API & Webhooks)
  16. System shows current feature status (enabled/disabled) for tenant
  17. Administrator toggles features:
  18. Checks features to enable
  19. Unchecks features to disable
  20. Administrator clicks "Save Changes"
  21. System validates feature configuration
  22. System updates tenant feature configuration
  23. System invalidates feature cache for tenant
  24. System displays success message
  25. When tenant users next login:
    • Navigation menu reflects enabled features only
    • Disabled features are completely hidden
    • API endpoints for disabled features return 403

Postconditions

  • Tenant feature configuration updated
  • Feature cache invalidated
  • Tenant users see updated navigation
  • Disabled features inaccessible
  • Audit log entry created

Alternative Flows

  • 8a. Validation fails: System displays error (e.g., "At least one feature must be enabled")
  • 12a. Active user sessions: Features refresh on next page navigation

Business Rules

  • Only host users can manage features
  • At least one feature must remain enabled
  • Default: All features enabled for new tenants
  • Feature changes take effect immediately
  • Tenant cannot see or modify their own feature configuration
  • Disabled feature data remains in database (not deleted)

UC-DOC-009: Download Document Securely

Primary Actor: Compliance Officer
Scope: Document Management
Level: User Goal
Stakeholders: Compliance officer, security team

Description

Securely download and view applicant-uploaded documents with proper authorization, encryption, and audit logging.

Preconditions

  • User has document view permissions
  • Document exists and belongs to accessible applicant
  • User authenticated with valid session

Main Success Scenario

  1. Compliance Officer views applicant details
  2. System displays list of uploaded documents
  3. Officer clicks "View Document" on target document
  4. System validates:
  5. User has permission to view documents
  6. User has access to this applicant (same tenant/branch)
  7. Document exists and is accessible
  8. System generates time-limited access token (valid 5 minutes)
  9. System creates secure download URL with token
  10. System logs document access attempt
  11. System redirects to secure document viewer:
  12. PDF documents: Inline viewer
  13. Images: Inline viewer with zoom
  14. Other files: Force download
  15. System retrieves document from storage:
  16. Azure Blob Storage (production)
  17. Local storage (development)
  18. System decrypts document (if encrypted)
  19. System streams document to user
  20. System logs successful document access
  21. User views document in browser or downloads

Postconditions

  • Document accessed by authorized user
  • Access logged in audit trail with:
  • User ID and name
  • Applicant ID
  • Document ID
  • Timestamp
  • IP address
  • Action (view/download)
  • Access token consumed (cannot be reused)

Alternative Flows

  • 4a. Permission denied: System returns 403 Forbidden
  • 4b. Document not found: System returns 404 Not Found
  • 4c. Different tenant: System returns 403, logs unauthorized attempt
  • 9a. Storage unavailable: System returns 503, displays error message
  • 10a. Decryption fails: System logs error, notifies security team

Security Features

  • Time-limited access tokens (5 minutes)
  • Tokens are single-use only
  • All access audited
  • Documents encrypted at rest
  • HTTPS required for transmission
  • No direct URL access to documents
  • IP address logging
  • Watermarking for sensitive documents (configurable)

Business Rules

  • Only authorized users can access documents
  • Access limited to documents within user's tenant/branch
  • Document access must be audited
  • Minimum retention: 5 years
  • PII documents require additional permissions
  • Bulk download limited to 50 documents

UC-TXN-007: Process Provider Webhook

Primary Actor: Third-party Provider System
Scope: Transaction Monitoring
Level: System Function
Stakeholders: Provider system, risk team, compliance team

Description

System receives and processes webhook callbacks from external transaction monitoring providers (Sumsub, Sardin) when they complete analysis.

Preconditions

  • Tenant has external provider configured
  • Transaction was sent to provider for monitoring
  • Provider webhook endpoint is publicly accessible

Main Success Scenario

  1. External provider completes transaction analysis
  2. Provider makes POST request to MetaKYC webhook endpoint: POST /api/webhooks/transaction-monitoring/{provider}
  3. System receives webhook request
  4. System reads webhook signature from header
  5. System retrieves tenant configuration for provider
  6. System validates webhook signature using secret key
  7. System parses webhook payload
  8. System identifies transaction by external reference ID
  9. System extracts analysis results:
  10. Risk score
  11. Flagged rules
  12. Recommendation (approve/review/reject)
  13. System updates transaction record with provider results
  14. If flagged:
    • System creates alert
    • System evaluates if case creation needed
    • System sends notifications
  15. System returns HTTP 200 OK to provider
  16. System logs webhook processing

Postconditions

  • Transaction updated with provider results
  • Alerts created if transaction flagged
  • Case created if high severity
  • Compliance team notified
  • Webhook delivery confirmed to provider
  • Audit log entry created

Alternative Flows

  • 6a. Signature validation fails:
  • System returns 401 Unauthorized
  • System logs security alert
  • System notifies security team
  • 8a. Transaction not found:
  • System logs error
  • System returns 200 OK (idempotent)
  • 12a. System error during processing:
  • System returns 500 Internal Server Error
  • Provider will retry
  • Provider retry: System handles idempotently (duplicate webhooks ignored)

Business Rules

  • Webhook signature must be valid
  • Transaction must exist in system
  • Duplicate webhooks are ignored
  • Provider results stored permanently
  • High-risk results create cases automatically

Webhook Payload Example (Sumsub)

{
  "applicantId": "5f7c2f0c-1234-5678-9abc-def012345678",
  "reviewResult": {
    "reviewAnswer": "RED",
    "rejectLabels": ["FRAUDULENT_PATTERNS"],
    "reviewRejectType": "FINAL"
  },
  "transactionId": "txn-12345",
  "externalUserId": "metakyc-applicant-67890"
}

Integration Patterns

Pattern 1: Identity Verification Integration

Client App → MetaKYC API → Identity Provider (Sumsub/Onfido)
     ↓              ↓                    ↓
  Status      Workflow Step         Verification
  Query        Management             Process
     ↑              ↑                    ↓
     ←─── Webhook ←─── Provider Webhook ←─

Pattern 2: Headless KYC Integration

Client App Frontend
       ↓
Client App Backend ─→ MetaKYC API
       ↑                    ↓
    Webhook         Workflow Processing
  Notifications           ↓
       ↑             Status Updates
       ←──────────────────┘

Pattern 3: Risk Assessment Flow

Applicant Data → Risk Scoring Engine
                        ↓
                 Evaluate Criteria
                        ↓
                 Calculate Score
                        ↓
                 Determine Level
                        ↓
            ┌───────────┴───────────┐
            ↓                       ↓
       Low/Medium              High Risk
            ↓                       ↓
    Auto-Approve              Create Case
            ↓                       ↓
       Complete                Manual Review

Glossary

Key Terms

  • Applicant: Individual or company undergoing KYC verification
  • Workflow: Sequence of steps required for compliance verification
  • Step: Individual verification action within a workflow
  • Risk Scoring: Automated assessment of applicant risk level
  • Case: Investigation record for applicants requiring manual review
  • Alert: Automated notification of potential compliance issue
  • Transaction Monitoring: Continuous surveillance of financial transactions
  • Tenant: Organization using the MetaKYC platform (multi-tenant SaaS)
  • Host: System administrator managing all tenants
  • Provider: Third-party service for identity verification or transaction monitoring
  • Webhook: HTTP callback for real-time event notifications
  • API Key: Authentication credential for API access
  • UBO: Ultimate Beneficial Owner (person with >25% ownership or control)
  • AML: Anti-Money Laundering compliance
  • KYC: Know Your Customer verification process
  • Decision Type: Compliance action (approve, reject, escalate, etc.)

Appendix A: System Entities

Core Entities

  1. Applicant
  2. Natural person or legal entity undergoing verification
  3. Properties: Name, DOB, nationality, contact info, status

  4. Relations: Workflow, Progress, Documents, Cases

  5. Workflow

  6. Defines verification process structure
  7. Properties: Name, type, active status

  8. Relations: Steps, Rules, Applicants

  9. WorkflowStep

  10. Individual verification action
  11. Properties: Name, type, order, required

  12. Types: IdentitySDK, Questionnaire, RiskScoring, UploadDocument, AppropriatenessTest

  13. Case

  14. Investigation record for manual review
  15. Properties: Status, assignee, priority

  16. Relations: Applicant, Decisions, Alerts

  17. Alert

  18. Automated compliance notification
  19. Properties: Type, severity, status

  20. Relations: Applicant, Transaction, Rule

  21. Transaction

  22. Financial transaction for monitoring
  23. Properties: Amount, currency, type, timestamp

  24. Relations: Applicant, Alerts

  25. RiskScoringPlan

  26. Risk assessment configuration
  27. Properties: Name, thresholds, criteria

  28. Relations: Criteria, Results

  29. Questionnaire

  30. Custom question set
  31. Properties: Name, type, country mappings

  32. Relations: Questions, Groups, Results

  33. Document

  34. Uploaded verification document
  35. Properties: Type, status, storage path

  36. Relations: Applicant, Requirements

  37. TenantFeature

    • Feature enablement per tenant
    • Properties: Feature key, enabled status
    • Relations: Tenant

Appendix B: API Endpoints Reference

Applicant Management

Method Endpoint Description
POST /api/services/app/Applicant/CreateApplicant Create natural person applicant
POST /api/services/app/Applicant/CreateCompanyApplicant Create legal entity applicant
GET /api/services/app/Applicant/GetApplicantForEdit Get applicant details
GET /api/services/app/Applicant/GetAllApplicants List applicants with filtering
PUT /api/services/app/Applicant/UpdateApplicantStatus Update applicant status
GET /api/services/app/Applicant/GetApplicantProgress Get workflow progress

Risk Management

Method Endpoint Description
POST /api/services/app/RiskScoring/CreateOrUpdatePlan Create/update risk plan
GET /api/services/app/RiskScoring/GetAllPlans List risk plans
GET /api/services/app/RiskScoring/GetApplicantRiskScore Get risk assessment
POST /api/services/app/RiskScoring/EvaluateRisk Trigger risk evaluation

Transaction Monitoring

Method Endpoint Description
POST /api/services/app/Transaction/CreateTransaction Submit transaction
GET /api/services/app/Transaction/GetAll List transactions
POST /api/services/app/TransactionMonitoringRule/CreateRule Create monitoring rule
GET /api/services/app/TransactionMonitoringRule/GetAll List monitoring rules

Case Management

Method Endpoint Description
POST /api/services/app/Case/CreateCase Create compliance case
GET /api/services/app/Case/GetAll List cases
POST /api/services/app/CaseDecision/MakeDecision Make case decision
GET /api/services/app/CaseDecision/GetDecisionsByCaseId Get case decisions

Alert Management

Method Endpoint Description
GET /api/services/app/Alert/GetAll List alerts
POST /api/services/app/AlertRule/CreateOrUpdate Create/update alert rule
PUT /api/services/app/Alert/AcknowledgeAlert Acknowledge alert
PUT /api/services/app/Alert/ResolveAlert Resolve alert

Workflow Configuration

Method Endpoint Description
POST /api/services/app/Workflow/CreateOrUpdate Create/update workflow
GET /api/services/app/Workflow/GetAll List workflows
POST /api/services/app/WorkflowStep/CreateOrUpdate Create/update step
POST /api/services/app/WorkflowRule/CreateOrUpdateWorkflowRule Create/update rule

Administration

Method Endpoint Description
POST /api/services/app/Tenant/CreateTenant Create tenant
GET /api/services/app/TenantFeature/GetTenantFeatures Get tenant features
POST /api/services/app/TenantFeature/UpdateTenantFeatures Update features
POST /api/services/app/User/CreateOrUpdateUser Create/update user

Appendix C: Webhook Events

Event Types and Payloads

applicant.created

{
  "event": "applicant.created",
  "tenantId": 2,
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "applicantId": 12345,
    "externalRefId": "client-ref-123",
    "workflowId": 1,
    "applicantType": "NaturalPerson"
  }
}

applicant.approved

{
  "event": "applicant.approved",
  "tenantId": 2,
  "timestamp": "2024-01-15T11:45:00Z",
  "data": {
    "applicantId": 12345,
    "externalRefId": "client-ref-123",
    "reviewStatus": "Approved",
    "riskLevel": "Low",
    "approvalTimestamp": "2024-01-15T11:45:00Z"
  }
}

alert.created

{
  "event": "alert.created",
  "tenantId": 2,
  "timestamp": "2024-01-15T10:35:00Z",
  "data": {
    "alertId": 789,
    "applicantId": 12345,
    "alertType": "RiskScoring",
    "severity": "High",
    "message": "High risk score detected",
    "requiresAction": true
  }
}

transaction.flagged

{
  "event": "transaction.flagged",
  "tenantId": 2,
  "timestamp": "2024-01-15T14:20:00Z",
  "data": {
    "transactionId": 456,
    "applicantId": 12345,
    "amount": 15000.00,
    "currency": "USD",
    "flaggedRules": ["HIGH_VALUE_TRANSACTION", "VELOCITY_CHECK"],
    "riskScore": 85
  }
}

Document Version: 1.0
Last Updated: January 2026
Maintained By: Tokenise Development Team
Status: Current