Skip to main content

​
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.
Endpoint: GET /api/v2.1/customer/individual/categorization/hierarchy/{tenantId}Headers:
Authorization: Bearer {admin-jwt-token}
X-Tenant-ID: fh_api_finsei_ltd_7f957f77

​
Category Types

​
Individual (B2C) Categories

CategoryDescriptionApproval Level
HIGH_RISK_INDIVIDUALPEP, high-risk countries, high volumePOWER_TENANT
STANDARD_INDIVIDUALStandard customersTENANT
LOW_RISK_INDIVIDUALLow-risk, verified customersTENANT

​
Organization (B2B) Categories

CategoryDescriptionApproval Level
HIGH_RISK_BUSINESSPEP involvement, high-risk industryPOWER_TENANT
MEDIUM_RISK_BUSINESSStandard business operationsTENANT
LOW_RISK_BUSINESSRegulated, low-risk industryTENANT

​
Feature Configuration

​
ENHANCED_AML_MONITORING

For high-risk customers requiring enhanced monitoring.
KeyRequiredAllowed Values
riskLevel✅LOW, MEDIUM, HIGH, CRITICAL
riskScore✅0-100 (numeric)
pep✅true, false
pepCategoryConditionalDOMESTIC_PEP, FOREIGN_PEP, RCA, HIO
sanctionsCheck✅STANDARD, ENHANCED, REAL_TIME
monitoring✅WEEKLY, DAILY, REAL_TIME
edd✅true, false
transactionMonitoringOptionalBATCH_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.
KeyRequiredDescription
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.
KeyRequiredDescription
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