Beneficiary Management Flow

This guide details the complete beneficiary management process in the FinHub platform v2.1. The new APIs integrate beneficiary management with payment consents, providing enhanced security through beneficiary restrictions and transaction limits. This approach ensures that transfers can only be made to pre-approved beneficiaries with defined limits.

Flow Overview

The following sequence diagram illustrates the enhanced beneficiary management process with payment consent integration:

Prerequisites

Before managing beneficiaries:

Customer must be activated - With active wallet and IBAN
Customer must be authenticated - Valid customer token required
Session must be established - X-Session-Id header required
Wallet ID must be available - From customer activation

Detailed API Flow

Step 1: Create Beneficiary

Add a new beneficiary to enable transfers. The v2.1 API provides comprehensive validation and supports both individual and business beneficiaries. API Request:

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

Request Body (Individual):

{
  "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",
  "relationship": "LANDLORD",
  "metadata": {
    "reference": "Monthly rent payment",
    "accountNumber": "0532013000"
  }
}

Request Body (Business):

{
  "partyType": "BUSINESS_CUSTOMER",
  "companyName": "Acme Corporation Ltd",
  "shortName": "Acme Corp",
  "iban": "FR1420041010050500013M02606",
  "currency": "EUR",
  "country": "FR",
  "email": "payments@acmecorp.com",
  "phoneNumber": "+33123456789",
  "bicSwiftCode": "BNPAFRPP",
  "networkName": "SEPA",
  "bankName": "BNP Paribas",
  "bankAddress": "16 Boulevard des Italiens, 75009 Paris, France",
  "purposeCode": "SUPP",
  "vatNumber": "FR12345678901",
  "registrationNumber": "123456789"
}

Response:

{
  "data": {
    "id": "ben_abc123xyz789",
    "partyType": "INDIVIDUAL_CUSTOMER",
    "firstName": "Jane",
    "lastName": "Smith",
    "shortName": "Jane Smith",
    "iban": "DE89370400440532013000",
    "bicSwiftCode": "DEUTDEFF",
    "networkName": "SEPA",
    "status": "ACTIVE",
    "verificationStatus": "VERIFIED",
    "validationDetails": {
      "ibanValid": true,
      "bicValid": true,
      "nameMatching": "VERIFIED",
      "sanctionsCheck": "PASSED"
    },
    "createdAt": "2025-01-23T10:15:00Z"
  }
}

Key Features:

Automatic IBAN/BIC Validation: Server-side validation using SWIFT standards
Name Matching: Verifies beneficiary name against banking records
Sanctions Screening: Automatic check against sanctions lists
Network Detection: Automatically determines payment network (SEPA, SWIFT, etc.)

Step 2: List Beneficiaries

Retrieve all beneficiaries with filtering and pagination support. API Request:

GET /api/v2.1/fintrans/{walletId}/beneficiaries?page=0&size=20&sort=createdAt,desc
Content-Type: application/json
Authorization: Bearer {customer_token}
X-Tenant-ID: {tenant_id}
X-Session-Id: {session_id}

Response:

{
  "data": [
    {
      "id": "ben_abc123xyz789",
      "partyType": "INDIVIDUAL_CUSTOMER",
      "shortName": "Jane Smith",
      "iban": "DE89370400440532013000",
      "bicSwiftCode": "DEUTDEFF",
      "networkName": "SEPA",
      "currency": "EUR",
      "status": "ACTIVE",
      "verificationStatus": "VERIFIED",
      "lastUsed": "2025-01-20T15:30:00Z",
      "createdAt": "2025-01-15T10:15:00Z"
    },
    {
      "id": "ben_def456ghi012",
      "partyType": "BUSINESS_CUSTOMER",
      "shortName": "Acme Corp",
      "iban": "FR1420041010050500013M02606",
      "bicSwiftCode": "BNPAFRPP",
      "networkName": "SEPA",
      "currency": "EUR",
      "status": "ACTIVE",
      "verificationStatus": "VERIFIED",
      "lastUsed": null,
      "createdAt": "2025-01-10T14:30:00Z"
    }
  ],
  "pagination": {
    "page": 0,
    "size": 20,
    "totalElements": 2,
    "totalPages": 1
  }
}

The key innovation in v2.1 is integrating beneficiaries with payment consents for enhanced security. 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": "10000.00",
    "dailyLimit": "20000.00",
    "weeklyLimit": "50000.00",
    "monthlyLimit": "100000.00",
    "currency": "EUR"
  },
  "beneficiaryRestrictions": {
    "enabled": true,
    "allowedBeneficiaries": [
      "ben_abc123xyz789",
      "ben_def456ghi012"
    ],
    "allowNewBeneficiaries": false
  },
  "validFrom": "2025-01-23",
  "validUntil": "2026-01-23",
  "description": "Restricted payment consent for approved beneficiaries only",
  "requiresCustomerAcceptance": true
}

Response:

{
  "data": {
    "id": "consent_xyz789abc123",
    "consentReference": "consent-payment-restricted-001",
    "status": "ACTIVE",
    "paymentType": "TRANSFER",
    "beneficiaryRestrictions": {
      "enabled": true,
      "allowedBeneficiaries": [
        {
          "id": "ben_abc123xyz789",
          "shortName": "Jane Smith"
        },
        {
          "id": "ben_def456ghi012",
          "shortName": "Acme Corp"
        }
      ],
      "allowNewBeneficiaries": false
    },
    "limits": {
      "maxAmountPerTransaction": "10000.00",
      "dailyLimit": "20000.00",
      "currency": "EUR"
    },
    "validUntil": "2026-01-23",
    "createdAt": "2025-01-23T11:00:00Z"
  }
}

