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
Response

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

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

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

Category must exist in tenant hierarchy
All mandatory keys must be provided for each feature
Values must match allowed values
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

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

​Categorization Hierarchy

​Overview

​Get Categorization Hierarchy

​Category Types

​Individual (B2C) Categories

​Organization (B2B) Categories

​Feature Configuration

​ENHANCED_AML_MONITORING

​TRANSACTION_LIMITS

​INTERNATIONAL_PAYMENTS (B2B)

​Smart Categorization Strategy

​High-Risk Customer Criteria

​Standard Customer Criteria

​Validation Process

​Validation Rules

​Common Validation Errors

​Missing Mandatory Key

​Invalid Value

​Best Practices

Categorization Hierarchy

Overview

Get Categorization Hierarchy

Category Types

Individual (B2C) Categories

Organization (B2B) Categories

Feature Configuration

ENHANCED_AML_MONITORING

TRANSACTION_LIMITS

INTERNATIONAL_PAYMENTS (B2B)

Smart Categorization Strategy

High-Risk Customer Criteria

Standard Customer Criteria

Validation Process

Validation Rules

Common Validation Errors

Missing Mandatory Key

Invalid Value

Best Practices