B2B and Tenant Business Flow

This guide details the complete business customer (B2B) and tenant management processes in the FinHub platform. These flows include business registration, authentication, wallet management, and transaction processing specifically for business customers and tenants.

Flow Overview

The following sequence diagram illustrates the B2B/Tenant process:

Detailed API Flow

Step 1: Register Business Customer

The first step is to register a business customer with organization details. API Request:

POST /api/v2/business/register
Content-Type: application/json

Request Body:

{
  "organization": {
    "name": "Acme Corporation",
    "registrationNumber": "12345678",
    "taxId": "DE123456789",
    "industry": "Technology",
    "website": "https://acme-corp.example.com",
    "address": {
      "street": "Tech Boulevard 123",
      "city": "Berlin",
      "postalCode": "10115",
      "country": "DE"
    }
  },
  "administrator": {
    "firstName": "John",
    "lastName": "Smith",
    "email": "john.smith@acme-corp.example.com",
    "password": "SecureP@ssw0rd",
    "position": "Chief Financial Officer",
    "phoneNumber": "+4930123456789"
  }
}

Response:

{
  "customerId": "cust_b2b_12345678",
  "organizationId": "org_12345678",
  "status": "PENDING_VERIFICATION",
  "createdAt": "2025-06-01T09:15:00Z"
}

Implementation Notes:

The system creates both a business customer and an organization
The initial status is set to PENDING_VERIFICATION
The customer ID and organization ID are stored in localStorage
The administrator becomes the first user of the business account

Step 2: B2B Authentication

Business customers authenticate using their credentials with a specific account type. API Request:

POST /api/v2/auth/token
Content-Type: application/json

Request Body:

{
  "username": "john.smith@acme-corp.example.com",
  "password": "SecureP@ssw0rd",
  "accountType": "B2B"
}

Response:

{
  "bffToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "userToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "sessionId": "sess_b2b_12345678",
  "customerId": "cust_b2b_12345678",
  "organizationId": "org_12345678",
  "tenantId": "tenant_12345678",
  "expiresIn": 3600
}

Implementation Notes:

The authentication process identifies the user as a B2B customer
The response includes tenant-specific information
The tokens and IDs are stored in localStorage
The session has an expiration time (typically 1 hour)

Step 3: Get Customer Wallets

Business customers can retrieve their organization’s wallet information. API Request:

POST /api/v2/wallet/customer-wallets
Content-Type: application/json
Authorization: Bearer {bffToken}

Request Body:

{
  "customerId": "cust_b2b_12345678",
  "tenantId": "tenant_12345678"
}

Response:

{
  "wallets": [
    {
      "walletId": "wallet_b2b_12345678",
      "walletAddress": "0xb2b1234567890abcdef",
      "walletType": "FIAT",
      "currency": "EUR",
      "balance": "10000.50",
      "availableBalance": "9500.25",
      "status": "ACTIVE",
      "createdAt": "2025-05-15T10:30:00Z"
    },
    {
      "walletId": "wallet_b2b_87654321",
      "walletAddress": "0xb2babcdef1234567890",
      "walletType": "FIAT",
      "currency": "USD",
      "balance": "5000.00",
      "availableBalance": "5000.00",
      "status": "ACTIVE",
      "createdAt": "2025-05-16T14:20:00Z"
    }
  ]
}

Implementation Notes:

The request includes tenant-specific headers
The system returns all wallets associated with the business customer
Each wallet includes its current balance and available balance
Business wallets may have different limits than individual wallets

Step 4: Create Order (SEPA Transfer)

Business customers can initiate transactions from their wallets. API Request:

POST /api/v2/wallet/create-order
Content-Type: application/json
Authorization: Bearer {bffToken}

Request Body:

{
  "customerId": "cust_b2b_12345678",
  "tenantId": "tenant_12345678",
  "orderOperationType": "SEPA_TRANSFER",
  "sourceEntity": {
    "walletAddress": "0xb2b1234567890abcdef",
    "currency": "EUR"
  },
  "destinationEntity": {
    "iban": "DE89370400440532013000",
    "name": "Supplier GmbH",
    "bankName": "Deutsche Bank",
    "country": "DE"
  },
  "orderAmount": {
    "amount": "1000.00",
    "currency": "EUR"
  },
  "orderContext": {
    "description": "Invoice payment #INV-2025-001",
    "reference": "INV-2025-001"
  }
}

Response:

{
  "orderId": "order_b2b_12345678",
  "transactionId": "txn_b2b_12345678",
  "status": "PROCESSING",
  "createdAt": "2025-06-01T09:45:00Z",
  "estimatedCompletionTime": "2025-06-01T10:00:00Z"
}

Implementation Notes:

