Categorization Hierarchy

Categorization is a feature-based system for classifying customers based on risk level and enabling appropriate monitoring and limits.

Overview

flowchart TD
    A[Tenant] --> B[Categories]
    B --> C[HIGH_RISK_INDIVIDUAL]
    B --> D[STANDARD_INDIVIDUAL]
    B --> E[MEDIUM_RISK_BUSINESS]
    C --> F[Features]
    D --> F
    E --> F
    F --> G[ENHANCED_AML_MONITORING]
    F --> H[TRANSACTION_LIMITS]
    F --> I[INTERNATIONAL_PAYMENTS]

Get Categorization Hierarchy

Before registration, retrieve available categories and features.

Authorization: Bearer {admin-jwt-token}
X-Tenant-ID: fh_api_finsei_ltd_7f957f77

{
  "code": 200,
  "message": "Hierarchy retrieved successfully",
  "data": {
    "tenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
    "tenantName": "Finsei Ltd",
    "complianceLevel": "ENHANCED",
    "categories": {
      "HIGH_RISK_INDIVIDUAL": {
        "databaseId": "550e8400-e29b-41d4-a716-446655440001",
        "categoryId": "HIGH_RISK_INDIVIDUAL",
        "categoryName": "High Risk Individual Customer",
        "description": "High-risk customers requiring enhanced monitoring",
        "availableFeatures": [
          {
            "databaseId": "660e8400-e29b-41d4-a716-446655440002",
            "featureCode": "ENHANCED_AML_MONITORING",
            "featureName": "Enhanced AML Monitoring",
            "mandatoryKeys": [
              "riskLevel",
              "riskScore",
              "pep",
              "sanctionsCheck",
              "monitoring",
              "edd"
            ],
            "allowedValues": {
              "riskLevel": ["LOW", "MEDIUM", "HIGH", "CRITICAL"],
              "riskScore": ["0-100"],
              "pep": ["true", "false"],
              "pepCategory": ["DOMESTIC_PEP", "FOREIGN_PEP", "RCA", "HIO"],
              "sanctionsCheck": ["STANDARD", "ENHANCED", "REAL_TIME"],
              "monitoring": ["WEEKLY", "DAILY", "REAL_TIME"],
              "edd": ["true", "false"]
            },
            "multiValueKeys": ["pepCategory"]
          }
        ]
      },
      "STANDARD_INDIVIDUAL": {
        "databaseId": "550e8400-e29b-41d4-a716-446655440010",
        "categoryId": "STANDARD_INDIVIDUAL",
        "categoryName": "Standard Individual Customer"
      }
    },
    "features": {
      "ENHANCED_AML_MONITORING": {
        "databaseId": "660e8400-e29b-41d4-a716-446655440002",
        "featureCode": "ENHANCED_AML_MONITORING",
        "featureName": "Enhanced AML Monitoring",
        "description": "Real-time transaction monitoring and enhanced due diligence"
      },
      "TRANSACTION_LIMITS": {
        "databaseId": "770e8400-e29b-41d4-a716-446655440003",
        "featureCode": "TRANSACTION_LIMITS",
        "featureName": "Transaction Limits"
      }
    }
  }
}

Category Types

Individual (B2C) Categories

Organization (B2B) Categories

Feature Configuration

ENHANCED_AML_MONITORING

For high-risk customers requiring enhanced monitoring.

Example Configuration:

{
  "feature": {
    "id": "660e8400-e29b-41d4-a716-446655440002",
    "code": "ENHANCED_AML_MONITORING"
  },
  "enabled": true,
  "parametrization": [
    { "name": "riskLevel", "value": "HIGH" },
    { "name": "riskScore", "value": "85" },
    { "name": "pep", "value": "true" },
    { "name": "pepCategory", "value": "DOMESTIC_PEP" },
    { "name": "sanctionsCheck", "value": "ENHANCED" },
    { "name": "monitoring", "value": "DAILY" },
    { "name": "edd", "value": "true" },
    { "name": "transactionMonitoring", "value": "REAL_TIME" }
  ]
}

TRANSACTION_LIMITS

Define transaction limits for the customer.

Example Configuration:

{
  "feature": {
    "id": "770e8400-e29b-41d4-a716-446655440003",
    "code": "TRANSACTION_LIMITS"
  },
  "enabled": true,
  "parametrization": [
    { "name": "dailyLimit", "value": "5000" },
    { "name": "monthlyLimit", "value": "50000" },
    { "name": "singleTransactionLimit", "value": "2000" }
  ]
}

INTERNATIONAL_PAYMENTS (B2B)

Enable international payment capabilities.

Example Configuration:

{
  "feature": {
    "id": "org-feat-770e8400-e29b-41d4-a716-446655440102",
    "code": "INTERNATIONAL_PAYMENTS"
  },
  "enabled": true,
  "parametrization": [
    { "name": "swiftEnabled", "value": "true" },
    { "name": "sepaEnabled", "value": "true" },
    { "name": "crossBorderLimit", "value": "50000" }
  ]
}

Smart Categorization Strategy

High-Risk Customer Criteria

Assign HIGH_RISK_INDIVIDUAL or HIGH_RISK_BUSINESS when:

• ✅ Customer is a PEP (Politically Exposed Person)
• ✅ High transaction volume expected (>€50k/month)
• ✅ High-risk occupation or industry
• ✅ High-risk country of residence/nationality
• ✅ Sanctions list check required
• ✅ Complex ownership structure (B2B)

Standard Customer Criteria

Assign STANDARD_INDIVIDUAL or MEDIUM_RISK_BUSINESS when:

• ✅ No PEP involvement
• ✅ Standard transaction volume
• ✅ Low-risk occupation or industry
• ✅ Low-risk country
• ✅ Simple ownership structure (B2B)

Validation Process

flowchart TD
    A[Registration Request] --> B{Categorization Provided?}
    B -->|No| C[Use Default Category]
    B -->|Yes| D[Validate Category Exists]
    D --> E{Valid Category?}
    E -->|No| F[Return 400 Error]
    E -->|Yes| G[Validate Features]
    G --> H{All Mandatory Keys?}
    H -->|No| F
    H -->|Yes| I{Valid Values?}
    I -->|No| F
    I -->|Yes| J[Store Categorization]
    J --> K[Registration Success]

Validation Rules

1. Category must exist in tenant hierarchy
2. All mandatory keys must be provided for each feature
3. Values must match allowed values
4. Multi-value keys can have multiple values (comma-separated)

Common Validation Errors

Missing Mandatory Key

{
  "code": 400,
  "message": "Categorization validation failed",
  "data": {
    "error": "Missing mandatory key 'riskLevel'",
    "feature": "ENHANCED_AML_MONITORING",
    "missingKeys": ["riskLevel"]
  }
}

Invalid Value

{
  "code": 400,
  "message": "Categorization validation failed",
  "data": {
    "error": "Invalid value for key 'monitoring'",
    "feature": "ENHANCED_AML_MONITORING",
    "invalidValues": {
      "monitoring": "HOURLY is not in allowed values: [WEEKLY, DAILY, REAL_TIME]"
    }
  }
}

Best Practices

1. Always call hierarchy endpoint first - Get current categories and features
2. Don’t hardcode IDs - IDs may differ across environments
3. Validate locally before submission - Check mandatory keys and values
4. Use appropriate risk levels - Match customer profile to category
5. Document categorization decisions - Keep audit trail