> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finhub.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Core Integration Flows

> Complete customer lifecycle flows for Individual (B2C) and Organization (B2B) customers

# Core Integration Flows

This section provides comprehensive guides for implementing the complete customer lifecycle - from registration through to active payment operations.

## Customer Lifecycle Overview

Both Individual (B2C) and Organization (B2B) customers follow a **linear flow** with strict prerequisites at each phase. Operations are blocked until all requirements are met.

```mermaid theme={null}
flowchart LR
    A[Registration] --> B[Session]
    B --> C[Verification]
    C --> D[Consents]
    D --> E[Activation]
    E --> F[Operations]
    
    style A fill:#e1f5fe
    style B fill:#e1f5fe
    style C fill:#fff3e0
    style D fill:#fff3e0
    style E fill:#e8f5e9
    style F fill:#e8f5e9
```

## Flow Timeline Comparison

| Phase                  | Individual (B2C) | Organization (B2B) |
| ---------------------- | ---------------- | ------------------ |
| **Registration**       | 5 minutes        | 10 minutes         |
| **Personnel Setup**    | N/A              | 20 minutes         |
| **Verification**       | 1-3 days (KYC)   | 2-5 days (KYB)     |
| **Consent Acceptance** | 5 minutes        | 10 minutes         |
| **Activation**         | Instant          | Instant            |
| **Operations**         | Ongoing          | Ongoing            |
| **Total**              | \~1-3 days       | \~2-5 days         |

***

## Individual Customer (B2C) - 7 Phases

Complete lifecycle for personal/individual customers.

```mermaid theme={null}
flowchart TD
    subgraph Phase1[Phase 1: Registration]
        A1[Get Categorization Hierarchy]
        A2[POST /customer/individual/registration]
        A1 --> A2
    end
    
    subgraph Phase2[Phase 2: Session]
        B1[POST /sessions - Login]
        B2[JWT Token Generated]
        B1 --> B2
    end
    
    subgraph Phase3[Phase 3: Verification]
        C1[Initiate Verification]
        C2[Submit Documents]
        C3[Await Approval]
        C1 --> C2 --> C3
    end
    
    subgraph Phase4[Phase 4: Consents]
        D1[Terms & Conditions]
        D2[Privacy Policy]
        D3[Data Processing]
        D1 --> D2 --> D3
    end
    
    subgraph Phase5[Phase 5: Activation]
        E1[POST /activation]
        E2[IBAN + Wallet Created]
        E1 --> E2
    end
    
    subgraph Phase6[Phase 6: Wallet Ops]
        F1[Get Balance]
        F2[Allowed Operations]
        F1 --> F2
    end
    
    subgraph Phase7[Phase 7: Payments]
        G1[Add Beneficiaries]
        G2[Prepare Order]
        G3[Execute Order]
        G1 --> G2 --> G3
    end
    
    Phase1 --> Phase2 --> Phase3 --> Phase4 --> Phase5 --> Phase6 --> Phase7
```

<CardGroup cols={2}>
  <Card title="B2C Overview" icon="user" href="/baas/api/integration/flows/individual-customer">
    Complete Individual customer flow guide
  </Card>

  <Card title="Phase 1: Registration" icon="user-plus" href="/baas/api/integration/flows/individual-customer/registration">
    Customer registration with categorization
  </Card>

  <Card title="Phase 3: Verification" icon="shield-check" href="/baas/api/integration/flows/individual-customer/verification">
    KYC verification process
  </Card>

  <Card title="Phase 5: Activation" icon="check-circle" href="/baas/api/integration/flows/individual-customer/activation">
    Account activation & wallet creation
  </Card>
</CardGroup>

***

## Organization Customer (B2B) - 8 Phases

Complete lifecycle for business/organization customers with multi-stakeholder management.

```mermaid theme={null}
flowchart TD
    subgraph Phase1[Phase 1: Registration]
        A1[POST /customer/organization/registration]
        A2[Organization Record Created]
        A1 --> A2
    end
    
    subgraph Phase2[Phase 2: Personnel]
        B1[Add Directors]
        B2[Add Shareholders]
        B3[Add Employees]
        B1 --> B2 --> B3
    end
    
    subgraph Phase3[Phase 3: Verification]
        C1[Initiate KYB]
        C2[Upload Documents]
        C3[Await Approval]
        C1 --> C2 --> C3
    end
    
    subgraph Phase4[Phase 4: Consents]
        D1[Org Terms]
        D2[Privacy Policy]
        D3[Data Processing]
        D1 --> D2 --> D3
    end
    
    subgraph Phase5[Phase 5: Activation]
        E1[Role Validation]
        E2[POST /activation]
        E3[IBAN + Wallet Created]
        E1 --> E2 --> E3
    end
    
    subgraph Phase6[Phase 6: Beneficiaries]
        F1[Add Business Beneficiaries]
        F2[PEP/Sanctions Check]
        F1 --> F2
    end
    
    subgraph Phase7[Phase 7: Payment Consent]
        G1[Create Payment Consent]
        G2[Set Limits & Restrictions]
        G1 --> G2
    end
    
    subgraph Phase8[Phase 8: Transactions]
        H1[Fund Wallet]
        H2[Prepare Transfer]
        H3[Execute Transfer]
        H1 --> H2 --> H3
    end
    
    Phase1 --> Phase2 --> Phase3 --> Phase4 --> Phase5 --> Phase6 --> Phase7 --> Phase8
```

