​
Beneficiary Management Flow

This guide details the complete beneficiary management process in the FinHub platform. Beneficiaries are external accounts to which customers can send funds, and proper management of these entities is crucial for secure and efficient transfers.

​
Flow Overview

The following sequence diagram illustrates the beneficiary management process:

​
Detailed API Flow

​
Step 1: IBAN Validation

Before creating a beneficiary, the system validates the IBAN format based on country-specific rules. Client-Side Validation: The system performs initial validation on the client side to ensure the IBAN follows the correct format for the specified country:
  • Each country has specific IBAN length requirements
  • The IBAN must follow the correct structure (country code, check digits, bank code, account number)
  • Basic checksum validation is performed
Implementation Notes:
  • Client-side validation provides immediate feedback to users
  • This is a preliminary check before server-side validation
  • The validation rules are based on the ISO 13616 standard
  • Different countries have different IBAN formats and lengths

​
Step 2: Create Beneficiary

After initial validation, the system creates a new beneficiary with the provided details. API Request: 
POST /api/v2/customer/beneficiaries
Content-Type: application/json
Authorization: Bearer {access_token}
Request Body: 
{
  "name": "Jane Smith",
  "iban": "DE89370400440532013000",
  "country": "DE",
  "bankName": "Deutsche Bank",
  "address": "Mainzer Landstrasse 16-24",
  "city": "Frankfurt",
  "postalCode": "60325",
  "countryOfResidence": "DE",
  "description": "Rent payment recipient"
}
Response: 
{
  "beneficiaryId": "ben_12345678",
  "name": "Jane Smith",
  "iban": "DE89370400440532013000",
  "country": "DE",
  "bankName": "Deutsche Bank",
  "address": "Mainzer Landstrasse 16-24",
  "city": "Frankfurt",
  "postalCode": "60325",
  "countryOfResidence": "DE",
  "description": "Rent payment recipient",
  "status": "ACTIVE",
  "createdAt": "2025-06-01T10:15:00Z"
}
Implementation Notes:
  • The system performs comprehensive server-side IBAN validation
  • The beneficiary is created with an ACTIVE status by default
  • The beneficiary ID is used for future transactions
  • The system may have limits on the number of beneficiaries per customer

​
Step 3: Retrieve Beneficiaries

Customers can retrieve their list of beneficiaries at any time. API Request: 
GET /api/v2/customer/beneficiaries
Content-Type: application/json
Authorization: Bearer {access_token}
Response: 
{
  "beneficiaries": [
    {
      "beneficiaryId": "ben_12345678",
      "name": "Jane Smith",
      "iban": "DE89370400440532013000",
      "country": "DE",
      "bankName": "Deutsche Bank",
      "address": "Mainzer Landstrasse 16-24",
      "city": "Frankfurt",
      "postalCode": "60325",
      "countryOfResidence": "DE",
      "description": "Rent payment recipient",
      "status": "ACTIVE",
      "createdAt": "2025-06-01T10:15:00Z"
    },
    {
      "beneficiaryId": "ben_87654321",
      "name": "John Johnson",
      "iban": "FR7630006000011234567890189",
      "country": "FR",
      "bankName": "BNP Paribas",
      "address": "16 Boulevard des Italiens",
      "city": "Paris",
      "postalCode": "75009",
      "countryOfResidence": "FR",
      "description": "Business partner",
      "status": "ACTIVE",
      "createdAt": "2025-05-15T14:30:00Z"
    }
  ]
}
Implementation Notes:
  • The response includes all active beneficiaries
  • Beneficiaries are sorted by creation date (newest first)
  • The system may implement pagination for customers with many beneficiaries
  • The response includes all details needed for displaying beneficiaries

​
Step 4: Update Beneficiary

Customers can update the details of an existing beneficiary. API Request: 
PUT /api/v2/customer/beneficiaries/{beneficiaryId}
Content-Type: application/json
Authorization: Bearer {access_token}
Request Body: 
{
  "name": "Jane Smith",
  "address": "New Street 123",
  "city": "Berlin",
  "postalCode": "10115",
  "description": "Updated description"
}
Response: 
{
  "beneficiaryId": "ben_12345678",
  "name": "Jane Smith",
  "iban": "DE89370400440532013000",
  "country": "DE",
  "bankName": "Deutsche Bank",
  "address": "New Street 123",
  "city": "Berlin",
  "postalCode": "10115",
  "countryOfResidence": "DE",
  "description": "Updated description",
  "status": "ACTIVE",
  "createdAt": "2025-06-01T10:15:00Z",
  "updatedAt": "2025-06-01T11:30:00Z"
}
Implementation Notes:
  • Certain fields may be immutable (e.g., IBAN, country)
  • If the IBAN needs to be changed, a new beneficiary should be created
  • The system maintains an audit trail of all updates
  • The updated beneficiary maintains the same ID

