Individual Account Opening

This guide walks you through the process of creating and verifying individual customer accounts using the FinHub API v2.1. The individual account opening process involves several steps including customer categorization, registration with smart features, identity verification, and account activation with automatic IBAN and wallet creation.

Overview

The individual account opening process follows these main steps:

Retrieve customer categorization hierarchy
Register individual customer with smart categorization
Create verification request and upload documents
Activate customer account (automatic IBAN and wallet creation)
Set up beneficiaries and payment consents
Execute financial transactions

Complete Flow Sequence

The following sequence diagram illustrates the complete individual account opening process with the new v2.1 APIs:

Note: The new v2.1 APIs provide enhanced features including smart categorization, automatic IBAN generation, integrated wallet creation, and streamlined verification processes.

Prerequisites

Before starting the individual account opening process, ensure you have:

Valid API credentials for the FinHub platform
Admin authentication token for initial setup
X-Tenant-ID header value
Required customer information (personal details, contact information, etc.)
Verification documents ready for upload

Step 1: Get Categorization Hierarchy

First, retrieve the customer categorization options available for your tenant. This determines risk levels, limits, and required parameters.

API Request

GET /api/v2.1/customer/categorization/tree
Content-Type: application/json
Authorization: Bearer {admin_token}
X-Tenant-ID: {tenant_id}

Response

{
  "data": {
    "categories": [
      {
        "id": "cat_001",
        "name": "LOW_RISK_INDIVIDUAL",
        "riskLevel": "LOW",
        "limits": {
          "dailyTransactionLimit": "10000.00",
          "monthlyTransactionLimit": "50000.00",
          "maxTransactionAmount": "5000.00"
        },
        "requiredParameters": [
          "firstName",
          "lastName",
          "dateOfBirth",
          "nationality",
          "email",
          "phoneNumber"
        ],
        "features": [
          {
            "code": "INSTANT_PAYMENTS",
            "enabled": true
          },
          {
            "code": "INTERNATIONAL_TRANSFERS",
            "enabled": false
          }
        ]
      },
      {
        "id": "cat_002",
        "name": "MEDIUM_RISK_INDIVIDUAL",
        "riskLevel": "MEDIUM",
        "limits": {
          "dailyTransactionLimit": "25000.00",
          "monthlyTransactionLimit": "100000.00",
          "maxTransactionAmount": "15000.00"
        },
        "requiredParameters": [
          "firstName",
          "lastName",
          "dateOfBirth",
          "nationality",
          "email",
          "phoneNumber",
          "address",
          "occupation",
          "sourceOfFunds"
        ],
        "features": [
          {
            "code": "INSTANT_PAYMENTS",
            "enabled": true
          },
          {
            "code": "INTERNATIONAL_TRANSFERS",
            "enabled": true
          },
          {
            "code": "CRYPTO_OPERATIONS",
            "enabled": false
          }
        ]
      }
    ]
  }
}

Step 2: Register Individual Customer

Create a new individual customer using the selected category. The smart categorization feature automatically applies the appropriate risk profile and limits.

API Request

POST /api/v2.1/customer/individual/register
Content-Type: application/json
Authorization: Bearer {admin_token}
X-Tenant-ID: {tenant_id}

Request Body

{
  "categoryId": "cat_002",  // MEDIUM_RISK_INDIVIDUAL from Step 1
  "person": {
    "firstName": "John",
    "lastName": "Doe",
    "dateOfBirth": "1985-05-15",
    "nationality": "US",
    "email": "john.doe@example.com",
    "phoneNumber": "+12125551234"
  },
  "address": {
    "street": "123 Main Street",
    "city": "New York",
    "postalCode": "10001",
    "country": "US"
  },
  "additionalInfo": {
    "occupation": "Software Engineer",
    "sourceOfFunds": "EMPLOYMENT",
    "estimatedMonthlyIncome": "8000.00"
  },
  "smartCategorization": {
    "enabled": true,
    "parameters": {
      "enableInstantPayments": true,
      "enableInternationalTransfers": true,
      "requestHigherLimits": false
    }
  }
}