<CardGroup cols={2}>
  <Card title="B2B Overview" icon="building" href="/baas/api/integration/flows/organization-customer">
    Complete Organization customer flow guide
  </Card>

  <Card title="Phase 2: Personnel" icon="users" href="/baas/api/integration/flows/organization-customer/personnel-management">
    Directors, shareholders, employees
  </Card>

  <Card title="Phase 3: Verification" icon="file-check" href="/baas/api/integration/flows/organization-customer/verification">
    KYB verification process
  </Card>

  <Card title="Phase 8: Transactions" icon="money-bill-transfer" href="/baas/api/integration/flows/organization-customer/transaction-operations">
    Business payment operations
  </Card>
</CardGroup>

***

## Key Differences: B2C vs B2B

| Aspect              | Individual (B2C)        | Organization (B2B)                                |
| ------------------- | ----------------------- | ------------------------------------------------- |
| **Registration**    | Single endpoint         | Requires separate personnel endpoints             |
| **Personnel**       | N/A                     | Directors, Shareholders, Employees                |
| **First Employee**  | N/A                     | Must have `ADMIN_USER` role                       |
| **Verification**    | KYC (Identity)          | KYB (Business + UBO)                              |
| **Approval Level**  | TENANT or POWER\_TENANT | TENANT (medium-risk)                              |
| **Consent Format**  | `accepted: true`        | Requires `acceptedBy` + `acceptedDate`            |
| **Activation**      | Simple code             | Requires `activationReason` + admin headers       |
| **Document Upload** | Basic fields            | Additional metadata (customerId, accountId, etc.) |

***

## Critical Prerequisites

### For Activation

<Warning>
  **All prerequisites must be met before activation:**

  1. Verification status: `APPROVED`
  2. Terms & Conditions: `ACCEPTED`
  3. Privacy Policy: `ACCEPTED`
  4. Data Processing: `ACCEPTED`
  5. Customer status: Not already `ACTIVE`
</Warning>

### For Transactions

<Info>
  **Required before payment operations:**

  1. Account status: `ACTIVE`
  2. Wallet status: `ACTIVE`
  3. Valid payment consent (for transfers)
  4. Pre-registered beneficiaries
</Info>

***

## Key Characteristics

### Individual Customer (B2C)

* **Risk-Based Processing**: High-risk customers require power tenant approval
* **Consent-Driven**: Operations blocked until required consents accepted
* **Smart Categorization**: Feature-based customer categorization
* **State Machine**: Strict state transitions with no backward movement

### Organization Customer (B2B)

* **Multi-Stakeholder**: Employees, Directors, Shareholders
* **Role-Based Access**: COMPLIANCE\_OFFICER, TRANSACTION\_APPROVER, ADMIN\_USER
* **Dual Record Creation**: Organization + Individual records for personnel
* **Enhanced Verification**: KYB + UBO verification

***

## Common Resources

<CardGroup cols={3}>
  <Card title="Categorization" icon="sitemap" href="/baas/api/integration/flows/common/categorization-hierarchy">
    Smart categorization strategy
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/baas/api/integration/flows/common/error-handling">
    Error scenarios & troubleshooting
  </Card>

  <Card title="Best Practices" icon="lightbulb" href="/baas/api/integration/flows/common/best-practices">
    Implementation best practices
  </Card>
</CardGroup>

***

## Quick Reference

### Individual Customer Endpoints

| Phase          | Endpoint                                                             | Method |
| -------------- | -------------------------------------------------------------------- | ------ |
| Registration   | `/api/v2.1/customer/individual/registration`                         | POST   |
| Categorization | `/api/v2.1/customer/individual/categorization/hierarchy/{tenantId}`  | GET    |
| Session        | `/api/v2.1/customer/individual/{customerId}/users/{userId}/sessions` | POST   |
| Verification   | `/api/v2.1/customer/individual/{customerId}/verification`            | POST   |
| Consents       | `/api/v2.1/customer/individual/{customerId}/consents/{type}`         | POST   |
| Activation     | `/api/v2.1/customer/individual/{customerId}/activation`              | POST   |
| Balance        | `/api/v2.1/fintrans/{accountId}/balance`                             | GET    |
| Beneficiaries  | `/api/v2.1/fintrans/{accountId}/beneficiaries`                       | POST   |
| Transfer       | `/api/v2.1/fintrans/{accountId}/types/transfer/prepare`              | POST   |

### Organization Customer Endpoints

| Phase            | Endpoint                                                        | Method |
| ---------------- | --------------------------------------------------------------- | ------ |
| Registration     | `/api/v2.1/customer/organization/registration`                  | POST   |
| Add Director     | `/api/v2.1/customer/organization/{orgId}/director`              | POST   |
| Add Shareholders | `/api/v2.1/customer/organization/{orgId}/shareholders`          | POST   |
| Add Employee     | `/api/v2.1/customer/organization/{orgId}/employee`              | POST   |
| Verification     | `/api/v2.1/customer/organization/{orgId}/verify`                | POST   |
| Consents         | `/api/v2.1/customer/organization/{orgId}/consents/{type}`       | POST   |
| Activation       | `/api/v2.1/customer/organization/{orgId}/activation`            | POST   |
| Beneficiaries    | `/api/v2.1/fintrans/{accountId}/beneficiaries`                  | POST   |
| Payment Consent  | `/api/v2.1/fintrans/{walletId}/payment-consents/types/transfer` | POST   |
| Transfer         | `/api/v2.1/fintrans/{accountId}/types/transfer/prepare`         | POST   |