Benefits of Beneficiary-Restricted Consents:

Enhanced Security: Transfers only allowed to pre-approved beneficiaries
Fraud Prevention: Prevents unauthorized transfers to unknown accounts
Compliance: Meets regulatory requirements for transaction monitoring
Customer Control: Customers explicitly approve beneficiaries

Step 4: Using Beneficiaries in Transfers

With beneficiaries and consents set up, execute transfers using the three-step process.

4.1 Prepare Transfer Order

API Request:

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}

Request Body:

{
  "amount": {
    "value": "150000",  // €1,500.00 in cents
    "scale": 2,
    "currency": "EUR"
  },
  "operationType": "TRANSFER",
  "target": {
    "iban": "DE89370400440532013000",  // Must match beneficiary IBAN
    "name": "Jane Smith"
  },
  "reference": "Monthly rent payment - January 2025",
  "consent": {
    "consentReference": "consent-payment-restricted-001"
  }
}

Response with Consent Validation:

{
  "data": {
    "orderId": "prep_order_rent_001",
    "status": "PREPARED",
    "validations": {
      "consentValid": true,
      "beneficiaryAllowed": true,
      "withinLimits": true,
      "sufficientBalance": true
    },
    "beneficiaryDetails": {
      "id": "ben_abc123xyz789",
      "shortName": "Jane Smith",
      "verified": true
    },
    "totalAmount": {
      "value": "151500",  // Including fees
      "currency": "EUR"
    }
  }
}

Managing Beneficiaries Over Time

Update Beneficiary Metadata

While core details like IBAN cannot be changed, metadata can be updated:

PATCH /api/v2.1/fintrans/{walletId}/beneficiaries/{beneficiaryId}

{
  "metadata": {
    "reference": "Updated rent payment account",
    "category": "HOUSING",
    "notes": "New rental agreement from Feb 2025"
  }
}

Deactivate Beneficiary

Instead of deletion, beneficiaries can be deactivated:

POST /api/v2.1/fintrans/{walletId}/beneficiaries/{beneficiaryId}/deactivate

Deactivated beneficiaries:

Cannot be used in new transfers
Are excluded from new payment consents
Remain in history for audit purposes

Advanced Features

Beneficiary Categories

{
  "category": "UTILITIES",  // HOUSING, UTILITIES, SALARY, SUPPLIER, OTHER
  "tags": ["monthly", "recurring", "essential"]
}

Bulk Beneficiary Import

For business customers managing many beneficiaries:

POST /api/v2.1/fintrans/{walletId}/beneficiaries/bulk

{
  "beneficiaries": [
    // Array of beneficiary objects
  ],
  "validationMode": "STRICT"  // STRICT or LENIENT
}

Error Handling

Error Code	HTTP Status	Description
INVALID_IBAN	400	IBAN format or checksum invalid
INVALID_BIC	400	BIC/SWIFT code invalid
DUPLICATE_BENEFICIARY	409	Beneficiary with same IBAN exists
BENEFICIARY_NOT_IN_CONSENT	403	Beneficiary not allowed by consent
SANCTIONS_CHECK_FAILED	422	Beneficiary failed sanctions screening
NAME_MISMATCH	422	Beneficiary name doesn’t match bank records
NETWORK_NOT_SUPPORTED	422	Payment network not available
LIMIT_EXCEEDED	429	Too many beneficiaries

Security Best Practices

Cooling-Off Period: New beneficiaries require 24-hour wait before first transfer
Two-Factor Authentication: Require 2FA for adding beneficiaries
Notification System: Email/SMS alerts for beneficiary changes
Regular Review: Prompt customers to review beneficiaries quarterly
Suspicious Pattern Detection: Monitor for rapid beneficiary additions
Consent Integration: Always use payment consents with beneficiary restrictions

Compliance Considerations

AML Screening: All beneficiaries undergo automated AML checks
Sanctions Lists: Real-time screening against global sanctions
Tax Reporting: Track transfers for regulatory reporting
Data Retention: Maintain beneficiary records per regulations
Cross-Border Rules: Apply country-specific transfer restrictions

Next Steps

After implementing beneficiary management:

About FinHub

​Beneficiary Management Flow

​Flow Overview

​Prerequisites

​Detailed API Flow

​Step 1: Create Beneficiary

​Step 2: List Beneficiaries

​Step 3: Create Payment Consent with Beneficiary Restrictions

​Step 4: Using Beneficiaries in Transfers

​4.1 Prepare Transfer Order

​Managing Beneficiaries Over Time

​Update Beneficiary Metadata

​Deactivate Beneficiary

​Advanced Features

​Beneficiary Categories

​Bulk Beneficiary Import

​Error Handling

​Security Best Practices

​Compliance Considerations

​Next Steps

​Related API Documentation

Beneficiary Management Flow

Flow Overview

Prerequisites

Detailed API Flow

Step 1: Create Beneficiary

Step 2: List Beneficiaries

Step 3: Create Payment Consent with Beneficiary Restrictions

Step 4: Using Beneficiaries in Transfers

4.1 Prepare Transfer Order

Managing Beneficiaries Over Time

Update Beneficiary Metadata

Deactivate Beneficiary

Advanced Features

Beneficiary Categories

Bulk Beneficiary Import

Error Handling

Security Best Practices

Compliance Considerations

Next Steps

Related API Documentation