Response

{
  "data": {
    "customerId": "cust_abc123def456",
    "status": "PENDING_VERIFICATION",
    "categoryId": "cat_002",
    "appliedLimits": {
      "dailyTransactionLimit": "25000.00",
      "monthlyTransactionLimit": "100000.00",
      "maxTransactionAmount": "15000.00"
    },
    "verificationRequest": {
      "requestId": "ver_req_xyz789",
      "status": "INITIATED",
      "requiredDocuments": [
        {
          "type": "IDENTITY_DOCUMENT",
          "accepted": ["PASSPORT", "NATIONAL_ID", "DRIVERS_LICENSE"]
        },
        {
          "type": "PROOF_OF_ADDRESS",
          "accepted": ["UTILITY_BILL", "BANK_STATEMENT", "RENTAL_AGREEMENT"]
        }
      ]
    },
    "createdAt": "2025-01-23T09:15:00Z"
  }
}

Step 3: Upload Verification Documents

Upload the required verification documents for the customer. The system will process these for identity verification.

API Request

POST /api/v2.1/verification/documents/upload
Content-Type: application/json
Authorization: Bearer {admin_token}
X-Tenant-ID: {tenant_id}

Request Body

{
  "verificationRequestId": "ver_req_xyz789",  // From Step 2 response
  "documents": [
    {
      "type": "IDENTITY_DOCUMENT",
      "subType": "PASSPORT",
      "content": "base64_encoded_document_content",
      "fileName": "passport.jpg",
      "mimeType": "image/jpeg",
      "metadata": {
        "documentNumber": "AB1234567",
        "issuingCountry": "US",
        "expiryDate": "2030-01-01"
      }
    },
    {
      "type": "PROOF_OF_ADDRESS",
      "subType": "UTILITY_BILL",
      "content": "base64_encoded_document_content",
      "fileName": "utility_bill.pdf",
      "mimeType": "application/pdf",
      "metadata": {
        "issueDate": "2025-01-01",
        "issuer": "ConEd New York"
      }
    }
  ]
}

Response

{
  "data": {
    "verificationRequestId": "ver_req_xyz789",
    "documentsProcessed": 2,
    "status": "DOCUMENTS_RECEIVED",
    "nextStep": "AWAIT_VERIFICATION_RESULT",
    "estimatedProcessingTime": "5-10 minutes"
  }
}

Step 4: Activate Customer Account

Once verification is complete (you can check the status via webhook or polling), activate the customer account. This step automatically creates the customer’s IBAN and wallet.

API Request

POST /api/v2.1/customer/individual/activate
Content-Type: application/json
Authorization: Bearer {admin_token}
X-Tenant-ID: {tenant_id}

Request Body

{
  "customerId": "cust_abc123def456",
  "activationOptions": {
    "generateIBAN": true,
    "createWallet": true,
    "walletCurrency": "EUR",
    "sendWelcomeEmail": true
  }
}

Response

{
  "data": {
    "customerId": "cust_abc123def456",
    "status": "ACTIVE",
    "activatedAt": "2025-01-23T10:35:00Z",
    "accountDetails": {
      "iban": "FR1420041010050500013M02606",
      "bic": "FINHFRPPXXX",
      "accountNumber": "50500013M02606",
      "walletId": "wal_def789ghi012",
      "currency": "EUR",
      "balance": {
        "available": "0.00",
        "current": "0.00",
        "locked": "0.00"
      }
    },
    "activationCode": "ACT-2025-ABC123",
    "welcomePackage": {
      "emailSent": true,
      "documentsGenerated": [
        "welcome_letter.pdf",
        "account_details.pdf",
        "terms_conditions.pdf"
      ]
    }
  }
}

Step 5: Set Up Beneficiaries