The request includes tenant-specific parameters
Business transactions may require additional approval based on amount
The system creates an order and a transaction record
Initial status is PROCESSING
Business transactions may have different fee structures

Step 5: Get Transaction History

Business customers can view their transaction history with tenant-specific filtering. API Request:

POST /api/v2/wallet/transaction-history
Content-Type: application/json
Authorization: Bearer {bffToken}

Request Body:

{
  "consumerId": "cust_b2b_12345678",
  "tenantId": "tenant_12345678",
  "pageNumber": 0,
  "pageSize": 10,
  "searchKey": "",
  "fromDate": "2025-05-01T00:00:00Z",
  "toDate": "2025-06-01T23:59:59Z"
}

Response:

{
  "over_all_transaction_history_by_customer": [
    {
      "transactionId": "txn_b2b_12345678",
      "orderId": "order_b2b_12345678",
      "transactionType": "TRANSFER",
      "amount": "1000.00",
      "currency": "EUR",
      "status": "COMPLETED",
      "sourceWallet": "0xb2b1234567890abcdef",
      "destinationWallet": "IBAN: DE89370400440532013000",
      "fee": "2.50",
      "description": "Invoice payment #INV-2025-001",
      "reference": "INV-2025-001",
      "createdAt": "2025-05-20T09:15:00Z",
      "completedAt": "2025-05-20T09:20:00Z"
    },
    {
      "transactionId": "txn_b2b_87654321",
      "orderId": "order_b2b_87654321",
      "transactionType": "DEPOSIT",
      "amount": "5000.00",
      "currency": "EUR",
      "status": "COMPLETED",
      "sourceWallet": "External Bank Transfer",
      "destinationWallet": "0xb2b1234567890abcdef",
      "fee": "0.00",
      "description": "Initial account funding",
      "createdAt": "2025-05-15T14:30:00Z",
      "completedAt": "2025-05-15T14:35:00Z"
    }
  ],
  "total_count": 15
}

Implementation Notes:

The response includes pagination information
Transactions can be filtered by date range and search term
Each transaction includes detailed information about the source and destination
Business transactions may include additional reference information

Step 6: B2B User Management

Business administrators can manage users within their organization. API Request to get user list:

GET /api/v2/business/users?page=0&take=10&searchTerm=&order=desc
Content-Type: application/json
Authorization: Bearer {bffToken}

Response:

{
  "users": [
    {
      "customerId": "cust_b2b_user_12345678",
      "firstName": "John",
      "middleName": "",
      "lastName": "Smith",
      "email": "john.smith@acme-corp.example.com",
      "phone": {
        "number": "+4930123456789",
        "code": "+49",
        "country": "DE"
      },
      "status": "ACTIVE",
      "role": {
        "id": "role_admin",
        "name": "Administrator"
      },
      "createdAt": "2025-05-15T10:30:00Z"
    },
    {
      "customerId": "cust_b2b_user_87654321",
      "firstName": "Jane",
      "middleName": "",
      "lastName": "Doe",
      "email": "jane.doe@acme-corp.example.com",
      "phone": {
        "number": "+4930987654321",
        "code": "+49",
        "country": "DE"
      },
      "status": "ACTIVE",
      "role": {
        "id": "role_finance",
        "name": "Finance Manager"
      },
      "createdAt": "2025-05-16T14:20:00Z"
    }
  ],
  "total": 2,
  "page": 0,
  "take": 10
}

API Request to create a new user:

POST /api/v2/business/users
Content-Type: application/json
Authorization: Bearer {bffToken}

Request Body:

{
  "firstName": "Michael",
  "middleName": "",
  "lastName": "Johnson",
  "sourceData": "B2B Platform",
  "phone": {
    "number": "+4930456789123",
    "code": "+49",
    "country": "DE"
  },
  "email": "michael.johnson@acme-corp.example.com",
  "status": "Active",
  "role": {
    "id": "role_accountant",
    "name": "Accountant"
  }
}

Response:

{
  "customerId": "cust_b2b_user_45678901",
  "firstName": "Michael",
  "middleName": "",
  "lastName": "Johnson",
  "email": "michael.johnson@acme-corp.example.com",
  "phone": {
    "number": "+4930456789123",
    "code": "+49",
    "country": "DE"
  },
  "status": "ACTIVE",
  "role": {
    "id": "role_accountant",
    "name": "Accountant"
  },
  "createdAt": "2025-06-01T11:30:00Z"
}

Implementation Notes:

Only users with administrative privileges can manage other users
The system sends an invitation email to new users
New users must complete their registration process
User roles determine permissions within the system

Tenant Resolution

The system resolves the appropriate tenant during the authentication process: API Request:

POST /api/v2/auth/token
Content-Type: application/json

Request Body:

{
  "username": "john.smith@acme-corp.example.com",
  "password": "SecureP@ssw0rd",
  "accountType": "B2B",
  "clientId": "client_12345678",
  "clientSecret": "cs_abcdef1234567890"
}

