Categorization Hierarchy

Smart categorization strategy for customer risk classification

Categorization Hierarchy

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

Overview

---

Get Categorization Hierarchy

Before registration, retrieve available categories and features.

Request

Endpoint: GET /api/v2.1/customer/individual/categorization/hierarchy/{tenantId}

Headers:

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

Response

{
  "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

Category	Description	Approval Level
HIGH_RISK_INDIVIDUAL	PEP, high-risk countries, high volume	POWER_TENANT
STANDARD_INDIVIDUAL	Standard customers	TENANT
LOW_RISK_INDIVIDUAL	Low-risk, verified customers	TENANT

Organization (B2B) Categories

Category	Description	Approval Level
HIGH_RISK_BUSINESS	PEP involvement, high-risk industry	POWER_TENANT
MEDIUM_RISK_BUSINESS	Standard business operations	TENANT
LOW_RISK_BUSINESS	Regulated, low-risk industry	TENANT

---

Feature Configuration

ENHANCED_AML_MONITORING

For high-risk customers requiring enhanced monitoring.

Key	Required	Allowed Values
riskLevel	✅	LOW, MEDIUM, HIGH, CRITICAL
riskScore	✅	0-100 (numeric)
pep	✅	true, false
pepCategory	Conditional	DOMESTIC_PEP, FOREIGN_PEP, RCA, HIO
sanctionsCheck	✅	STANDARD, ENHANCED, REAL_TIME
monitoring	✅	WEEKLY, DAILY, REAL_TIME
edd	✅	true, false
transactionMonitoring	Optional	BATCH_DAILY, REAL_TIME

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.

Key	Required	Description
dailyLimit	✅	Maximum daily transaction amount
monthlyLimit	✅	Maximum monthly transaction amount
singleTransactionLimit	✅	Maximum single transaction amount

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.

Key	Required	Description
swiftEnabled	✅	Enable SWIFT transfers
sepaEnabled	✅	Enable SEPA transfers
crossBorderLimit	✅	Cross-border transaction limit

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

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