Phase 1: Registration & Onboarding

Individual customer registration with categorization and validation

Phase 1: Registration & Onboarding

Registration is the entry point for all individual customers. This phase creates the customer record, user credentials, and default inactive wallet.

What Gets Created

Component	Status	Description
Customer Record	`PENDING_VERIFICATION`	Core customer entity
User Credentials	Active	Login credentials (hashed)
Wallet	`INACTIVE`	Default wallet (activated later)
Categorization	Assigned	Feature-based category (if provided)

Step 1: Get Categorization Hierarchy

Before registration, retrieve available categories and features for smart categorization.

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

Headers:

http

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

Status: 200 OK

json

{
  "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": [
          {
            "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"]
            }
          }
        ]
      },
      "STANDARD_INDIVIDUAL": {
        "databaseId": "550e8400-e29b-41d4-a716-446655440010",
        "categoryId": "STANDARD_INDIVIDUAL",
        "categoryName": "Standard Individual Customer"
      }
    }
  }
}

Step 2: Register Individual Customer

Endpoint: POST /api/v2.1/customer/individual/registration

Headers:

http

X-Tenant-ID: fh_api_finsei_ltd_7f957f77
Authorization: Bearer {admin-jwt-token}
Content-Type: application/json

Request Body:

json

{
  "tenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
  "email": "john.doe@example.com",
  "password": "SecurePass123!@#",
  "matchingPassword": "SecurePass123!@#",
  "firstName": "John",
  "lastName": "Doe",
  "individualCustomer": {
    "tenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
    "email": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "middleName": "Robert",
    "dateOfBirth": "1990-05-15",
    "placeOfBirth": "New York",
    "nationality": "US",
    "phoneNumber": "+12125551234",
    "alternatePhoneNumber": "+12125559876",
    "address": {
      "street": "123 Main Street",
      "streetNumber": "123",
      "apartment": "Apt 4B",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US",
      "addressType": "RESIDENTIAL"
    },
    "occupation": "Software Engineer",
    "employerName": "Tech Corp Inc",
    "annualIncome": "150000",
    "sourceOfFunds": "SALARY",
    "categorization": {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "HIGH_RISK_INDIVIDUAL",
      "isActive": true,
      "categoryFeatureRelations": [
        {
          "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" }
          ]
        },
        {
          "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" }
          ]
        }
      ]
    }
  }
}

Status: 201 Created

json

{
  "code": 201,
  "message": "Account created successfully",
  "data": {
    "id": "cust-550e8400-e29b-41d4-a716-446655440010",
    "userId": "user-660e8400-e29b-41d4-a716-446655440011",
    "email": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "status": "PENDING_VERIFICATION",
    "categorization": {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "HIGH_RISK_INDIVIDUAL",
      "categoryFeatureRelations": [...]
    },
    "createdAt": "2026-01-13T10:30:00.000Z",
    "updatedAt": "2026-01-13T10:30:00.000Z"
  }
}

Key IDs to Store:

id → Customer ID (for all subsequent calls)
userId → User ID (for session creation)

400 - Password Mismatch:

json

{
  "code": 400,
  "message": "Request validation failed",
  "data": {
    "errors": [
      {
        "field": "matchingPassword",
        "message": "Password and matching password must be identical"
      }
    ]
  }
}

400 - Invalid Categorization:

json

{
  "code": 400,
  "message": "Categorization validation failed",
  "data": {
    "error": "Invalid categorization",
    "details": "Feature 'ENHANCED_AML_MONITORING' requires mandatory key 'riskLevel'",
    "missingKeys": ["riskLevel"],
    "invalidValues": {
      "monitoring": "HOURLY is not in allowed values: [WEEKLY, DAILY, REAL_TIME]"
    }
  }
}

403 - Tenant Access Denied:

json

{
  "code": 403,
  "message": "Tenant access denied or categorization not available",
  "data": {
    "error": "Tenant access denied",
    "tenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd"
  }
}

Business Logic

Tenant ID Resolution

The system resolves tenant ID from the header:

1. Extract X-Tenant-ID header (e.g., "fh_api_finsei_ltd_7f957f77")
2. Resolve to UUID (e.g., "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd")
3. Override tenant ID in request body

Password Validation Rules

Rule	Requirement
Minimum Length	8 characters
Uppercase	At least 1
Lowercase	At least 1
Numbers	At least 1
Special Characters	At least 1
Must Match	`matchingPassword` field
Cannot Contain	Username or email

Categorization Validation

1. Check if categorization provided
2. Validate category exists in tenant hierarchy
3. For each feature:
   a. Validate feature exists for tenant
   b. Check all mandatory keys provided
   c. Validate values against allowedValues
4. Store validated categorization

Auto-Generated Components

Component	Format
Customer ID	UUID v4
User ID	UUID v4
Wallet ID	UUID v4 (inactive)
Email Verification Token	64-char hex string

Smart Categorization Examples

High-Risk Customer

Selection Criteria:

PEP (Politically Exposed Person)
High transaction volume expected
High-risk occupation or industry
High-risk country

Configuration:

json

{
  "riskLevel": "HIGH",
  "riskScore": "85",
  "pep": "true",
  "pepCategory": "DOMESTIC_PEP",
  "sanctionsCheck": "ENHANCED",
  "monitoring": "DAILY",
  "edd": "true",
  "transactionMonitoring": "REAL_TIME"
}

Standard Customer

Configuration:

json

{
  "riskLevel": "MEDIUM",
  "riskScore": "45",
  "pep": "false",
  "sanctionsCheck": "STANDARD",
  "monitoring": "WEEKLY",
  "edd": "false",
  "transactionMonitoring": "BATCH_DAILY"
}

Next Step

After successful registration, proceed to Phase 2: Session Management to authenticate the customer.

Phase 2: Session Management

Create customer session and obtain JWT token