​
Step 5: Delete Beneficiary

Customers can remove a beneficiary from their list. API Request: 
DELETE /api/v2/customer/beneficiaries/{beneficiaryId}
Content-Type: application/json
Authorization: Bearer {access_token}
Response: 
{
  "status": "SUCCESS",
  "message": "Beneficiary successfully deleted",
  "beneficiaryId": "ben_12345678"
}
Implementation Notes:
  • Deletion may be logical rather than physical (status changed to INACTIVE)
  • The system maintains records for compliance and audit purposes
  • Deleted beneficiaries cannot be used for new transactions
  • The customer may need to confirm deletion for security purposes

​
Using Beneficiaries in Transactions

Once beneficiaries are created, they can be used in transaction flows:

​
SEPA Transfer to Beneficiary

API Request: 
POST /api/v2/wallet/send-fund
Content-Type: application/json
Authorization: Bearer {access_token}
Request Body: 
{
  "sourceWalletAddress": "0x1234567890abcdef",
  "amount": "100.00",
  "currency": "EUR",
  "beneficiaryId": "ben_12345678",
  "description": "Monthly rent payment"
}
Response: 
{
  "orderId": "order_12345678",
  "transactionId": "txn_12345678",
  "status": "PROCESSING",
  "createdAt": "2025-06-01T09:45:00Z",
  "estimatedCompletionTime": "2025-06-01T10:00:00Z"
}
Implementation Notes:
  • Using a beneficiary ID simplifies the transaction process
  • The system retrieves all necessary beneficiary details automatically
  • This approach reduces the risk of errors in transaction details
  • The beneficiary information is validated again before processing the transaction

​
IBAN Validation Rules

The system implements comprehensive IBAN validation based on international standards:
  1. Format Validation:
    • Country-specific length (e.g., Germany: 22 characters, France: 27 characters)
    • Correct structure (country code, check digits, bank code, account number)
    • Valid characters (alphanumeric only)
  2. Checksum Validation:
    • MOD-97 operation as specified in the ISO 13616 standard
    • Converts letters to numbers and performs mathematical validation
  3. Bank Code Validation:
    • Validates that the bank code portion of the IBAN exists
    • Checks against a database of valid bank codes by country
  4. Country-Specific Rules:
    • Each country may have additional validation rules
    • Special formatting requirements for specific countries

​
Error Handling

The beneficiary management process includes comprehensive error handling for various scenarios:
Error ScenarioError CodeDescription
Invalid IBAN formatINVALID_IBAN_FORMATThe IBAN format does not match the country’s requirements
Invalid IBAN checksumINVALID_IBAN_CHECKSUMThe IBAN checksum validation failed
Invalid bank codeINVALID_BANK_CODEThe bank code in the IBAN is not valid
Duplicate beneficiaryDUPLICATE_BENEFICIARYA beneficiary with the same IBAN already exists
Beneficiary limit reachedBENEFICIARY_LIMIT_REACHEDThe maximum number of beneficiaries has been reached
Beneficiary not foundBENEFICIARY_NOT_FOUNDThe specified beneficiary ID does not exist
Unauthorized accessUNAUTHORIZED_ACCESSThe customer does not have permission to access this beneficiary

​
Security Considerations

When implementing the beneficiary management flow, consider the following security measures:
  1. Verification Period: Implement a waiting period before allowing transactions to new beneficiaries
  2. Transaction Limits: Apply lower limits for transactions to new beneficiaries
  3. Notification System: Send notifications when beneficiaries are added, modified, or deleted
  4. Two-Factor Authentication: Require 2FA for adding or modifying beneficiaries
  5. Audit Trail: Maintain a comprehensive audit trail of all beneficiary-related actions
  6. Suspicious Activity Monitoring: Monitor for unusual patterns in beneficiary management

​
Next Steps

After implementing the beneficiary management flow, consider:
  1. Implementing recurring payments to beneficiaries
  2. Setting up beneficiary groups for batch payments
  3. Adding international wire transfer capabilities
  4. Implementing advanced fraud detection for external transfers