Response:

{
  "bffToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "userToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "sessionId": "sess_b2b_12345678",
  "customerId": "cust_b2b_12345678",
  "organizationId": "org_12345678",
  "tenantId": "tenant_12345678",
  "expiresIn": 3600
}

Implementation Notes:

Client credentials are validated to resolve the appropriate tenant
The tenant ID is included in the authentication response
All subsequent API calls include the tenant ID
The system maintains a mapping between client credentials and tenants

Shareholder and Director Registration

Business customers can register shareholders and directors for their organization:

Shareholder Registration

API Request:

POST /api/v2/business/entities
Content-Type: application/json
Authorization: Bearer {bffToken}

Request Body:

{
  "shareholders": [
    {
      "type": "SHAREHOLDER",
      "position": "shareholders",
      "personFullname": "Sarah Johnson",
      "sharePercentage": "25",
      "person": {
        "firstName": { "name": "Sarah" },
        "lastName": { "name": "Johnson" },
        "dateOfBirth": "1980-03-15",
        "nationality": "United States",
        "email": "sarah.johnson@example.com",
        "addressLineOne": "123 Main Street, New York",
        "telephoneNumbers": [{ "number": "+12125551234" }]
      }
    }
  ]
}

Response:

{
  "entityId": "entity_12345678",
  "type": "SHAREHOLDER",
  "status": "PENDING_VERIFICATION",
  "createdAt": "2025-06-01T12:15:00Z"
}

Director Registration

API Request:

POST /api/v2/business/entities
Content-Type: application/json
Authorization: Bearer {bffToken}

Request Body:

{
  "directors": [
    {
      "type": "DIRECTOR",
      "position": "directors",
      "personFullname": "Robert Brown",
      "person": {
        "firstName": { "name": "Robert" },
        "lastName": { "name": "Brown" },
        "dateOfBirth": "1975-08-22",
        "nationality": "United Kingdom",
        "email": "robert.brown@example.com",
        "addressLineOne": "45 Oxford Street, London",
        "telephoneNumbers": [{ "number": "+442071234567" }]
      }
    }
  ]
}

Response:

{
  "entityId": "entity_87654321",
  "type": "DIRECTOR",
  "status": "PENDING_VERIFICATION",
  "createdAt": "2025-06-01T12:30:00Z"
}

Implementation Notes:

After registration, the system sends credentials to shareholders and directors
They must complete their own verification process
Documents may need to be uploaded for verification
The business customer can track the status of all entities

Error Handling

The B2B/Tenant processes include comprehensive error handling for various scenarios:

Error Scenario	Error Code	Description
Invalid business details	INVALID_BUSINESS_DETAILS	The provided business information is invalid
Duplicate business	DUPLICATE_BUSINESS	A business with this registration number already exists
Invalid tenant credentials	INVALID_TENANT_CREDENTIALS	The provided client ID or client secret is invalid
Tenant not found	TENANT_NOT_FOUND	The specified tenant does not exist
Insufficient permissions	INSUFFICIENT_PERMISSIONS	The user does not have permission for this action
Invalid role	INVALID_ROLE	The specified role does not exist
User limit reached	USER_LIMIT_REACHED	The maximum number of users has been reached

Implementation Considerations

When implementing the B2B/Tenant flows, consider the following:

Multi-Tenancy: Ensure proper isolation between different business tenants
Role-Based Access Control: Implement comprehensive permission management
Audit Trail: Maintain detailed logs of all business activities
Compliance: Ensure all business processes comply with relevant regulations
Scalability: Design the system to handle multiple businesses with many users
Security: Implement proper authentication and authorization for all business operations
Integration: Provide APIs for integration with business systems (ERP, accounting)

Next Steps

After implementing the B2B/Tenant flows, consider:

About FinHub

​B2B and Tenant Business Flow

​Flow Overview

​Detailed API Flow

​Step 1: Register Business Customer

​Step 2: B2B Authentication

​Step 3: Get Customer Wallets

​Step 4: Create Order (SEPA Transfer)

​Step 5: Get Transaction History

​Step 6: B2B User Management

​Tenant Resolution

​Shareholder and Director Registration

​Shareholder Registration

​Director Registration

​Error Handling

​Implementation Considerations

​Next Steps

B2B and Tenant Business Flow

Flow Overview

Detailed API Flow

Step 1: Register Business Customer

Step 2: B2B Authentication

Step 3: Get Customer Wallets

Step 4: Create Order (SEPA Transfer)

Step 5: Get Transaction History

Step 6: B2B User Management

Tenant Resolution

Shareholder and Director Registration

Shareholder Registration

Director Registration

Error Handling

Implementation Considerations

Next Steps