Add beneficiaries to enable the customer to make transfers.

API Request

POST /api/v2.1/fintrans/{walletId}/beneficiaries
Content-Type: application/json
Authorization: Bearer {customer_token}  // Customer must be authenticated
X-Tenant-ID: {tenant_id}
X-Session-Id: {session_id}

Request Body

{
  "partyType": "INDIVIDUAL_CUSTOMER",
  "firstName": "Jane",
  "lastName": "Smith",
  "shortName": "Jane Smith",
  "iban": "DE89370400440532013000",
  "currency": "EUR",
  "country": "DE",
  "email": "jane.smith@example.com",
  "phoneNumber": "+49123456789",
  "bicSwiftCode": "DEUTDEFF",
  "networkName": "SEPA",
  "bankName": "Deutsche Bank AG",
  "bankAddress": "Taunusanlage 12, 60325 Frankfurt am Main, Germany",
  "purposeCode": "OTHR"
}

Response

{
  "data": {
    "id": "ben_xyz789abc123",
    "status": "ACTIVE",
    "shortName": "Jane Smith",
    "iban": "DE89370400440532013000",
    "networkName": "SEPA",
    "createdAt": "2025-01-23T10:40:00Z"
  }
}

For enhanced security and control, create a payment consent that restricts transfers to specific beneficiaries.

API Request

POST /api/v2.1/fintrans/{walletId}/consents/payment
Content-Type: application/json
Authorization: Bearer {customer_token}
X-Tenant-ID: {tenant_id}
X-Session-Id: {session_id}

Request Body

{
  "paymentType": "TRANSFER",
  "limits": {
    "maxAmountPerTransaction": "5000.00",
    "dailyLimit": "10000.00",
    "weeklyLimit": "25000.00",
    "monthlyLimit": "50000.00",
    "currency": "EUR"
  },
  "beneficiaryRestrictions": {
    "enabled": true,
    "allowedBeneficiaries": ["ben_xyz789abc123"],  // From Step 5
    "allowNewBeneficiaries": false
  },
  "validFrom": "2025-01-23",
  "validUntil": "2026-01-23",
  "description": "Payment consent for EUR transfers"
}

Response

{
  "data": {
    "id": "consent_abc456def789",
    "consentReference": "consent-payment-abc123",
    "status": "ACTIVE",
    "validUntil": "2026-01-23",
    "beneficiaryRestrictions": {
      "enabled": true,
      "allowedBeneficiaries": ["ben_xyz789abc123"]
    }
  }
}

Step 7: Execute a Transfer (Three-Step Process)

Once the account is set up with beneficiaries and consent, execute transfers using the three-step process.

7.1 Check Allowed Operations

GET /api/v2.1/fintrans/{walletId}/allowed-operations
Authorization: Bearer {customer_token}
X-Tenant-ID: {tenant_id}
X-Session-Id: {session_id}

7.2 Prepare Order

POST /api/v2.1/fintrans/{walletId}/order/prepare
Content-Type: application/json
Authorization: Bearer {customer_token}
X-Tenant-ID: {tenant_id}
X-Session-Id: {session_id}

{
  "amount": {
    "value": "10050",  // €100.50 in cents
    "scale": 2,
    "currency": "EUR"
  },
  "operationType": "TRANSFER",
  "target": {
    "iban": "DE89370400440532013000",
    "name": "Jane Smith"
  },
  "reference": "Payment for services",
  "consent": {
    "consentReference": "consent-payment-abc123"
  }
}

7.3 Execute Order

POST /api/v2.1/fintrans/{walletId}/types/transfer/execute
Content-Type: application/json
Authorization: Bearer {customer_token}
X-Tenant-ID: {tenant_id}
X-Session-Id: {session_id}

{
  "preparedOrderId": "prep_order_xyz123",
  "authenticationCode": "123456",
  "consentConfirmation": {
    "consentId": "consent-payment-abc123",
    "confirmed": true,
    "timestamp": "2025-01-23T13:00:00.000Z",
    "channel": "WEB"
  }
}

Complete Flow Summary

The individual account opening process with the v2.1 APIs provides:

Smart Categorization: Automatic risk profiling and limit assignment
Integrated Verification: Streamlined document upload and processing
Automatic Account Setup: IBAN and wallet creation during activation
Comprehensive Financial Services: Beneficiary management, payment consents, and secure transfers

Error Handling

The v2.1 API returns detailed error responses:

HTTP Status	Error Code	Description
400	INVALID_REQUEST	Request body is invalid or missing required fields
401	UNAUTHORIZED	Invalid or expired authentication token
403	FORBIDDEN	Insufficient permissions or feature not enabled
404	NOT_FOUND	Resource (customer, wallet, etc.) not found
409	DUPLICATE_EMAIL	Customer with this email already exists
422	VALIDATION_ERROR	Business logic validation failed
429	RATE_LIMIT_EXCEEDED	Too many requests

Example Error Response

{
  "error": {
    "code": "INVALID_CATEGORY",
    "message": "The selected category is not available for your tenant",
    "details": {
      "availableCategories": ["cat_001", "cat_002"],
      "requestedCategory": "cat_003"
    },
    "requestId": "req_abcdef123456",
    "timestamp": "2025-01-23T10:45:00Z"
  }
}

Best Practices

Category Selection: Choose the appropriate category based on customer profile and business requirements
Smart Categorization: Use parametrization to enable/disable features based on customer needs
Document Quality: Ensure uploaded documents are clear and meet the specified requirements
Beneficiary Management: Add beneficiaries before creating payment consents
Payment Consent: Always create consents for controlled and secure transfers
Three-Step Transfer: Follow the allowed operations → prepare → execute flow for all transfers
Session Management: Maintain proper session tokens for customer operations
Webhook Integration: Implement webhooks for real-time status updates

Security Considerations

Use separate tokens for admin operations (customer creation) and customer operations (transfers)
Implement proper session management with X-Session-Id headers
Store sensitive data (customer IDs, wallet IDs) securely
Validate all inputs before API submission
Monitor for suspicious activities using transaction patterns

Next Steps

After successfully opening an individual account:

About FinHub

​Individual Account Opening

​Overview

​Complete Flow Sequence

​Prerequisites

​Step 1: Get Categorization Hierarchy

​API Request

​Response

​Step 2: Register Individual Customer

​API Request

​Request Body

​Response

​Step 3: Upload Verification Documents

​API Request

​Request Body

​Response

​Step 4: Activate Customer Account

​API Request

​Request Body

​Response

​Step 5: Set Up Beneficiaries

​API Request

​Request Body

​Response

​Step 6: Create Payment Consent (Optional)

​API Request

​Request Body

​Response

​Step 7: Execute a Transfer (Three-Step Process)

​7.1 Check Allowed Operations

​7.2 Prepare Order

​7.3 Execute Order

​Complete Flow Summary

​Error Handling

​Example Error Response

​Best Practices

​Security Considerations

​Next Steps

​Related API Documentation

Individual Account Opening

Overview

Complete Flow Sequence

Prerequisites

Step 1: Get Categorization Hierarchy

API Request

Response

Step 2: Register Individual Customer

API Request

Request Body

Response

Step 3: Upload Verification Documents

API Request

Request Body

Response

Step 4: Activate Customer Account

API Request

Request Body

Response

Step 5: Set Up Beneficiaries

API Request

Request Body

Response

Step 6: Create Payment Consent (Optional)

API Request

Request Body

Response

Step 7: Execute a Transfer (Three-Step Process)

7.1 Check Allowed Operations

7.2 Prepare Order

7.3 Execute Order

Complete Flow Summary

Error Handling

Example Error Response

Best Practices

Security Considerations

Next Steps

Related API Documentation