# FinHub


---

# About FinHub

Learn about FinHub as a Banking-as-a-Service and Platform-as-a-Service provider


URL: /overview/about



FinHub is a leading provider of Banking-as-a-Service (BaaS) and Platform-as-a-Service (PaaS) solutions for financial institutions, fintechs, enterprises, and marketplaces. We enable our clients to deliver innovative financial services to their customers through our comprehensive suite of products and capabilities.

## Our Mission

Our mission is to democratize financial services by providing the technology infrastructure that allows businesses of all sizes to embed financial capabilities into their products and services. We believe that financial services should be accessible, transparent, and tailored to meet the unique needs of every business and their customers.

## What We Offer

FinHub provides two primary service models:

### Business as a Service (BaaS)

Our BaaS offering enables businesses to integrate banking functionality directly into their products without having to build banking infrastructure from scratch or obtain banking licenses. This includes:

- Account management
- Payment processing
- Card issuance
- Compliance and regulatory support
- Financial transactions
- Multi-currency operations

### Platform as a Service (PaaS)

Our PaaS offering provides direct access to technology connectors for system-to-system integration. This includes:

- Payment gateway connectors (IPG)
- Banking network connectors (SEPA, SWIFT)
- KYC/KYB verification connectors
- Communication connectors (SMS, email)
- Crypto/blockchain connectors

## Our Technology Stack

FinHub's platform is built on a modern, scalable, and secure technology stack that includes:

- Microservices architecture
- Cloud-native infrastructure
- Real-time processing capabilities
- Advanced security protocols
- Compliance-by-design principles
- Global availability and redundancy

## Global Presence

FinHub operates in multiple countries and supports financial operations across various regulatory environments. Our platform is designed to adapt to local regulations while providing a consistent experience for our clients and their customers.

## Next Steps

<CardGroup cols={2}>
  <Card title="Service Models" icon="code-compare" href="/overview/service-models">
    Learn about BaaS and PaaS
  </Card>
  <Card title="Find Your Path" icon="map" href="/overview/find-your-path">
    Choose the right approach for you
  </Card>
</CardGroup>


---

# Overview

Understanding FinHub's service models: BaaS and PaaS


URL: /overview/service-models



FinHub offers two primary service models to serve different client needs: **Business as a Service (BaaS)** and **Platform as a Service (PaaS)**.

## Overview

| Service Model | What It Provides | Integration Type |
|---------------|------------------|------------------|
| **BaaS** | Business processes via microservices | CoreX, API, or Hybrid |
| **PaaS** | Direct connector access | System-to-system |

## Business as a Service (BaaS)

BaaS exposes **business processes** that are shared across organizations. Clients use FinHub's microservices, which are small, automated business areas handling:

- Customer management (onboarding, KYC/KYB)
- Account & wallet management
- Transaction processing
- Order management
- Compliance & back-office operations

### BaaS Service Models

Within BaaS, you can choose how to integrate:

| Service Model | Description | Best For |
|---------------|-------------|----------|
| **CoreX** | White-label front-end solution | Fast launch, minimal development |
| **API** | Direct API integration, build your own UI | Custom experiences, full control |
| **Hybrid** | Combination of CoreX + API | Best of both worlds |

<Card title="Explore BaaS" icon="building" href="/baas/introduction">
  Learn more about Business as a Service
</Card>

## Platform as a Service (PaaS)

PaaS provides **system-to-system integration** — direct access to FinHub's technology connectors without business process logic. This is pure technology integration.

### Available Connectors

- **Acquiring (IPG)** - Card payment gateway
- **Banking Networks** - SEPA, SWIFT, local payment rails
- **KYC/KYB** - Identity verification services
- **Communication** - SMS, email, push notifications
- **Crypto** - Blockchain connectivity

<Card title="Explore PaaS" icon="plug" href="/paas/introduction">
  Learn more about Platform as a Service
</Card>

## Choosing Between BaaS and PaaS

```mermaid
flowchart TD
    A[What do you need?] --> B{Business processes?}
    B -->|Yes| C[BaaS]
    B -->|No, just connectors| D[PaaS]
    
    C --> E{Build your own UI?}
    E -->|No| F[CoreX Service Model]
    E -->|Yes| G[API Service Model]
    E -->|Both| H[Hybrid Service Model]
```

| Question | BaaS | PaaS |
|----------|------|------|
| Need customer onboarding flows? | ✅ | ❌ |
| Need account management? | ✅ | ❌ |
| Need transaction processing with business logic? | ✅ | ❌ |
| Only need payment gateway integration? | ❌ | ✅ |
| Only need KYC/KYB connector? | ❌ | ✅ |
| Have existing systems, need connectors only? | ❌ | ✅ |

## Next Steps

<CardGroup cols={2}>
  <Card title="BaaS Explained" icon="building" href="/overview/service-models/baas-explained">
    Deep dive into BaaS
  </Card>
  <Card title="PaaS Explained" icon="plug" href="/overview/service-models/paas-explained">
    Deep dive into PaaS
  </Card>
</CardGroup>


---

# BaaS Explained

Understanding Business as a Service - business processes and microservices


URL: /overview/service-models/baas-explained



# Business as a Service (BaaS) Explained

Business as a Service (BaaS) is FinHub's comprehensive offering that exposes **business processes** shared across organizations. Unlike PaaS which provides raw technology connectors, BaaS delivers complete business logic through microservices.

## What BaaS Provides

BaaS delivers automated business processes through microservices:

| Microservice | Business Process |
|--------------|------------------|
| **Customer Management** | Onboarding, KYC/KYB verification, customer lifecycle |
| **Account Management** | Account creation, wallets, balance management |
| **Transaction Management** | Payments, transfers, reconciliation |
| **Order Management** | Order creation, processing, fulfillment |
| **Compliance** | AML screening, regulatory reporting |
| **Back Office** | Approvals, case management, operations |

## Service Models Within BaaS

BaaS offers three service models for integration:

### CoreX Service Model

**Pre-built white-label front-end solution**

- Ready-to-use web and mobile applications
- B2C and B2B distribution channels
- Customizable branding (colors, logos, themes)
- Managed by FinHub (updates, maintenance)
- Launch in 2-4 weeks

**Best for:** Companies wanting fast launch with minimal development

### API Service Model

**Direct API integration with your own UI**

- Full API access to all microservices
- Build your own custom user interface
- Complete control over user experience
- Sandbox environment for development
- Webhooks for real-time events

**Best for:** Companies with development teams wanting custom experiences

### Hybrid Service Model

**Combination of CoreX and API**

- Use CoreX for some processes (e.g., onboarding)
- Use API for others (e.g., custom payment flows)
- Flexibility to mix approaches
- Gradual migration path

**Best for:** Companies wanting best of both worlds

## Client Categories

BaaS serves different client categories:

| Category | Description | Typical Service Model |
|----------|-------------|----------------------|
| **Embedded Finance** | Unregulated entities embedding finance | API |
| **Inter-Banking License** | Licensed institutions with 3rd-party license | CoreX or Hybrid |
| **Business Banking** | Merchants needing business accounts | CoreX or API |
| **Technology & BaaS** | Fintechs with own license | API or Hybrid |

## Admin Panel

All BaaS clients (CoreX, API, and Hybrid) have access to the **Master Admin Panel** for:

- Viewing onboarded customers
- Monitoring transactions
- Handling approvals and manual tasks
- Generating reports and analytics
- Managing notifications

## Next Steps

<CardGroup cols={2}>
  <Card title="Explore BaaS" icon="building" href="/baas/introduction">
    Go to BaaS documentation
  </Card>
  <Card title="PaaS Explained" icon="plug" href="/overview/service-models/paas-explained">
    Learn about PaaS
  </Card>
</CardGroup>


---

# PaaS Explained

Understanding Platform as a Service - connectors and system-to-system integration


URL: /overview/service-models/paas-explained



# Platform as a Service (PaaS) Explained

Platform as a Service (PaaS) provides **system-to-system integration** — direct access to FinHub's technology connectors without the business process layer. This is pure technology integration for clients who already have their own systems and business logic.

## What PaaS Provides

PaaS provides direct connector access:

| Connector | What It Does |
|-----------|--------------|
| **Acquiring (IPG)** | Card payment gateway integration |
| **Banking Networks** | SEPA, SWIFT, local payment rails |
| **KYC/KYB** | Identity verification services |
| **Communication** | SMS, email, push notifications |
| **Crypto** | Blockchain and digital asset connectivity |

## PaaS vs BaaS

| Aspect | PaaS | BaaS |
|--------|------|------|
| **What you get** | Connectors only | Business processes + connectors |
| **Business logic** | You provide | FinHub provides |
| **UI/Front-end** | You build | CoreX or you build |
| **Integration type** | System-to-system | API or white-label |
| **Best for** | Companies with existing systems | Companies needing full solution |

## When to Choose PaaS

Choose PaaS if you:

- Already have your own core banking system
- Only need specific connector integrations
- Have your own business process logic
- Want to integrate FinHub's technology into existing infrastructure
- Need payment gateway (IPG) access only

## Available Connectors

### Acquiring (IPG)

Internet Payment Gateway for card transactions:

- Card payment acceptance
- 3D Secure authentication
- Multiple card networks
- Settlement and reconciliation

### Banking Networks

Access to payment rails:

- **SEPA** - Euro payments in Europe
- **SWIFT** - International wire transfers
- **Local Rails** - Country-specific payment systems
- **Faster Payments** - UK instant payments

### KYC/KYB

Identity verification connectors:

- Document verification
- Biometric checks
- Sanctions screening
- PEP checks

### Communication

Notification services:

- SMS delivery
- Email sending
- Push notifications

### Crypto

Blockchain connectivity:

- Digital asset trading
- Custody services
- Blockchain integrations

## Next Steps

<CardGroup cols={2}>
  <Card title="Explore PaaS" icon="plug" href="/paas/introduction">
    Go to PaaS documentation
  </Card>
  <Card title="BaaS Explained" icon="building" href="/overview/service-models/baas-explained">
    Learn about BaaS
  </Card>
</CardGroup>


---

# Find Your Path

Choose the right FinHub integration path for your needs


URL: /overview/find-your-path



# Find Your Path

Use this guide to determine which FinHub service model is right for you.

## Step 1: BaaS or PaaS?

```mermaid
flowchart TD
    A[What do you need?] --> B{Need business processes?}
    B -->|Yes - onboarding, accounts, transactions| C[BaaS]
    B -->|No - just technology connectors| D[PaaS]
```

| Question | Answer → Path |
|----------|---------------|
| Do you need customer onboarding flows? | Yes → **BaaS** |
| Do you need account/wallet management? | Yes → **BaaS** |
| Do you only need payment gateway integration? | Yes → **PaaS** |
| Do you have existing systems and just need connectors? | Yes → **PaaS** |

---

## Step 2: If BaaS, Which Service Model?

```mermaid
flowchart TD
    A[BaaS Selected] --> B{Do you want to build your own UI?}
    B -->|No, give me a ready solution| C[CoreX Service Model]
    B -->|Yes, I have developers| D[API Service Model]
    B -->|Some of each| E[Hybrid Service Model]
```

### Side-by-Side Comparison

| Aspect | CoreX | API | Hybrid |
|--------|-------|-----|--------|
| **Time to Market** | 2-4 weeks | 4-12 weeks | 4-8 weeks |
| **Development Effort** | Minimal | Significant | Moderate |
| **UI/UX Control** | Customizable themes | Complete control | Mixed |
| **Mobile Apps** | Included | Build your own | Some included |
| **Maintenance** | Managed by FinHub | Your responsibility | Shared |
| **Best For** | Quick launch | Custom experiences | Flexibility |

---

## Decision Guide

<Steps>
  <Step title="Evaluate Your Resources">
    **Do you have a development team?**
    - Yes → API or Hybrid Service Model viable
    - No → Consider CoreX Service Model
  </Step>
  <Step title="Consider Time to Market">
    **When do you need to launch?**
    - Within 1 month → CoreX Service Model
    - 3+ months → API Service Model
  </Step>
  <Step title="Assess Customization Needs">
    **How unique is your user experience?**
    - Standard flows → CoreX Service Model
    - Highly custom → API Service Model
  </Step>
  <Step title="Plan for Maintenance">
    **Who will maintain the solution?**
    - Prefer managed → CoreX Service Model
    - Have team capacity → API Service Model
  </Step>
</Steps>

---

## Quick Recommendations

| You Are | You Need | Recommended Path |
|---------|----------|------------------|
| Startup, no dev team | Fast launch | BaaS → CoreX |
| Fintech with developers | Custom UX | BaaS → API |
| Bank modernizing | White-label + custom | BaaS → Hybrid |
| Platform with existing systems | Payment gateway only | PaaS |
| Enterprise with own core banking | Specific connectors | PaaS |

---

## Ready to Start?

<CardGroup cols={2}>
  <Card title="BaaS - CoreX" icon="desktop" href="/baas/corex/introduction">
    White-label solution
  </Card>
  <Card title="BaaS - API" icon="code" href="/baas/api/introduction">
    Direct API access
  </Card>
  <Card title="BaaS - Hybrid" icon="shuffle" href="/baas/hybrid/introduction">
    Combined approach
  </Card>
  <Card title="PaaS - Connectors" icon="plug" href="/paas/introduction">
    Technology connectors
  </Card>
</CardGroup>


---

# Platform Architecture

FinHub technology platform architecture overview


URL: /overview/platform/architecture



# Platform Architecture

FinHub's platform is built on a modern, scalable, and secure microservices architecture designed for financial services.

## Architecture Overview

Our platform is built on a microservices architecture that allows for independent scaling, deployment, and maintenance:

- **Flexibility**: Components can be updated or replaced without affecting the entire system
- **Scalability**: Services can be scaled independently based on demand
- **Resilience**: Failures in one service do not cascade to others
- **Technology diversity**: Different services can use different technologies as appropriate

## Core Components

| Component | Description |
|-----------|-------------|
| **API Gateway** | Authentication, request routing, rate limiting, API versioning |
| **Identity & Access Management** | Multi-factor auth, role-based access control, SSO, audit logging |
| **Transaction Processing Engine** | Real-time processing, multi-currency support, fraud detection |
| **Data Storage & Analytics** | Encrypted storage, real-time analytics, reporting, ML capabilities |
| **Integration Framework** | REST APIs, webhooks, event-driven architecture, third-party connectors |

## Core Capabilities

| Capability | Description |
|------------|-------------|
| **Account Management** | Create and manage customer accounts |
| **Payments** | Process domestic and international transfers |
| **Cards** | Issue virtual and physical cards |
| **KYC/KYB** | Identity verification and compliance |
| **Wallets** | Multi-currency wallet management |
| **Compliance** | Regulatory reporting and monitoring |

## Deployment Options

- **Cloud-native**: Fully managed by FinHub in our secure cloud environment
- **Hybrid**: Core components in our cloud with specific services deployed in client environments
- **On-premises**: For clients with specific regulatory or security requirements

## Security and Compliance

Security is built into every layer of our platform:

- End-to-end encryption (TLS 1.3, AES-256)
- Regular security audits and penetration testing
- Compliance with industry standards (PCI-DSS, ISO 27001, GDPR, SOC 2)
- Continuous monitoring and threat detection

## Global Infrastructure

Our platform is deployed across multiple geographic regions to provide:

- Low-latency access for clients worldwide
- Data residency compliance
- Disaster recovery capabilities
- High availability (99.99% uptime SLA)

## Next Steps

<CardGroup cols={2}>
  <Card title="BaaS" icon="building" href="/baas/introduction">
    Explore Business as a Service
  </Card>
  <Card title="PaaS" icon="plug" href="/paas/introduction">
    Explore Platform as a Service
  </Card>
</CardGroup>


---

# BaaS Introduction

Introduction to FinHub Business as a Service


URL: /baas/introduction



# Business as a Service (BaaS)

Business as a Service (BaaS) is FinHub's comprehensive offering that provides **business processes** through microservices. BaaS enables you to deliver complete financial services to your customers without building the underlying infrastructure.

## What BaaS Provides

BaaS delivers automated business processes:

| Business Process | What It Does |
|------------------|--------------|
| **Customer Onboarding** | B2C and B2B registration, KYC/KYB verification, activation |
| **Account Management** | Account creation, wallets, multi-currency support |
| **Transaction Processing** | Payments, transfers, SEPA, SWIFT |
| **Compliance** | AML screening, regulatory reporting, audit trails |
| **Back Office** | Approvals, case management, operations |

## Service Models

Within BaaS, you choose how to integrate:

<CardGroup cols={3}>
  <Card title="CoreX Service Model" icon="desktop" href="/baas/corex/introduction">
    White-label front-end solution
  </Card>
  <Card title="API Service Model" icon="code" href="/baas/api/introduction">
    Direct API integration
  </Card>
  <Card title="Hybrid Service Model" icon="shuffle" href="/baas/hybrid/introduction">
    Combined approach
  </Card>
</CardGroup>

| Service Model | Description | Time to Market |
|---------------|-------------|----------------|
| **CoreX** | Pre-built white-label solution with web & mobile apps | 2-4 weeks |
| **API** | Direct API access for custom implementations | 4-12 weeks |
| **Hybrid** | Combination of CoreX + API | 4-8 weeks |

## Client Categories

BaaS serves different types of clients:

<CardGroup cols={2}>
  <Card title="Embedded Finance" icon="puzzle-piece" href="/baas/client-categories/embedded-finance">
    For unregulated entities
  </Card>
  <Card title="Inter-Banking License" icon="building-columns" href="/baas/client-categories/inter-banking-license">
    For licensed institutions
  </Card>
  <Card title="Business Banking" icon="briefcase" href="/baas/client-categories/business-banking">
    For merchants
  </Card>
  <Card title="Technology & BaaS" icon="microchip" href="/baas/client-categories/technology-baas">
    For fintechs with own license
  </Card>
</CardGroup>

## Product Suite

BaaS provides access to FinHub's product modules:

<CardGroup cols={3}>
  <Card title="FinCore™" icon="building-columns" href="/baas/products/fincore">
    Core Banking
  </Card>
  <Card title="FinTrans™" icon="banknote" href="/baas/products/fintrans">
    Payment Processing
  </Card>
  <Card title="FinCard™" icon="credit-card" href="/baas/products/fincard">
    Card Issuing
  </Card>
  <Card title="FinPOS™" icon="store" href="/baas/products/finpos">
    Acquiring
  </Card>
  <Card title="FinCheck™" icon="shield-check" href="/baas/products/fincheck">
    Compliance
  </Card>
  <Card title="FinExE™" icon="bitcoin" href="/baas/products/finexe">
    Crypto Exchanges
  </Card>
</CardGroup>

## Getting Started

Choose your path:

1. **Identify your client category** → [Client Categories](/baas/client-categories)
2. **Choose your service model** → [Service Models Comparison](/baas/service-models)
3. **Start with your chosen model**:
   - [CoreX Service Model](/baas/corex/introduction)
   - [API Service Model](/baas/api/introduction)
   - [Hybrid Service Model](/baas/hybrid/introduction)

## Next Steps

<CardGroup cols={2}>
  <Card title="Client Categories" icon="users" href="/baas/client-categories">
    Find your category
  </Card>
  <Card title="Service Models" icon="code-compare" href="/baas/service-models">
    Compare CoreX, API, and Hybrid
  </Card>
</CardGroup>


---

# Client Categories

Overview of FinHub client categories and their use cases


URL: /baas/client-categories



# Client Categories

FinHub serves diverse client categories, each with unique requirements and integration patterns.

<CardGroup cols={2}>
  <Card title="Embedded Finance" icon="puzzle-piece" href="/baas/client-categories/embedded-finance">
    Non-financial companies adding financial services
  </Card>
  <Card title="Inter-Banking License" icon="building-columns" href="/baas/client-categories/inter-banking-license">
    Licensed financial institutions
  </Card>
  <Card title="Business Banking" icon="briefcase" href="/baas/client-categories/business-banking">
    B2B banking solutions
  </Card>
  <Card title="Technology & BaaS" icon="microchip" href="/baas/client-categories/technology-baas">
    Tech companies building financial products
  </Card>
</CardGroup>

## Category Overview

| Category | Primary Use Case | Typical Service Model |
|----------|------------------|----------------------|
| **Embedded Finance** | Add finance to existing products | API |
| **Inter-Banking License** | Expand banking services | CoreX or Hybrid |
| **Business Banking** | Serve business customers | CoreX or API |
| **Technology & BaaS** | Build fintech products | API or Hybrid |

## Embedded Finance

For non-financial companies adding financial services to their platforms:

- E-commerce platforms
- SaaS applications
- Marketplaces
- Gig economy platforms

**Typical integration:** API Service Model for custom experiences

## Inter-Banking License & BaaS

For licensed financial institutions expanding their capabilities:

- Traditional banks modernizing
- Credit unions expanding services
- Payment institutions
- E-money institutions

**Typical integration:** CoreX or Hybrid Service Model

## Business Banking

For companies serving business customers:

- SMB banking solutions
- Corporate treasury
- Trade finance
- Invoice financing

**Typical integration:** CoreX or API Service Model

## Technology & BaaS

For technology companies building financial products from the ground up:

- Neobanks and challenger banks
- Payment service providers
- Lending platforms
- Investment apps

**Typical integration:** API or Hybrid Service Model

## Choosing Your Category

Consider these factors:

1. **Regulatory Status**: Do you have a financial license?
2. **Target Market**: B2C, B2B, or both?
3. **Technical Resources**: In-house development capability?
4. **Time to Market**: How quickly do you need to launch?
5. **Customization Needs**: Standard features or highly custom?

## Next Steps

<CardGroup cols={2}>
  <Card title="Service Models" icon="code-compare" href="/baas/service-models">
    Compare CoreX, API, and Hybrid
  </Card>
  <Card title="Product Suite" icon="box" href="/baas/products">
    Explore FinHub products
  </Card>
</CardGroup>


---

# Embedded Finance

End-to-end embedded finance lifecycle: customer onboarding, compliance, wallets, and payments with links to API reference and sample payloads


URL: /baas/client-categories/embedded-finance



# Embedded Finance

Embedded finance lets non-financial brands offer regulated financial journeys inside their own products. FinHub exposes this as an **API-first** platform: you own UX and branding; FinHub provides customer lifecycle, verification, wallets, and payments.

This page maps a **typical integration** to the published [Customer APIs](/baas/api/reference/customer-apis), [Verification & Compliance](/baas/api/reference/verification-compliance), and [Financial Operations](/baas/api/reference/financial-operations) references. Use it as the narrative companion to those sections.

<Info>
  **Sandbox base URL (illustrative):** `https://sandbox.finhub.cloud/api/v2.1` — your tenant receives the exact base URL and credentials during onboarding.
</Info>

---

## Documentation map

<CardGroup cols={3}>
  <Card title="Customer APIs" icon="user" href="/baas/api/reference/customer-apis">
    B2C and B2B registration, sessions, activation, and organization management
  </Card>
  <Card title="Verification & Compliance" icon="shield-check" href="/baas/api/reference/verification-compliance">
    Verifications, documents, approvals, and mandatory consents
  </Card>
  <Card title="Financial Operations" icon="banknote" href="/baas/api/reference/financial-operations">
    Wallets, beneficiaries, payment consents, prepare/execute, orders
  </Card>
</CardGroup>

<Info>
  **Run this flow in Postman**: Import `Finhub B2B Flow v1.1.3` or `Finhub B2C Flow v1.1.3` from the partner Postman collections and a matching tenant environment to execute the exact steps below.
</Info>

---

## Workflow diagrams

```mermaid
flowchart LR
    A[Authenticate] --> B[Register]
    B --> C[Verify]
    C --> D[Consents]
    D --> E[Activate]
    E --> F[Wallets]
    F --> G[Payments]
```

### B2C workflow

```mermaid
flowchart TB
    A1["(1) Admin login"] --> A2["(2) Get categorization"]
    A2 --> A2a["(2.1) Classified wallets"]
    A2a --> A3["(3) Register individual customer"]
    A3 --> A4["(4) Create customer session"]
    A4 --> A5a["(5.1) Initiate identity verification"]
    A5a --> A5b["(5.2) Upload passport document"]
    A5b --> A5c["(5.3) Approve identity verification"]
    A5c --> A5d["(5.4) Initiate document verification"]
    A5d --> A5e["(5.5) Upload proof of address"]
    A5e --> A5f["(5.6) Approve document verification"]
    A5f --> A6a["(6.1) Accept terms consent"]
    A6a --> A6b["(6.2) Accept privacy consent"]
    A6b --> A6c["(6.3) Accept data processing consent"]
    A6c --> A7["(7) Activation readiness check"]
    A7 --> A8["(8) Activate individual customer"]
    A8 --> A9["(9) Poll customer wallets"]
    A9 --> A10["(10) Add beneficiary"]
    A10 --> A11["(11) Create payment consent"]
    A11 --> A12["(12) Prepare transfer"]
    A12 --> A13["(13) Consent confirmation/OTP"]
    A13 --> A14["(14) Execute transfer"]
```

### B2B workflow

```mermaid
flowchart TB
    B1["(1) Admin login"] --> B2["(2) Get categorization"]
    B2 --> B3["(3) Register organization"]
    B3 --> B3a["(3a) Add address"]
    B3a --> B3b["(3b) Add director"]
    B3b --> B3c["(3c) Add shareholder"]
    B3c --> B4["(4) Add employee"]
    B4 --> B5["(5) Create organization user session"]
    B5 --> B6a["(6a) Initiate verification (org route)"]
    B6a --> B6b["(6b–6e) Upload documents"]
    B6b --> B6f["(6f) Approve verification"]
    B6f --> B7["(7) Accept consents (terms/privacy/data-processing)"]
    B7 --> B8["(8) Activate organization"]
    B8 --> B9["(9) Poll wallets until IBAN exists"]
    B9 --> B10["(10) Add beneficiary on org/tenant wallet as required"]
    B10 --> B11["(11) Create payment consent"]
    B11 --> B12["(12) Prepare transfer"]
    B12 --> B13["(13) Consent confirmation/OTP"]
    B13 --> B14["(14) Execute transfer"]
```

| Stage | What happens | Primary docs |
|-------|----------------|----------------|
| **Authenticate** | Admin (or partner) JWT for back-office calls; customer JWT after session | [Administration](/baas/api/reference/administration), [API introduction](/baas/api/introduction) |
| **Register** | Create B2C individual or B2B organization with categorization | [Customer APIs](/baas/api/reference/customer-apis) |
| **Verify** | KYC/KYB initiation, document upload, approval | [Verification & Compliance](/baas/api/reference/verification-compliance) |
| **Consents** | `terms`, `privacy`, `data-processing` | [Individual consents](/baas/api/reference/verification-compliance/consents-individual), [Organization consents](/baas/api/reference/verification-compliance/consents-organization) |
| **Activate** | Unlock account and downstream wallet provisioning | [Individual activation](/baas/api/reference/customer-apis/individual/activation), [Organization activation](/baas/api/reference/customer-apis/organization/activation) |
| **Wallets** | Poll until Product GP wallet and IBAN are available | [Get wallets by customer](/baas/api/reference/financial-operations/get-wallets-by-customer) |
| **Payments** | Beneficiaries → payment consent → prepare → execute | [Financial Operations](/baas/api/reference/financial-operations) |

---

## Placeholders

Replace these with values from your tenant and API responses:

| Placeholder | Description |
|-------------|-------------|
| `{{BASE_URL}}` | API base URL from onboarding |
| `{{X_TENANT_ID}}` | Tenant header value (e.g. `X-Tenant-ID`) |
| `{{TENANT_UUID}}` | Tenant UUID (often from JWT `tenantId`) |
| `{{CUSTOMER_ID}}` | Customer ID from registration |
| `{{USER_ID}}` | User ID from registration or employee creation |
| `{{ORG_ID}}` | Organization ID (B2B) |
| `{{WALLET_ID}}` | Product GP wallet used for `fintrans` calls |
| `{{VERIFICATION_ID}}` | From verification creation |
| `{{CONSENT_ID}}` | AML / payment consent reference |
| `{{PREPARED_ORDER_ID}}` | From prepare step |
| `{{ADDRESS_ID}}` | From add address step |
| `{{DIRECTOR_ID}}` | From add director step |
| `{{SHAREHOLDER_ID}}` | From add shareholder step |
| `{{EMPLOYEE_ID}}` | From add employee step |

---

## B2C individual — embedded journey

High-level sequence aligned with [Individual customer APIs](/baas/api/reference/customer-apis/individual):

| Step | Action | API reference |
|------|--------|----------------|
| 1 | Admin session (or partner auth) | [Administration](/baas/api/reference/administration) |
| 2 | Categorization hierarchy | [Categorization](/baas/api/reference/customer-apis/individual/categorization) |
| 3 | Individual registration | [Registration](/baas/api/reference/customer-apis/individual/registration) |
| 4 | Customer session (`POST .../users/{userId}/sessions`) | [Individual index](/baas/api/reference/customer-apis/individual) (sessions table) |
| 5 | Verification: create → upload documents → approve | [Create verification](/baas/api/reference/verification-compliance/create-verification), [Upload document](/baas/api/reference/verification-compliance/upload-verification-document), [Approve](/baas/api/reference/verification-compliance/approve-verification) |
| 6 | Accept consents (`terms`, `privacy`, `data-processing`) | [Individual consents](/baas/api/reference/verification-compliance/consents-individual) |
| 7 | Activation readiness | [Activation readiness check](/baas/api/reference/customer-apis/individual/activation-readiness-check) |
| 8 | Activate account | [Activation](/baas/api/reference/customer-apis/individual/activation) |
| 9 | Poll wallets until IBAN on Product GP wallet | [Get wallets by customer](/baas/api/reference/financial-operations/get-wallets-by-customer) (`?customerType=B2C`) |
| 10+ | Beneficiaries, payment consent, prepare, consent confirmation, execute | See [Financial operations](#financial-operations-after-activation) |

<Tip>
  Verification types for individuals include `IDENTITY_VERIFICATION` and `DOCUMENT_VERIFICATION`; see the [Verification & Compliance overview](/baas/api/reference/verification-compliance) for the full table.
</Tip>

---

## B2B organization — embedded journey

Aligned with [Organization customer APIs](/baas/api/reference/customer-apis/organization):

| Step | Action | API reference |
|------|--------|----------------|
| 1 | Admin login | [Administration](/baas/api/reference/administration) |
| 2 | Get categorization hierarchy | [Categorization](/baas/api/reference/customer-apis/individual/categorization) |
| 2.1 | Classified wallets (resolve default wallet product) | [Get wallets by customer](/baas/api/reference/financial-operations/get-wallets-by-customer) |
| 3 | Register organization | [Registration](/baas/api/reference/customer-apis/organization/registration) |
| 3a | Add address | [Organization management](/baas/api/reference/customer-apis/organization/management) |
| 3b | Add director | [Organization management](/baas/api/reference/customer-apis/organization/management) |
| 3c | Add shareholder | [Shareholders](/baas/api/reference/customer-apis/organization/shareholders) |
| 4 | Add employee | [Employee](/baas/api/reference/customer-apis/organization/employee) |
| 5 | Create organization user session | [Administration](/baas/api/reference/administration) |
| 6a | Initiate verification (org route) | [Organization verify](/baas/api/reference/customer-apis/organization/verify) |
| 6b–6e | Upload documents (certificate, articles, proof of address, data processing) | [Upload verification document](/baas/api/reference/verification-compliance/upload-verification-document) |
| 6f | Approve verification | [Approve verification](/baas/api/reference/verification-compliance/approve-verification) |
| 7a–7c | Accept consents (`terms`, `privacy`, `data-processing`) | [Organization consents](/baas/api/reference/verification-compliance/consents-organization) |
| 8 | Activate organization | [Activation](/baas/api/reference/customer-apis/organization/activation) |
| 9 | Poll wallets (`?customerType=B2B`) | [Get wallets by customer](/baas/api/reference/financial-operations/get-wallets-by-customer) |
| 10+ | Wallet funding, beneficiaries, payment consent, prepare, consent confirmation, execute | [Financial Operations](/baas/api/reference/financial-operations) |

<Warning>
  Some B2B steps require operational headers such as `X-User-ID` and `X-User-Roles`. See [Standard HTTP headers](/baas/api/reference/schemas/standard-headers) and your tenant’s integration checklist.
</Warning>

---

## Financial operations (after activation)

Financial endpoints are only valid once the customer is **activated** and wallets are **ACTIVE**. The canonical HTTP sequence is documented on the [Financial Operations overview](/baas/api/reference/financial-operations):

| Order | Operation | Documentation |
|-------|-----------|----------------|
| 1 | Balance / allowed operations | [Balance](/baas/api/reference/financial-operations/account-information/balance), [Allowed operations](/baas/api/reference/financial-operations/account-information/allowed-operations) |
| 2 | Register beneficiaries | [Create beneficiary](/baas/api/reference/financial-operations/create-beneficiary) |
| 3 | Payment consent (when required) | [Create payment consent](/baas/api/reference/financial-operations/create-payment-consent) |
| 4 | Prepare order | [Prepare](/baas/api/reference/financial-operations/prepare-financial-operation) |
| 5 | Consent confirmation / OTP (flow depends on environment) | [Approve verification](/baas/api/reference/verification-compliance/approve-verification), [Consent verification](/baas/api/reference/verification-compliance/consent-verification) |
| 6 | Execute order | [Execute](/baas/api/reference/financial-operations/execute-prepared-operation) |

---

## Why API service model fits embedded finance

- **Your UI, your brand** — no forced FinHub screens; you build flows in your app or web.
- **Composable steps** — same APIs support light-touch onboarding or fully automated journeys.
- **Regulatory coverage** — KYC/KYB, consents, and payment consents are exposed as explicit API calls.

<Card title="API Service Model" icon="code" href="/baas/api/introduction">
  Platform overview and authentication concepts
</Card>

---

## Next steps

<CardGroup cols={2}>
  <Card title="Individual APIs (B2C)" icon="user" href="/baas/api/reference/customer-apis/individual">
    Registration through activation
  </Card>
  <Card title="Organization APIs (B2B)" icon="building" href="/baas/api/reference/customer-apis/organization">
    Business onboarding and activation
  </Card>
  <Card title="Verification & Compliance" icon="shield-check" href="/baas/api/reference/verification-compliance">
    Verifications, documents, and consents
  </Card>
  <Card title="Financial Operations" icon="banknote" href="/baas/api/reference/financial-operations">
    Wallets, transfers, and payment operations
  </Card>
</CardGroup>


---

# Inter-Banking License

Banking infrastructure solutions for licensed financial institutions


URL: /baas/client-categories/inter-banking-license



# Inter-Banking License & BaaS

FinHub provides specialized Banking as a Service solutions for licensed financial institutions seeking to expand their capabilities through inter-banking partnerships and infrastructure sharing.

## Overview

Licensed banks and financial institutions can leverage FinHub's platform to extend their service offerings, access new markets, and optimize their technology infrastructure while maintaining full regulatory compliance.

## Target Audience

This solution is designed for:

- **Licensed Banks**: Regional and national banks seeking technology modernization
- **Credit Unions**: Cooperative financial institutions expanding services
- **Payment Institutions**: Licensed PSPs enhancing their offerings
- **E-Money Institutions**: EMIs looking for banking partnerships

## Key Capabilities

### Correspondent Banking Services

- **Payment Rails Access**: Connect to SEPA, SWIFT, and local payment networks
- **FX Services**: Multi-currency processing and exchange
- **Nostro/Vostro Accounts**: Correspondent account management
- **Settlement Services**: Real-time and batch settlement options

### Regulatory Compliance

- **License Sharing**: Operate under partnership license arrangements
- **Compliance Framework**: Shared KYC/AML infrastructure
- **Regulatory Reporting**: Automated reporting tools
- **Audit Support**: Comprehensive audit trail and documentation

### Technology Infrastructure

- **Core Banking Integration**: Connect to existing core banking systems
- **API Gateway**: Secure, scalable API management
- **Data Management**: Centralized data lake and analytics
- **Disaster Recovery**: Enterprise-grade business continuity

## Service Model Options

| Service Model | Description | Best For |
|---------------|-------------|----------|
| **CoreX** | White-label solution, quick launch | Rapid deployment |
| **Hybrid** | CoreX + custom integrations | Flexibility |

## Partnership Models

### White-Label Banking

Deploy FinHub's banking services under your own brand:

| Feature | Description |
|---------|-------------|
| Branding | Full white-label customization |
| Licensing | Operate under partner's license |
| Compliance | Shared compliance framework |
| Support | Dedicated partner support |

### Infrastructure Partnership

Share infrastructure while maintaining operational independence:

- Shared technology platform
- Independent operations
- Cost optimization
- Scalable capacity

## Getting Started

1. **Initial Consultation**: Discuss partnership requirements
2. **Due Diligence**: Regulatory and technical assessment
3. **Agreement**: Partnership contract and SLA
4. **Integration**: Technical integration and testing
5. **Pilot**: Limited rollout and validation
6. **Full Launch**: Production deployment

## Benefits

- **Extended Reach**: Access new markets and customer segments
- **Cost Efficiency**: Shared infrastructure reduces operational costs
- **Regulatory Support**: Leverage FinHub's compliance expertise
- **Technology Modernization**: Access modern banking technology stack
- **Risk Mitigation**: Shared risk through partnership model

## Next Steps

<CardGroup cols={2}>
  <Card title="CoreX Service Model" icon="desktop" href="/baas/corex/introduction">
    Explore white-label solution
  </Card>
  <Card title="Hybrid Service Model" icon="shuffle" href="/baas/hybrid/introduction">
    Explore hybrid approach
  </Card>
</CardGroup>


---

# Business Banking

Comprehensive business banking solutions for enterprises and SMBs


URL: /baas/client-categories/business-banking



# Business Banking

FinHub provides comprehensive business banking solutions designed to meet the diverse needs of enterprises and small-to-medium businesses (SMBs) through our partners.

## Overview

Our business banking platform enables financial institutions and fintechs to offer complete business banking services to their corporate clients, from basic account management to sophisticated treasury operations.

## Target Segments

### Small & Medium Businesses (SMBs)

- Startups and entrepreneurs
- Local businesses
- Professional services firms
- E-commerce merchants

### Mid-Market Enterprises

- Regional businesses
- Growing companies
- Multi-location operations
- Industry-specific enterprises

### Large Enterprises

- Multinational corporations
- Holding companies
- Financial services firms
- Public sector organizations

## Core Services

### Business Accounts

| Account Type | Features | Best For |
|--------------|----------|----------|
| Business Current | Day-to-day operations | All businesses |
| Business Savings | Interest-bearing deposits | Cash reserves |
| Multi-Currency | Multiple currency holdings | International trade |
| Escrow | Third-party holding | Transactions, M&A |

### Payment Services

- **Domestic Payments**: Same-day and next-day transfers
- **International Payments**: SWIFT and local payment rails
- **Batch Payments**: Payroll and supplier payments
- **Direct Debits**: Recurring payment collection
- **Virtual Accounts**: Automated reconciliation

### Card Programs

- **Corporate Cards**: Employee expense management
- **Virtual Cards**: Secure online payments
- **Prepaid Cards**: Budget-controlled spending

### Treasury Management

- **Cash Pooling**: Centralized liquidity management
- **FX Management**: Currency hedging and conversion
- **Reporting**: Real-time cash position and forecasting

## B2B Features

### Organization Management

- **Multi-Entity Support**: Manage multiple legal entities
- **Role-Based Access**: Granular permission controls
- **Approval Workflows**: Multi-level authorization
- **Audit Trails**: Complete transaction history

### Integration Capabilities

- **ERP Integration**: Connect to SAP, Oracle, NetSuite
- **Accounting Software**: Sync with QuickBooks, Xero
- **API Access**: Full programmatic control
- **File-Based**: SFTP and batch file processing

## Service Model Options

| Service Model | Description | Best For |
|---------------|-------------|----------|
| **CoreX** | Pre-built business banking portal | Quick launch |
| **API** | Custom business banking experience | Full control |

## Getting Started

1. **Requirements Analysis**: Define your business banking needs
2. **Solution Design**: Choose implementation approach
3. **Sandbox Access**: Set up development environment
4. **Integration**: Build and test your solution
5. **Pilot Launch**: Test with select customers
6. **Full Rollout**: Scale to all customers

## Next Steps

<CardGroup cols={2}>
  <Card title="CoreX Service Model" icon="desktop" href="/baas/corex/introduction">
    White-label business banking
  </Card>
  <Card title="API Service Model" icon="code" href="/baas/api/introduction">
    Custom business banking
  </Card>
</CardGroup>


---

# Technology & BaaS

Banking as a Service solutions for technology companies


URL: /baas/client-categories/technology-baas



# Technology & BaaS

FinHub provides comprehensive Banking as a Service (BaaS) solutions designed specifically for technology companies looking to integrate financial services into their platforms.

## Overview

Technology companies increasingly need to embed financial capabilities into their products to remain competitive. FinHub's BaaS platform enables you to offer banking services without the complexity of building and maintaining financial infrastructure.

## Key Capabilities

### API-First Architecture

- **RESTful APIs**: Modern, well-documented APIs for seamless integration
- **Webhooks**: Real-time notifications for transaction events
- **SDKs**: Pre-built libraries for popular programming languages
- **Sandbox Environment**: Full-featured testing environment

### Core Banking Services

- **Account Management**: Create and manage customer accounts
- **Payment Processing**: Handle domestic and international payments
- **Card Issuance**: Virtual and physical card programs
- **Ledger Management**: Real-time balance and transaction tracking

### Compliance & Security

- **KYC/AML Integration**: Built-in identity verification
- **Regulatory Compliance**: Pre-certified for multiple jurisdictions
- **Data Encryption**: End-to-end encryption for all data
- **Audit Trails**: Comprehensive logging and reporting

## Service Model Options

| Service Model | Description | Best For |
|---------------|-------------|----------|
| **API** | Full API access, build your own UI | Custom fintech products |
| **Hybrid** | Combine CoreX + custom API | Flexibility with speed |

## Use Cases

| Industry | Application | Key Features |
|----------|-------------|--------------|
| SaaS Platforms | Embedded payments | Subscription billing, vendor payouts |
| Marketplaces | Multi-party payments | Escrow, split payments |
| Fintech Apps | Neobanking | Full banking stack |
| E-commerce | Payment processing | Checkout, refunds |

## Getting Started

1. **Consultation**: Discuss your requirements with our solutions team
2. **Integration Planning**: Design your integration architecture
3. **Sandbox Setup**: Configure your development environment
4. **Development**: Build and test your integration
5. **Certification**: Complete compliance and security review
6. **Go-Live**: Launch your BaaS-powered solution

## Benefits

- **Faster Time to Market**: Launch financial services in weeks, not years
- **Reduced Costs**: No need to build infrastructure from scratch
- **Regulatory Compliance**: Leverage our licenses and compliance framework
- **Scalability**: Enterprise-grade infrastructure that grows with you
- **Continuous Innovation**: Access to new features and capabilities

## Next Steps

<CardGroup cols={2}>
  <Card title="API Service Model" icon="code" href="/baas/api/introduction">
    Explore API integration
  </Card>
  <Card title="Hybrid Service Model" icon="shuffle" href="/baas/hybrid/introduction">
    Explore hybrid approach
  </Card>
</CardGroup>


---

# Product Suite

Overview of FinHub's trademarked product suite


URL: /baas/products



# Product Suite

FinHub offers a comprehensive suite of financial technology products, each designed to address specific aspects of the financial services ecosystem. These products can be integrated individually or as a complete solution.

<CardGroup cols={3}>
  <Card title="FinCore™" icon="building-columns" href="/baas/products/fincore">
    Core Banking
  </Card>
  <Card title="FinTrans™" icon="banknote" href="/baas/products/fintrans">
    Payment Processing
  </Card>
  <Card title="FinCard™" icon="credit-card" href="/baas/products/fincard">
    Card Issuing
  </Card>
  <Card title="FinPOS™" icon="store" href="/baas/products/finpos">
    Acquiring
  </Card>
  <Card title="FinCheck™" icon="shield-check" href="/baas/products/fincheck">
    Compliance
  </Card>
  <Card title="FinExE™" icon="bitcoin" href="/baas/products/finexe">
    Crypto Exchanges
  </Card>
</CardGroup>

## Product Overview

| Product | Description | Key Features |
|---------|-------------|--------------|
| **FinCore™** | Core Banking | Account management, ledger, multi-currency |
| **FinTrans™** | Payment Processing | SEPA, SWIFT, real-time payments |
| **FinCard™** | Card Issuing | Virtual & physical cards, card lifecycle |
| **FinPOS™** | Acquiring | POS, mobile payments, merchant services |
| **FinCheck™** | Compliance | KYC/KYB, AML screening, regulatory reporting |
| **FinExE™** | Crypto Exchanges | Multi-currency exchange, trading, FX |

## FinCore™

The foundational banking system that powers all FinHub products and services.

**Key Features:**
- Account management and ledger system
- Transaction processing engine
- Multi-currency support
- Compliance and regulatory framework

## FinTrans™

Transaction processing system enabling secure and efficient movement of funds.

**Key Features:**
- Domestic and international transfers
- Real-time payment processing
- Batch payment handling
- Transaction monitoring and fraud detection

## FinCard™

Comprehensive card issuance and management solutions.

**Key Features:**
- Virtual and physical card issuance
- Card lifecycle management
- Transaction authorization
- Spending controls and limits

## FinPOS™

Point-of-sale solution enabling merchants to accept payments.

**Key Features:**
- In-store payment acceptance
- Mobile payment processing
- QR code payments
- Merchant management system

## FinCheck™

Comprehensive verification and compliance services.

**Key Features:**
- KYC/KYB verification
- AML screening
- Transaction monitoring
- Regulatory reporting

## FinExE™

Currency exchange and trading capabilities.

**Key Features:**
- Multi-currency exchange
- Real-time rate calculations
- FX risk management
- Liquidity management

## Product Availability by Subscription Tier

| Product | Starter | Professional | Enterprise |
|---------|---------|--------------|------------|
| FinCore™ | Basic | Enhanced | Complete |
| FinTrans™ | Basic | Enhanced | Complete |
| FinCard™ | - | Basic | Enhanced |
| FinPOS™ | - | - | Basic |
| FinCheck™ | Basic | Enhanced | Complete |
| FinExE™ | - | Basic | Enhanced |

## Next Steps

<CardGroup cols={2}>
  <Card title="Service Models" icon="code-compare" href="/baas/service-models">
    Choose CoreX, API, or Hybrid
  </Card>
  <Card title="Client Categories" icon="users" href="/baas/client-categories">
    Find your category
  </Card>
</CardGroup>


---

# FinCore™

The foundational banking system powering all FinHub products


URL: /baas/products/fincore



# FinCore™

FinCore™ is the foundational banking system that powers all FinHub products and services. It provides the core infrastructure for account management, transaction processing, and financial operations.

## Overview

FinCore™ serves as the backbone of the FinHub platform, providing essential banking infrastructure that all other products build upon.

## Key Features

| Feature | Description |
|---------|-------------|
| **Account Management** | Comprehensive account lifecycle management |
| **Ledger System** | Double-entry ledger for accurate financial record-keeping |
| **Transaction Processing** | High-performance transaction processing engine |
| **Multi-Currency Support** | Native support for multiple currencies and real-time conversions |
| **Compliance Framework** | Built-in regulatory compliance and audit capabilities |
| **Microservices Architecture** | Scalable, resilient infrastructure |

## Use Cases

- **Digital Banking**: Power neobanks and digital-first financial services
- **Corporate Treasury**: Manage corporate accounts and cash management
- **Multi-Currency Operations**: Handle international business needs
- **Financial Marketplaces**: Enable account services for marketplace platforms

## Integration

FinCore™ is available through both CoreX and API service models.

## Next Steps

<CardGroup cols={2}>
  <Card title="FinTrans™" icon="banknote" href="/baas/products/fintrans">
    Payment processing
  </Card>
  <Card title="Service Models" icon="code-compare" href="/baas/service-models">
    Choose your integration
  </Card>
</CardGroup>


---

# FinTrans™

Transaction processing system for secure fund movement


URL: /baas/products/fintrans



# FinTrans™

FinTrans™ is FinHub's transaction processing system, enabling secure and efficient movement of funds across various payment rails and networks.

## Key Features

| Feature | Description |
|---------|-------------|
| **Domestic Transfers** | Same-day and next-day domestic payments |
| **International Transfers** | SEPA, SWIFT, and local payment rails |
| **Real-time Processing** | Instant payment capabilities |
| **Batch Payments** | Payroll and bulk payment handling |
| **Fee Management** | Configurable fee structures |
| **Fraud Detection** | Transaction monitoring and fraud prevention |

## Supported Payment Rails

- **SEPA** - Euro payments across Europe
- **SWIFT** - International wire transfers
- **Local Rails** - Country-specific payment systems
- **Instant Payments** - Real-time settlement

## Use Cases

- **Payroll Processing**: Batch salary payments
- **Supplier Payments**: B2B payment automation
- **Cross-Border Transfers**: International payments
- **Treasury Operations**: Corporate fund movement

## Next Steps

<CardGroup cols={2}>
  <Card title="FinCard™" icon="credit-card" href="/baas/products/fincard">
    Card issuing
  </Card>
  <Card title="Service Models" icon="code-compare" href="/baas/service-models">
    Choose your integration
  </Card>
</CardGroup>


---

# FinCard™

Comprehensive card issuance and management solutions


URL: /baas/products/fincard



# FinCard™

FinCard™ delivers comprehensive card issuance and management solutions, supporting virtual and physical cards across multiple networks.

## Key Features

| Feature | Description |
|---------|-------------|
| **Virtual Cards** | Instant digital card issuance |
| **Physical Cards** | Branded plastic card programs |
| **Card Lifecycle** | Full lifecycle management |
| **Authorization** | Real-time transaction authorization |
| **Spending Controls** | Limits and restrictions |
| **Security** | 3D Secure, fraud prevention |

## Card Types

- **Debit Cards** - Linked to account balances
- **Prepaid Cards** - Pre-loaded value cards
- **Corporate Cards** - Business expense cards
- **Virtual Cards** - Digital-only cards

## Use Cases

- **Consumer Banking**: Personal debit and prepaid cards
- **Corporate Expense**: Employee expense management
- **E-commerce**: Virtual cards for online payments
- **Gift Cards**: Branded prepaid card programs

## Next Steps

<CardGroup cols={2}>
  <Card title="FinPOS™" icon="store" href="/baas/products/finpos">
    Acquiring
  </Card>
  <Card title="Service Models" icon="code-compare" href="/baas/service-models">
    Choose your integration
  </Card>
</CardGroup>


---

# FinPOS™

Point-of-sale and merchant acquiring solutions


URL: /baas/products/finpos



# FinPOS™

FinPOS™ is FinHub's point-of-sale solution, enabling merchants to accept payments through multiple channels and methods.

## Key Features

| Feature | Description |
|---------|-------------|
| **In-Store Payments** | POS terminal integration |
| **Mobile Payments** | mPOS and mobile acceptance |
| **QR Payments** | QR code-based transactions |
| **Contactless** | NFC and tap-to-pay |
| **Multi-Method** | Cards, wallets, bank transfers |
| **Merchant Portal** | Management and reporting |

## Payment Methods

- **Card Payments** - Visa, Mastercard, local schemes
- **Mobile Wallets** - Apple Pay, Google Pay
- **Bank Transfers** - Direct debit, instant payments
- **QR Codes** - Static and dynamic QR

## Use Cases

- **Retail**: In-store payment acceptance
- **Hospitality**: Restaurant and hotel payments
- **E-commerce**: Online payment gateway
- **Services**: Professional services billing

## Next Steps

<CardGroup cols={2}>
  <Card title="FinCheck™" icon="shield-check" href="/baas/products/fincheck">
    Compliance
  </Card>
  <Card title="Service Models" icon="code-compare" href="/baas/service-models">
    Choose your integration
  </Card>
</CardGroup>


---

# FinCheck™

Comprehensive verification and compliance services


URL: /baas/products/fincheck



# FinCheck™

FinCheck™ provides comprehensive verification and compliance services, ensuring all financial operations meet regulatory requirements.

## Key Features

| Feature | Description |
|---------|-------------|
| **KYC Verification** | Individual identity verification |
| **KYB Verification** | Business identity verification |
| **AML Screening** | Anti-money laundering checks |
| **Transaction Monitoring** | Real-time transaction analysis |
| **Regulatory Reporting** | Automated compliance reports |
| **Risk Assessment** | Customer risk scoring |

## Verification Services

- **Document Verification** - ID, passport, proof of address
- **Biometric Checks** - Facial recognition, liveness detection
- **Sanctions Screening** - Global sanctions lists
- **PEP Checks** - Politically exposed persons

## Use Cases

- **Customer Onboarding**: KYC during registration
- **Business Onboarding**: KYB for B2B customers
- **Ongoing Monitoring**: Transaction surveillance
- **Regulatory Compliance**: Audit and reporting

## Next Steps

<CardGroup cols={2}>
  <Card title="FinExE™" icon="bitcoin" href="/baas/products/finexe">
    Crypto exchanges
  </Card>
  <Card title="Service Models" icon="code-compare" href="/baas/service-models">
    Choose your integration
  </Card>
</CardGroup>


---

# FinExE™

Currency exchange and digital asset trading capabilities


URL: /baas/products/finexe



# FinExE™

FinExE™ (Financial Exchange Engine) provides currency exchange and trading capabilities, allowing for seamless conversion between different currencies and assets.

## Key Features

| Feature | Description |
|---------|-------------|
| **Multi-Currency Exchange** | Fiat currency conversions |
| **Real-Time Rates** | Live exchange rate calculations |
| **FX Risk Management** | Hedging and exposure tools |
| **Trading Algorithms** | Automated trading capabilities |
| **Liquidity Management** | Liquidity pool access |
| **Market Data** | Real-time market information |

## Supported Operations

- **Spot FX** - Immediate currency exchange
- **Forward Contracts** - Future-dated conversions
- **Multi-Currency Wallets** - Hold multiple currencies
- **Digital Assets** - Cryptocurrency trading

## Use Cases

- **International Payments**: FX for cross-border transfers
- **Treasury Operations**: Corporate FX management
- **Multi-Currency Accounts**: Currency diversification
- **Trading Platforms**: Exchange functionality

## Next Steps

<CardGroup cols={2}>
  <Card title="Product Suite" icon="box" href="/baas/products">
    All products
  </Card>
  <Card title="Service Models" icon="code-compare" href="/baas/service-models">
    Choose your integration
  </Card>
</CardGroup>


---

# Service Models Comparison

Compare CoreX, API, and Hybrid service models for BaaS integration


URL: /baas/service-models



# Service Models Comparison

FinHub BaaS offers three service models for integration. Choose the one that best fits your needs.

<CardGroup cols={3}>
  <Card title="CoreX Service Model" icon="desktop" href="/baas/corex/introduction">
    White-label solution
  </Card>
  <Card title="API Service Model" icon="code" href="/baas/api/introduction">
    Direct API integration
  </Card>
  <Card title="Hybrid Service Model" icon="shuffle" href="/baas/hybrid/introduction">
    Combined approach
  </Card>
</CardGroup>

## Comparison Table

| Aspect | CoreX | API | Hybrid |
|--------|-------|-----|--------|
| **Description** | Pre-built white-label solution | Direct API access, build your own UI | Combination of both |
| **Time to Market** | 2-4 weeks | 4-12 weeks | 4-8 weeks |
| **Development Effort** | Minimal | Significant | Moderate |
| **UI/UX Control** | Customizable themes | Complete control | Mixed |
| **Mobile Apps** | Included | Build your own | Some included |
| **Web Portal** | Included | Build your own | Some included |
| **Maintenance** | Managed by FinHub | Your responsibility | Shared |
| **Updates** | Automatic | Manual implementation | Mixed |
| **Cost Structure** | Subscription-based | Usage-based | Combined |
| **Best For** | Quick launch, standard flows | Custom experiences | Flexibility |

## CoreX Service Model

**Pre-built white-label front-end solution**

What you get:
- ✅ Ready-to-use web portal
- ✅ iOS and Android mobile apps
- ✅ Admin back-office panel
- ✅ Customizable branding (colors, logos, fonts)
- ✅ Built-in customer onboarding flows
- ✅ Managed updates and maintenance

**Best for:**
- Companies wanting to launch quickly
- Limited technical resources
- Standard banking/payment use cases
- Predictable subscription pricing

<Card title="CoreX Service Model" icon="desktop" href="/baas/corex/introduction">
  Learn more about CoreX
</Card>

## API Service Model

**Direct API integration with your own UI**

What you get:
- ✅ Full API access to all FinHub services
- ✅ Complete control over UI/UX
- ✅ Build any custom workflow
- ✅ Integrate into existing applications
- ✅ Webhooks for real-time events
- ✅ Sandbox environment for development

**Best for:**
- Companies with development resources
- Unique user experience requirements
- Integration into existing products
- Complex or non-standard workflows

<Card title="API Service Model" icon="code" href="/baas/api/introduction">
  Learn more about API integration
</Card>

## Hybrid Service Model

**Combination of CoreX and API**

What you get:
- ✅ CoreX for some processes
- ✅ API for custom integrations
- ✅ Flexibility to mix approaches
- ✅ Gradual migration path

**Best for:**
- Companies wanting best of both worlds
- Starting with CoreX, transitioning to API
- Standard flows + custom differentiators

<Card title="Hybrid Service Model" icon="shuffle" href="/baas/hybrid/introduction">
  Learn more about Hybrid approach
</Card>

## Client Journey by Service Model

### CoreX Client Journey

1. **Sales Engagement** → Discuss requirements and select subscription tier
2. **Branding Setup** → Provide branding assets and configuration preferences
3. **Platform Configuration** → FinHub configures your white-labeled platform
4. **Review & Approval** → Review and approve the customized platform
5. **Go-Live** → Launch your branded financial services platform

### API Client Journey

1. **Registration** → Complete application on the FinHub Developer Portal
2. **Sandbox Access** → Receive credentials and explore APIs in sandbox
3. **Integration Development** → Build your integration with FinHub APIs
4. **Certification** → Complete integration certification and security review
5. **Production Deployment** → Transition to production with phased rollout

## Next Steps

<CardGroup cols={2}>
  <Card title="Find Your Path" icon="map" href="/overview/find-your-path">
    Decision guide
  </Card>
  <Card title="Client Categories" icon="users" href="/baas/client-categories">
    Find your category
  </Card>
</CardGroup>


---

# CoreX Service Model

Complete front-end solution with white-labeling capabilities for financial services


URL: /baas/corex/introduction



# CoreX Service Model

Welcome to the CoreX Service Model documentation. CoreX is FinHub's comprehensive white-label front-end solution that provides a complete user interface for all FinHub financial services.

## What is CoreX?

CoreX is a fully-featured front-end platform that integrates with all FinHub products and services. Unlike the API Service Model where you build your own interface, CoreX provides a ready-to-use, customizable front-end solution that can be white-labeled with your brand.

## Key Benefits

- **Rapid Deployment**: Launch a complete financial services platform in days, not months
- **Full Feature Set**: Access all FinHub products through a unified interface
- **White-Labeling**: Customize the interface with your brand colors, logos, and styling
- **Flexible Subscription**: Choose from different subscription tiers based on your needs
- **Managed Updates**: Receive regular feature updates and security patches
- **Reduced Development**: Minimize your development effort and maintenance costs

## CoreX vs. API Service Model

| Feature | CoreX | API |
|---------|-------|-----|
| Implementation Time | Days | Weeks/Months |
| Development Effort | Minimal | Significant |
| Customization | Theme-based | Complete control |
| Maintenance | Managed by FinHub | Self-managed |
| Feature Updates | Automatic | Manual integration |
| Cost Model | Subscription-based | Usage-based |

## Platform Components

CoreX includes the following components:

### Service Distribution Channels

- **B2C Distribution Channel**: Responsive web and mobile interfaces for individual customers
- **B2B Distribution Channel**: Business customer portal with multi-user access
- **Customer Support Interface**: Tools for handling customer inquiries

### Administrative Tools

- **Admin Panel**: Administrative interface for all tenant operations
- **Reporting Suite**: Comprehensive analytics and reporting tools
- **User Management**: Role-based access control system

### Integration Components

- **API Access**: Direct API access for custom integrations (if needed)
- **Webhook Support**: Real-time event notifications
- **SSO Integration**: Single sign-on capabilities

## Subscription Tiers

CoreX is available in several subscription tiers:

| Tier | Description |
|------|-------------|
| **Starter** | Essential features for small businesses |
| **Professional** | Advanced features for growing businesses |
| **Enterprise** | Complete feature set with dedicated support |
| **Custom** | Tailored solutions for specific requirements |

## Next Steps

<CardGroup cols={2}>
  <Card title="Getting Started" icon="rocket" href="/baas/corex/getting-started">
    Start your CoreX journey
  </Card>
  <Card title="Features" icon="list-check" href="/baas/corex/features">
    Explore CoreX capabilities
  </Card>
  <Card title="White-Labeling" icon="palette" href="/baas/corex/white-labeling">
    Customize your brand
  </Card>
  <Card title="Operations" icon="gear" href="/baas/corex/operations">
    Manage your platform
  </Card>
</CardGroup>


---

# Getting Started with CoreX

Begin your CoreX journey - from registration to go-live


URL: /baas/corex/getting-started



# Getting Started with CoreX

This guide walks you through the process of launching your CoreX-powered financial services platform.

## CoreX Client Journey

```mermaid
flowchart LR
    A[Register] --> B[Select Products]
    B --> C[Provide Branding]
    C --> D[Configuration]
    D --> E[Go-Live]
```

<Steps>
  <Step title="Tenant Registration">
    Register your organization through our self-service portal
  </Step>
  <Step title="Select Products">
    Choose which FinHub products you need (FinCore, FinTrans, etc.)
  </Step>
  <Step title="Provide Branding">
    Submit your brand assets for white-labeling
  </Step>
  <Step title="Platform Configuration">
    FinHub configures your white-labeled platform
  </Step>
  <Step title="Review & Approve">
    Review the customized platform in staging
  </Step>
  <Step title="Go-Live">
    Launch your branded financial services platform
  </Step>
</Steps>

## Self-Service Registration

Get started immediately with our self-service signup:

<Card title="Register Now" icon="user-plus" href="https://bpm-beta.finhub.cloud/new-tenant/signup">
  Start your CoreX registration at bpm-beta.finhub.cloud
</Card>

## Timeline

| Phase | Duration | Activities |
|-------|----------|------------|
| **Registration** | Instant | Self-service signup, account creation |
| **Product Selection** | 1 day | Choose products and subscription tier |
| **Branding Setup** | 1 week | Brand asset collection, theme configuration |
| **Configuration** | 1-2 weeks | Platform setup, product configuration |
| **Review** | 1 week | Staging review, feedback, refinements |
| **Go-Live** | 1-2 days | Production deployment, DNS setup |

**Total: 2-4 weeks** (depending on complexity)

## What You'll Need

Before starting, prepare:

- **Brand Assets**: Logo (SVG/PNG), color palette, fonts
- **Legal Documents**: Terms of service, privacy policy
- **Domain**: Custom domain for your platform
- **Business Info**: Company details for compliance

## Next Steps

<CardGroup cols={3}>
  <Card title="Tenant Registration" icon="user-plus" href="/baas/corex/getting-started/tenant-registration">
    Register your organization
  </Card>
  <Card title="Select Products" icon="box" href="/baas/corex/getting-started/select-products">
    Choose your products
  </Card>
  <Card title="Provide Branding" icon="palette" href="/baas/corex/getting-started/provide-branding">
    Submit brand assets
  </Card>
</CardGroup>


---

# Tenant Registration

Register your organization as a CoreX tenant through self-service signup


URL: /baas/corex/getting-started/tenant-registration



# Tenant Registration

Register your organization as a CoreX tenant through our self-service portal to start your white-labeled financial services platform.

## Self-Service Registration

CoreX offers a streamlined self-registration process. Visit our tenant signup portal to get started:

<Card title="Register Now" icon="user-plus" href="https://bpm-beta.finhub.cloud/new-tenant/signup">
  Start your CoreX registration at bpm-beta.finhub.cloud
</Card>

## Registration Process

```mermaid
sequenceDiagram
    participant You
    participant Signup Portal
    participant FinHub Platform
    
    You->>Signup Portal: Visit signup page
    Signup Portal->>You: Registration form
    You->>Signup Portal: Submit business details
    Signup Portal->>FinHub Platform: Create tenant account
    FinHub Platform->>You: Welcome email with access
    You->>FinHub Platform: Access tenant portal
```

## Registration Steps

<Steps>
  <Step title="Visit Signup Portal">
    Navigate to [bpm-beta.finhub.cloud/new-tenant/signup](https://bpm-beta.finhub.cloud/new-tenant/signup)
  </Step>
  <Step title="Complete Registration Form">
    Provide your business and contact information
  </Step>
  <Step title="Verify Email">
    Confirm your email address via verification link
  </Step>
  <Step title="Access Tenant Portal">
    Log in to your new tenant account
  </Step>
</Steps>

## Required Information

During registration, you'll need to provide:

### Business Information

| Field | Description |
|-------|-------------|
| **Company Name** | Legal name of your organization |
| **Business Type** | Type of business entity |
| **Registration Number** | Company registration/incorporation number |
| **Country** | Country of incorporation |
| **Industry** | Primary business industry |

### Contact Information

| Field | Description |
|-------|-------------|
| **Primary Contact** | Name and email of main contact |
| **Technical Contact** | Name and email for technical matters |
| **Phone Number** | Business phone number |

### Platform Details

| Field | Description |
|-------|-------------|
| **Platform Name** | Desired name for your platform |
| **Target Market** | B2C, B2B, or both |
| **Expected Launch** | Approximate go-live timeline |

## What Happens After Registration

1. **Account Created**: Your tenant account is instantly provisioned
2. **Welcome Email**: Receive login credentials and getting started guide
3. **Tenant Portal Access**: Access your dashboard to configure your platform
4. **Product Selection**: Choose which FinHub products you need
5. **Branding Setup**: Upload your brand assets for white-labeling

## Next Steps

<CardGroup cols={2}>
  <Card title="Select Products" icon="box" href="/baas/corex/getting-started/select-products">
    Choose your FinHub products
  </Card>
  <Card title="Provide Branding" icon="palette" href="/baas/corex/getting-started/provide-branding">
    Submit your brand assets
  </Card>
</CardGroup>


---

# Select Products

Choose your FinHub products and subscription tier


URL: /baas/corex/getting-started/select-products



# Select Products & Tier

Choose which FinHub products you need and select the appropriate subscription tier.

## Available Products

| Product | Description | Included In |
|---------|-------------|-------------|
| **FinCore™** | Core banking, accounts, wallets | All tiers |
| **FinTrans™** | Payment processing, SEPA, SWIFT | All tiers |
| **FinCheck™** | KYC/KYB, compliance | All tiers |
| **FinCard™** | Card issuing | Professional+ |
| **FinExE™** | FX, multi-currency | Professional+ |
| **FinPOS™** | Acquiring, POS | Enterprise+ |

## Subscription Tiers

### Starter

**Best for:** Small businesses, MVPs, proof-of-concept

- FinCore™ (Basic)
- FinTrans™ (Basic)
- FinCheck™ (Basic)
- Basic white-labeling
- Standard support

### Professional

**Best for:** Growing businesses, fintechs

- All Starter features
- FinCard™ (Basic)
- FinExE™ (Basic)
- Full white-labeling
- Priority support
- Custom domain

### Enterprise

**Best for:** Large organizations, banks

- All Professional features
- FinPOS™ (Basic)
- Enhanced product tiers
- Custom UI components
- Dedicated support
- SLA guarantees

### Custom

**Best for:** Specific requirements

- Tailored product configuration
- Bespoke features
- Custom SLAs
- Dedicated account team

## Choosing Your Tier

| Question | Starter | Professional | Enterprise |
|----------|---------|--------------|------------|
| Transaction volume | Low | Medium | High |
| Customization needs | Basic | Standard | Advanced |
| Support requirements | Standard | Priority | Dedicated |
| Time to market | 2 weeks | 3 weeks | 4 weeks |

## Next Steps

<Card title="Provide Branding" icon="palette" href="/baas/corex/getting-started/provide-branding">
  Submit your brand assets
</Card>


---

# Provide Branding

Submit your brand assets for white-labeling


URL: /baas/corex/getting-started/provide-branding



# Provide Branding

Submit your brand assets to customize your CoreX platform with your visual identity.

## Required Assets

### Logo Files

| Format | Usage | Specifications |
|--------|-------|----------------|
| **SVG** | Web, documentation | Vector format, scalable |
| **PNG** | Mobile apps, emails | Min 512x512px, transparent |
| **Favicon** | Browser tabs | 32x32px and 16x16px |

### Color Palette

Provide HEX codes for:

- **Primary Color**: Main brand color
- **Secondary Color**: Accent color
- **Background Colors**: Light and dark modes
- **Text Colors**: Primary and secondary text
- **Status Colors**: Success, warning, error (optional)

### Typography

- **Heading Font**: For titles and headers
- **Body Font**: For body text
- Provide web font links or font files

## Optional Assets

- Custom icons
- Background images
- Marketing banners
- Email header images

## Brand Guidelines

If available, provide your brand guidelines document including:

- Logo usage rules
- Color specifications
- Typography guidelines
- Tone of voice

## Content Customization

- Welcome messages
- Email templates
- Terms of service
- Privacy policy
- Custom terminology

## Submission Process

1. **Access Portal**: Log into the FinHub Partner Portal
2. **Upload Assets**: Use the brand asset submission form
3. **Review**: Our team reviews your assets
4. **Configuration**: We apply your branding to the platform
5. **Preview**: Review in staging environment

## Next Steps

<CardGroup cols={2}>
  <Card title="White-Labeling Details" icon="palette" href="/baas/corex/white-labeling">
    Learn more about customization
  </Card>
  <Card title="Features" icon="list-check" href="/baas/corex/features">
    Explore platform features
  </Card>
</CardGroup>


---

# COREX Capabilities

Standard capability configurations available in the COREX Platform


URL: /baas/corex/features



# COREX Platform Capabilities

The COREX Platform offers a comprehensive set of capabilities that can be configured based on client requirements and subscription tier. Each capability is identified by a standard code (SCTxx) and can be enabled or configured to different levels depending on client needs.

## Capability Categories

<CardGroup cols={2}>
  <Card title="Core Capabilities" icon="cube" href="/baas/corex/features/sct01-b2c-channel">
    SCT01-03: Distribution channels and country operations
  </Card>
  <Card title="Payment Capabilities" icon="credit-card" href="/baas/corex/features/sct04-instant-payment">
    SCT04, 08-10: Payments, cards, FX, closed-loop
  </Card>
  <Card title="Management Capabilities" icon="chart-line" href="/baas/corex/features/sct05-subscription-management">
    SCT05-06, 11: Subscriptions, analytics, compliance
  </Card>
  <Card title="Advanced Capabilities" icon="rocket" href="/baas/corex/features/sct07-omni-channel">
    SCT07, 12-13: Omni-channel, networks, assets
  </Card>
</CardGroup>

## Core Capabilities

### SCT01 - B2C Distribution Channel

The B2C Distribution Channel provides interfaces for individual customers to access financial services.

**Features:**
- Customer registration and onboarding
- Account management and overview
- Transaction history and statements
- Payment initiation and management
- Customer support access
- Personal settings and preferences

**Platform Options:**
- Web Interface: Browser-based responsive application
- Mobile - Android: Native Android application
- Mobile - iOS: Native iOS application

**Configuration Options:**

| Level | Description |
|-------|-------------|
| Basic | Single platform (Web OR Mobile) with essential features |
| Standard | Two platforms (Web + one mobile platform) with full feature set |
| Advanced | All platforms (Web + Android + iOS) with biometric authentication and offline capabilities |

### SCT02 - B2B Distribution Channel

The B2B Distribution Channel provides interfaces for business customers with multi-user access and role-based permissions.

**Features:**
- Business entity registration and verification
- Multi-user access with role-based permissions
- Bulk payment processing
- Business account management
- Reporting and analytics
- Integration with accounting systems

**Platform Options:**
- Web Interface: Browser-based responsive application
- Mobile - Android: Native Android application
- Mobile - iOS: Native iOS application

**Configuration Options:**

| Level | Description |
|-------|-------------|
| Basic | Web-only interface with essential business account management |
| Standard | Web + one mobile platform with full business features and multi-user support |
| Advanced | All platforms (Web + Android + iOS) with accounting integrations and custom workflows |

### SCT03 - Country of Operation

A foundational core capability that defines where a tenant can operate and is used by all other capabilities.

**Features:**
- Allowed country lists - Countries where operations are permitted
- Denied country lists - Countries where operations are restricted
- Localized interfaces and content
- Country-specific compliance features
- Regional payment methods and banking connections
- Local currency support
- Country-specific reporting requirements

**Per-Capability Configuration:**
- Each capability (SCT01-SCT13) can have its own country configuration
- Tenants can enable specific capabilities in specific countries
- Different compliance requirements can be applied per country
- Capabilities can be gradually rolled out to new countries

**Configuration Options:**

| Level | Description |
|-------|-------------|
| Single | Limited to one country with full compliance |
| Regional | Multiple countries in a region (e.g., EU, APAC) with regional compliance |
| Global | Worldwide operation with country-specific compliance for each market |

## Payment Capabilities

### SCT04 - Instant Payment

Real-time payment processing capabilities for immediate fund transfers.

**Features:**
- Real-time transaction processing
- Instant payment notifications
- 24/7 availability
- Transaction status tracking
- Fallback mechanisms for failed transactions

**Configuration Options:**

| Level | Description |
|-------|-------------|
| Basic | Standard processing times |
| Standard | Same-day processing |
| Advanced | Real-time processing with instant confirmation |

### SCT08 - Usage of External Bank Cards

Integration with external card networks for payment processing.

**Features:**
- Card registration and management
- Card transaction processing
- 3D Secure authentication
- Recurring payment setup
- Card tokenization for security

**Configuration Options:**

| Level | Description |
|-------|-------------|
| Basic | Limited card types and transaction volumes |
| Standard | Full card support with standard security |
| Advanced | Enhanced security features and specialized card types |

### SCT09 - Multi-Currency Financial Operation

Support for operations across multiple currencies with exchange capabilities.

**Features:**
- Multi-currency accounts
- Foreign exchange services
- International payment processing
- Currency conversion reporting
- Exchange rate management

**Configuration Options:**

| Level | Description |
|-------|-------------|
| Basic | Limited currency support (major currencies only) |
| Standard | Extended currency support |
| Advanced | Complete global currency support with real-time FX |

### SCT10 - Closed-loop Operation

Self-contained financial ecosystem for specific use cases.

**Features:**
- Internal wallet system
- Closed network transactions
- Custom payment instruments
- Specialized loyalty integration
- Controlled ecosystem management

**Configuration Options:**

| Level | Description |
|-------|-------------|
| Basic | Simple closed-loop transactions |
| Standard | Full closed-loop ecosystem |
| Advanced | Hybrid closed/open loop with external connections |

## Management Capabilities

### SCT05 - Subscription Business Performance Management

Tools for managing subscription-based business models and recurring revenue.

**Features:**
- Subscription plan management
- Recurring billing automation
- Subscription analytics and reporting
- Customer lifecycle management
- Churn prediction and prevention

**Configuration Options:**

| Level | Description |
|-------|-------------|
| Basic | Essential subscription management |
| Standard | Full subscription business tools |
| Advanced | AI-powered subscription optimization |

### SCT06 - Decision Support System

Analytics and intelligence tools to support business decision-making.

**Features:**
- Business intelligence dashboards
- Data visualization tools
- Predictive analytics
- Custom reporting
- Decision recommendation engine

**Configuration Options:**

| Level | Description |
|-------|-------------|
| Basic | Standard reports and basic analytics |
| Standard | Interactive dashboards and custom reporting |
| Advanced | AI-powered predictions and recommendations |

### SCT11 - Compliance Management

Tools and features to ensure regulatory compliance across operations.

**Features:**
- KYC/AML verification workflows
- Regulatory reporting
- Transaction monitoring
- Audit trail and logging
- Compliance documentation management

**Configuration Options:**

| Level | Description |
|-------|-------------|
| Basic | Essential compliance features |
| Standard | Comprehensive compliance management |
| Advanced | Automated compliance with regulatory updates |

## Advanced Capabilities

### SCT07 - Omni Channel

Seamless experience across multiple customer touchpoints and channels.

**Features:**
- Consistent user experience across channels
- Cross-channel transaction continuity
- Unified customer data view
- Channel-specific optimizations
- Centralized channel management

**Configuration Options:**

| Level | Description |
|-------|-------------|
| Basic | Limited channel integration |
| Standard | Core channel integration |
| Advanced | Complete omnichannel experience |

### SCT12 - Financial Network Access

Connectivity to financial networks and banking systems.

**Features:**
- Banking network integration
- Payment scheme access
- Correspondent banking relationships
- Network status monitoring
- Fallback routing mechanisms

**Configuration Options:**

| Level | Description |
|-------|-------------|
| Basic | Limited network access |
| Standard | Regional network access |
| Advanced | Global network access with redundancy |

### SCT13 - Financial Asset Management

Tools for managing various financial assets and investments.

**Features:**
- Asset portfolio management
- Investment tracking and reporting
- Risk assessment tools
- Performance analytics
- Asset allocation optimization

**Configuration Options:**

| Level | Description |
|-------|-------------|
| Basic | Simple asset tracking |
| Standard | Comprehensive asset management |
| Advanced | Sophisticated investment tools and strategies |

## Capability Configuration by Subscription Tier

Each subscription tier includes a specific configuration of these capabilities:

| Tier | Included Capabilities |
|------|----------------------|
| **Starter** | SCT01 (Basic), SCT03 (Single), SCT04 (Basic), SCT11 (Basic) |
| **Professional** | SCT01-02 (Standard), SCT03-04 (Standard), SCT08-09 (Standard), SCT11 (Standard) |
| **Enterprise** | All capabilities at Advanced level |
| **Custom** | Tailored configuration based on requirements |

Contact your account manager for detailed information on subscription tiers and availability.

## Next Steps

<CardGroup cols={2}>
  <Card title="B2C Distribution Channel" icon="user" href="/baas/corex/features/sct01-b2c-channel">
    SCT01 - Individual customer interfaces
  </Card>
  <Card title="B2B Distribution Channel" icon="building" href="/baas/corex/features/sct02-b2b-channel">
    SCT02 - Business customer interfaces
  </Card>
</CardGroup>


---

# SCT01 - B2C Distribution Channel

Interfaces for individual customers to access financial services


URL: /baas/corex/features/sct01-b2c-channel



# SCT01 - B2C Distribution Channel

The B2C Distribution Channel provides interfaces for individual customers to access financial services through web and mobile platforms.

## Overview

This capability enables your platform to serve individual (retail) customers with a complete suite of self-service financial tools across multiple channels.

## Features

| Feature | Description |
|---------|-------------|
| **Customer Registration** | Self-service onboarding with KYC integration |
| **Account Management** | View and manage accounts, balances, and settings |
| **Transaction History** | Complete transaction history with search and filters |
| **Statements** | Generate and download account statements |
| **Payment Initiation** | Initiate transfers, payments, and bill payments |
| **Customer Support** | In-app support access and ticket management |
| **Personal Settings** | Manage preferences, notifications, and security |

## Platform Options

### Web Interface
Browser-based responsive application optimized for desktop and tablet use.

- Responsive design for all screen sizes
- Full feature parity with mobile
- Document upload and management
- Advanced reporting and analytics

### Mobile - Android
Native Android application available on Google Play Store.

- Biometric authentication (fingerprint, face)
- Push notifications
- Offline transaction queuing
- Camera integration for document capture

### Mobile - iOS
Native iOS application available on Apple App Store.

- Face ID and Touch ID support
- Apple Pay integration
- Widget support
- Siri shortcuts

## Configuration Options

| Level | Platforms | Features |
|-------|-----------|----------|
| **Basic** | Single platform (Web OR Mobile) | Essential features only |
| **Standard** | Two platforms (Web + one mobile) | Full feature set |
| **Advanced** | All platforms (Web + Android + iOS) | Biometric auth, offline capabilities |

## User Journey

```mermaid
flowchart TD
    A[Customer Registration] --> B[Identity Verification]
    B --> C[Account Activation]
    C --> D[Dashboard Access]
    D --> E[Transactions & Payments]
    D --> F[Account Management]
    D --> G[Support & Settings]
```

## Integration with Other Capabilities

| Capability | Integration |
|------------|-------------|
| **SCT03 - Country of Operation** | Determines available countries for B2C customers |
| **SCT04 - Instant Payment** | Enables real-time payment features |
| **SCT09 - Multi-Currency** | Enables multi-currency account views |
| **SCT11 - Compliance** | Integrates KYC/AML workflows |

## Subscription Tier Availability

| Tier | Configuration Level |
|------|---------------------|
| Starter | Basic |
| Professional | Standard |
| Enterprise | Advanced |
| Custom | Configurable |


---

# SCT02 - B2B Distribution Channel

Interfaces for business customers with multi-user access and role-based permissions


URL: /baas/corex/features/sct02-b2b-channel



# SCT02 - B2B Distribution Channel

The B2B Distribution Channel provides interfaces for business customers with multi-user access, role-based permissions, and advanced business tools.

## Overview

This capability enables your platform to serve business customers with comprehensive financial management tools, supporting multiple users within an organization with granular access controls.

## Features

| Feature | Description |
|---------|-------------|
| **Business Registration** | Corporate onboarding with KYB verification |
| **Multi-User Access** | Multiple users per organization |
| **Role-Based Permissions** | Granular access control and approval workflows |
| **Bulk Payments** | Process multiple payments in batches |
| **Business Account Management** | Manage multiple accounts and sub-accounts |
| **Reporting & Analytics** | Business intelligence and financial reports |
| **Accounting Integration** | Connect with accounting software |

## Platform Options

### Web Interface
Browser-based responsive application designed for business operations.

- Advanced dashboard with business KPIs
- Bulk transaction processing
- Multi-level approval workflows
- Comprehensive audit logs
- Export to accounting formats

### Mobile - Android
Native Android application for business users on-the-go.

- Approval notifications and actions
- Transaction authorization
- Quick payment initiation
- Push alerts for pending actions

### Mobile - iOS
Native iOS application for business users.

- Face ID for transaction approval
- Mobile authorization
- Quick access to pending tasks
- Business notifications

## Configuration Options

| Level | Platforms | Features |
|-------|-----------|----------|
| **Basic** | Web-only | Essential business account management |
| **Standard** | Web + one mobile | Full business features, multi-user support |
| **Advanced** | All platforms | Accounting integrations, custom workflows |

## User Roles

| Role | Permissions |
|------|-------------|
| **Admin** | Full access, user management, settings |
| **Finance Manager** | Payments, reports, account management |
| **Approver** | Transaction approval, view-only access |
| **Operator** | Payment initiation, limited access |
| **Viewer** | Read-only access to accounts and reports |

## Business Workflow

```mermaid
flowchart TD
    A[Business Registration] --> B[KYB Verification]
    B --> C[Admin Account Setup]
    C --> D[Add Users & Roles]
    D --> E[Configure Approval Rules]
    E --> F[Business Operations]
    
    F --> G[Bulk Payments]
    F --> H[Reporting]
    F --> I[Account Management]
```

## Integration with Other Capabilities

| Capability | Integration |
|------------|-------------|
| **SCT03 - Country of Operation** | Determines available countries for B2B operations |
| **SCT05 - Subscription Management** | Recurring billing for business clients |
| **SCT06 - Decision Support** | Business analytics and reporting |
| **SCT11 - Compliance** | KYB workflows and transaction monitoring |

## Subscription Tier Availability

| Tier | Configuration Level |
|------|---------------------|
| Starter | Not included |
| Professional | Standard |
| Enterprise | Advanced |
| Custom | Configurable |


---

# SCT03 - Country of Operation

Foundational capability defining where a tenant can operate


URL: /baas/corex/features/sct03-country-operation



# SCT03 - Country of Operation

A foundational core capability that defines where a tenant can operate and is used by all other capabilities. Each tenant can configure which countries they can operate in per capability.

## Overview

This capability forms the foundation of your platform's geographic scope, enabling you to define allowed and restricted countries for operations, with localized experiences for each market.

## Features

| Feature | Description |
|---------|-------------|
| **Allowed Country Lists** | Countries where operations are permitted |
| **Denied Country Lists** | Countries where operations are restricted |
| **Localized Interfaces** | Language and content localization |
| **Country-Specific Compliance** | Regional regulatory requirements |
| **Regional Payment Methods** | Local payment rails and methods |
| **Local Currency Support** | Native currency handling per country |
| **Country Reporting** | Country-specific regulatory reports |

## Per-Capability Configuration

Each capability (SCT01-SCT13) can have its own country configuration:

| Configuration | Description |
|---------------|-------------|
| **Capability-Specific Countries** | Enable specific capabilities in specific countries |
| **Differentiated Compliance** | Different compliance requirements per country |
| **Gradual Rollout** | Phase capabilities into new countries over time |
| **Regional Grouping** | Group countries by region for unified management |

## Configuration Options

| Level | Scope | Features |
|-------|-------|----------|
| **Single** | One country | Full compliance for single market |
| **Regional** | Multiple countries in region (EU, APAC) | Regional compliance framework |
| **Global** | Worldwide operation | Country-specific compliance per market |

## Supported Regions

### Europe
- EU member states (SEPA zone)
- EEA countries
- UK and Switzerland

### Asia-Pacific
- Southeast Asia
- East Asia
- Oceania

### Americas
- North America
- Latin America
- Caribbean

### Middle East & Africa
- GCC countries
- North Africa
- Sub-Saharan Africa

## Country Configuration Flow

```mermaid
flowchart TD
    A[Select Target Countries] --> B[Compliance Assessment]
    B --> C[Enable Capabilities per Country]
    C --> D[Configure Local Settings]
    D --> E[Localization Setup]
    E --> F[Go-Live per Country]
```

## Compliance Considerations

<Warning>
Different countries have different regulatory requirements. Ensure you understand and comply with local regulations before enabling operations in new markets.
</Warning>

| Region | Key Considerations |
|--------|-------------------|
| **EU/EEA** | GDPR, PSD2, AML5/6 directives |
| **US** | State licensing, OFAC, FinCEN |
| **UK** | FCA regulations, UK GDPR |
| **APAC** | Varies by country, data localization |

## Integration with Other Capabilities

All capabilities reference SCT03 for geographic scope:

- **SCT01/02**: Determines customer countries
- **SCT04**: Available instant payment schemes
- **SCT09**: Available currencies
- **SCT12**: Financial network access per country

## Subscription Tier Availability

| Tier | Configuration Level |
|------|---------------------|
| Starter | Single |
| Professional | Regional |
| Enterprise | Global |
| Custom | Configurable |


---

# SCT04 - Instant Payment

Real-time payment processing capabilities for immediate fund transfers


URL: /baas/corex/features/sct04-instant-payment



# SCT04 - Instant Payment

Real-time payment processing capabilities for immediate fund transfers with 24/7 availability.

## Overview

This capability enables your platform to process payments in real-time, providing instant confirmation and immediate fund availability for your customers.

## Features

| Feature | Description |
|---------|-------------|
| **Real-Time Processing** | Immediate transaction execution |
| **Instant Notifications** | Real-time payment confirmations |
| **24/7 Availability** | Round-the-clock payment processing |
| **Status Tracking** | Live transaction status updates |
| **Fallback Mechanisms** | Automatic retry and alternative routing |

## Payment Schemes Supported

| Scheme | Region | Settlement Time |
|--------|--------|-----------------|
| **SEPA Instant** | EU/EEA | < 10 seconds |
| **Faster Payments** | UK | < 2 hours |
| **RTP** | US | Real-time |
| **IMPS** | India | Real-time |
| **NPP** | Australia | Real-time |

## Configuration Options

| Level | Processing Time | Features |
|-------|-----------------|----------|
| **Basic** | Standard (T+1) | Batch processing |
| **Standard** | Same-day | Intraday settlement |
| **Advanced** | Real-time | Instant confirmation, 24/7 |

## Transaction Flow

```mermaid
sequenceDiagram
    participant Customer
    participant Platform
    participant Payment Network
    participant Beneficiary
    
    Customer->>Platform: Initiate Payment
    Platform->>Platform: Validate & Authorize
    Platform->>Payment Network: Submit Instant Payment
    Payment Network->>Beneficiary: Credit Funds
    Payment Network->>Platform: Confirmation
    Platform->>Customer: Instant Notification
```

## Use Cases

- **P2P Transfers**: Instant money transfers between individuals
- **Bill Payments**: Real-time bill settlements
- **Merchant Payments**: Instant payment confirmation for merchants
- **Payroll**: Same-day salary disbursements
- **Refunds**: Instant refund processing

## Integration with Other Capabilities

| Capability | Integration |
|------------|-------------|
| **SCT03 - Country of Operation** | Available payment schemes per country |
| **SCT09 - Multi-Currency** | Cross-currency instant payments |
| **SCT11 - Compliance** | Real-time fraud screening |
| **SCT12 - Financial Network** | Network connectivity for instant rails |

## Subscription Tier Availability

| Tier | Configuration Level |
|------|---------------------|
| Starter | Basic |
| Professional | Standard |
| Enterprise | Advanced |
| Custom | Configurable |


---

# SCT08 - External Bank Cards

Integration with external card networks for payment processing


URL: /baas/corex/features/sct08-external-cards



# SCT08 - Usage of External Bank Cards

Integration with external card networks for payment processing, enabling card-based transactions on your platform.

## Overview

This capability enables your platform to accept and process payments from external bank cards, including credit, debit, and prepaid cards from major card networks.

## Features

| Feature | Description |
|---------|-------------|
| **Card Registration** | Secure card enrollment and storage |
| **Transaction Processing** | Process card payments and refunds |
| **3D Secure** | Strong customer authentication (SCA) |
| **Recurring Payments** | Subscription and recurring billing |
| **Card Tokenization** | Secure card data storage |

## Supported Card Networks

| Network | Card Types |
|---------|------------|
| **Visa** | Credit, Debit, Prepaid |
| **Mastercard** | Credit, Debit, Prepaid |
| **American Express** | Credit, Corporate |
| **Discover** | Credit, Debit |
| **UnionPay** | Credit, Debit |

## Configuration Options

| Level | Card Types | Features |
|-------|------------|----------|
| **Basic** | Limited (Visa, MC debit only) | Standard transaction limits |
| **Standard** | Full support | 3D Secure, recurring payments |
| **Advanced** | All networks | Enhanced security, specialized cards |

## Card Processing Flow

```mermaid
sequenceDiagram
    participant Customer
    participant Platform
    participant 3DS Server
    participant Card Network
    participant Issuer
    
    Customer->>Platform: Enter Card Details
    Platform->>Platform: Tokenize Card
    Platform->>3DS Server: 3D Secure Check
    3DS Server->>Customer: Authentication Challenge
    Customer->>3DS Server: Authenticate
    3DS Server->>Platform: Auth Result
    Platform->>Card Network: Process Payment
    Card Network->>Issuer: Authorize
    Issuer->>Card Network: Approved
    Card Network->>Platform: Confirmation
    Platform->>Customer: Payment Complete
```

## Security Features

| Feature | Description |
|---------|-------------|
| **PCI DSS Compliance** | Full PCI DSS Level 1 certification |
| **Tokenization** | Card data replaced with secure tokens |
| **3D Secure 2.0** | Frictionless and challenge flows |
| **Fraud Detection** | Real-time fraud scoring |
| **Velocity Controls** | Transaction limits and velocity checks |

## Use Cases

- **E-commerce Payments**: Online card payments
- **In-App Purchases**: Mobile card transactions
- **Subscription Billing**: Recurring card charges
- **Card-to-Wallet**: Fund wallet from external card
- **Refunds**: Return funds to original card

## Integration with Other Capabilities

| Capability | Integration |
|------------|-------------|
| **SCT03 - Country of Operation** | Available card networks per country |
| **SCT09 - Multi-Currency** | Multi-currency card processing |
| **SCT11 - Compliance** | Card fraud monitoring |

## Subscription Tier Availability

| Tier | Configuration Level |
|------|---------------------|
| Starter | Not included |
| Professional | Standard |
| Enterprise | Advanced |
| Custom | Configurable |


---

# SCT09 - Multi-Currency Financial Operation

Support for operations across multiple currencies with exchange capabilities


URL: /baas/corex/features/sct09-multi-currency



# SCT09 - Multi-Currency Financial Operation

Support for operations across multiple currencies with exchange capabilities, enabling global financial services.

## Overview

This capability enables your platform to operate across multiple currencies, providing foreign exchange services, multi-currency accounts, and international payment processing.

## Features

| Feature | Description |
|---------|-------------|
| **Multi-Currency Accounts** | Hold balances in multiple currencies |
| **Foreign Exchange** | Real-time currency conversion |
| **International Payments** | Cross-border payment processing |
| **FX Reporting** | Currency conversion reporting |
| **Exchange Rate Management** | Competitive rate sourcing |

## Supported Currencies

### Major Currencies
- USD, EUR, GBP, JPY, CHF, CAD, AUD, NZD

### European Currencies
- SEK, NOK, DKK, PLN, CZK, HUF, RON, BGN

### Asian Currencies
- CNY, HKD, SGD, INR, THB, MYR, IDR, PHP

### Other Currencies
- AED, SAR, ZAR, BRL, MXN, and 100+ more

## Configuration Options

| Level | Currencies | Features |
|-------|------------|----------|
| **Basic** | Major currencies only (8) | Standard FX rates |
| **Standard** | Extended (30+) | Competitive rates, FX reporting |
| **Advanced** | Global (100+) | Real-time FX, rate locking |

## Currency Conversion Flow

```mermaid
sequenceDiagram
    participant Customer
    participant Platform
    participant FX Engine
    participant Payment Rail
    
    Customer->>Platform: Request Transfer (EUR to USD)
    Platform->>FX Engine: Get Exchange Rate
    FX Engine->>Platform: Quote (1.0850)
    Platform->>Customer: Display Rate & Fees
    Customer->>Platform: Confirm
    Platform->>FX Engine: Lock Rate
    Platform->>Payment Rail: Process Transfer
    Payment Rail->>Platform: Confirmation
    Platform->>Customer: Transfer Complete
```

## FX Rate Types

| Type | Description | Use Case |
|------|-------------|----------|
| **Spot Rate** | Current market rate | Immediate conversions |
| **Locked Rate** | Fixed rate for period | Large transactions |
| **Forward Rate** | Future date rate | Planned transfers |

## Multi-Currency Account Features

- **Single Account, Multiple Currencies**: Hold balances in different currencies
- **Auto-Conversion**: Automatic conversion for payments
- **Currency Preference**: Default currency settings
- **Balance View**: Unified or per-currency balance view

## Integration with Other Capabilities

| Capability | Integration |
|------------|-------------|
| **SCT03 - Country of Operation** | Available currencies per country |
| **SCT04 - Instant Payment** | Cross-currency instant transfers |
| **SCT12 - Financial Network** | International payment rails |

## Subscription Tier Availability

| Tier | Configuration Level |
|------|---------------------|
| Starter | Not included |
| Professional | Standard |
| Enterprise | Advanced |
| Custom | Configurable |


---

# SCT10 - Closed-loop Operation

Self-contained financial ecosystem for specific use cases


URL: /baas/corex/features/sct10-closed-loop



# SCT10 - Closed-loop Operation

Self-contained financial ecosystem for specific use cases, enabling controlled internal transactions and custom payment instruments.

## Overview

This capability enables your platform to operate a closed-loop financial ecosystem where transactions occur within a controlled network, ideal for loyalty programs, corporate ecosystems, or specialized marketplaces.

## Features

| Feature | Description |
|---------|-------------|
| **Internal Wallet System** | Closed-loop wallet balances |
| **Network Transactions** | Internal peer-to-peer transfers |
| **Custom Instruments** | Branded payment instruments |
| **Loyalty Integration** | Points and rewards systems |
| **Ecosystem Management** | Control participant access |

## Use Cases

| Use Case | Description |
|----------|-------------|
| **Corporate Ecosystem** | Internal corporate payments and expenses |
| **Marketplace** | Buyer-seller transactions within platform |
| **Loyalty Program** | Points earning and redemption |
| **Gift Cards** | Closed-loop gift card systems |
| **Campus/Venue** | University or venue payment systems |

## Configuration Options

| Level | Features | External Access |
|-------|----------|-----------------|
| **Basic** | Simple closed-loop transactions | None |
| **Standard** | Full ecosystem with loyalty | Limited (load only) |
| **Advanced** | Hybrid closed/open loop | Full external connections |

## Closed-Loop Architecture

```mermaid
flowchart TD
    A[Load Funds] --> B[Closed-Loop Wallet]
    B --> C[Internal Transfer]
    B --> D[Merchant Payment]
    B --> E[Loyalty Redemption]
    
    C --> B
    D --> F[Merchant Wallet]
    E --> G[Points Account]
    
    subgraph Closed Network
        B
        C
        D
        E
        F
        G
    end
```

## Wallet Types

| Type | Purpose |
|------|---------|
| **Consumer Wallet** | Individual user balances |
| **Merchant Wallet** | Business/merchant accounts |
| **Float Wallet** | System float management |
| **Reward Wallet** | Loyalty points and rewards |

## Integration Options

### Hybrid Mode (Advanced)
Connect closed-loop ecosystem to external networks:

- **Load from Bank**: Fund closed-loop from external bank account
- **Load from Card**: Fund from external debit/credit card
- **Cashout**: Withdraw to external bank account

## Integration with Other Capabilities

| Capability | Integration |
|------------|-------------|
| **SCT01/02 - Distribution Channels** | Customer/merchant interfaces |
| **SCT05 - Subscription Management** | Recurring value loads |
| **SCT11 - Compliance** | Internal transaction monitoring |

## Subscription Tier Availability

| Tier | Configuration Level |
|------|---------------------|
| Starter | Not included |
| Professional | Basic |
| Enterprise | Advanced |
| Custom | Configurable |


---

# SCT05 - Subscription Business Performance Management

Tools for managing subscription-based business models and recurring revenue


URL: /baas/corex/features/sct05-subscription-management



# SCT05 - Subscription Business Performance Management

Tools for managing subscription-based business models and recurring revenue, enabling automated billing and customer lifecycle management.

## Overview

This capability provides comprehensive tools for managing subscription-based services, from plan creation to billing automation and churn prevention.

## Features

| Feature | Description |
|---------|-------------|
| **Plan Management** | Create and manage subscription plans |
| **Recurring Billing** | Automated billing cycles |
| **Analytics & Reporting** | Subscription metrics and insights |
| **Lifecycle Management** | Customer journey automation |
| **Churn Prevention** | Predictive churn analytics |

## Subscription Plan Features

| Feature | Description |
|---------|-------------|
| **Flexible Pricing** | Fixed, tiered, usage-based pricing |
| **Trial Periods** | Free trial configuration |
| **Billing Cycles** | Weekly, monthly, annual billing |
| **Proration** | Automatic proration on changes |
| **Add-ons** | Optional add-on products |

## Configuration Options

| Level | Features | Automation |
|-------|----------|------------|
| **Basic** | Essential plan management | Manual billing |
| **Standard** | Full subscription tools | Automated billing |
| **Advanced** | AI-powered optimization | Predictive analytics |

## Subscription Lifecycle

```mermaid
flowchart TD
    A[Trial Sign-up] --> B[Trial Period]
    B --> C{Convert?}
    C -->|Yes| D[Active Subscription]
    C -->|No| E[Trial Expired]
    
    D --> F[Renewal]
    D --> G[Upgrade/Downgrade]
    D --> H[Cancellation Request]
    
    F --> D
    G --> D
    H --> I[Retention Offer]
    I -->|Accept| D
    I -->|Decline| J[Cancelled]
```

## Key Metrics

| Metric | Description |
|--------|-------------|
| **MRR** | Monthly Recurring Revenue |
| **ARR** | Annual Recurring Revenue |
| **Churn Rate** | Customer cancellation rate |
| **LTV** | Customer Lifetime Value |
| **CAC** | Customer Acquisition Cost |

## Billing Automation

- **Invoice Generation**: Automatic invoice creation
- **Payment Collection**: Automated payment processing
- **Dunning Management**: Failed payment recovery
- **Renewal Reminders**: Pre-renewal notifications
- **Receipt Delivery**: Automatic receipt emails

## Integration with Other Capabilities

| Capability | Integration |
|------------|-------------|
| **SCT01/02 - Channels** | Subscription management UI |
| **SCT04 - Instant Payment** | Payment collection |
| **SCT06 - Decision Support** | Subscription analytics |
| **SCT08 - External Cards** | Card-based recurring billing |

## Subscription Tier Availability

| Tier | Configuration Level |
|------|---------------------|
| Starter | Not included |
| Professional | Standard |
| Enterprise | Advanced |
| Custom | Configurable |


---

# SCT06 - Decision Support System

Analytics and intelligence tools to support business decision-making


URL: /baas/corex/features/sct06-decision-support



# SCT06 - Decision Support System

Analytics and intelligence tools to support business decision-making with data visualization and predictive insights.

## Overview

This capability provides business intelligence dashboards, data visualization, and predictive analytics to help you make informed decisions about your financial services platform.

## Features

| Feature | Description |
|---------|-------------|
| **BI Dashboards** | Interactive business intelligence views |
| **Data Visualization** | Charts, graphs, and visual reports |
| **Predictive Analytics** | AI-powered forecasting |
| **Custom Reporting** | Build custom report templates |
| **Recommendations** | Decision recommendation engine |

## Dashboard Categories

| Dashboard | Metrics |
|-----------|---------|
| **Executive** | Revenue, growth, key KPIs |
| **Operations** | Transaction volumes, success rates |
| **Customer** | Acquisition, retention, engagement |
| **Risk** | Fraud, compliance, exposure |
| **Financial** | P&L, cash flow, projections |

## Configuration Options

| Level | Features | Analytics |
|-------|----------|-----------|
| **Basic** | Standard reports | Historical data |
| **Standard** | Interactive dashboards, custom reports | Trend analysis |
| **Advanced** | AI-powered insights | Predictive analytics |

## Analytics Capabilities

### Descriptive Analytics
- Transaction summaries
- Customer demographics
- Revenue breakdowns
- Operational metrics

### Diagnostic Analytics
- Trend identification
- Anomaly detection
- Root cause analysis
- Performance comparisons

### Predictive Analytics (Advanced)
- Revenue forecasting
- Churn prediction
- Fraud probability
- Demand forecasting

### Prescriptive Analytics (Advanced)
- Action recommendations
- Optimization suggestions
- Risk mitigation strategies

## Report Types

```mermaid
flowchart LR
    A[Data Sources] --> B[Report Engine]
    B --> C[Standard Reports]
    B --> D[Custom Reports]
    B --> E[Scheduled Reports]
    B --> F[Ad-hoc Queries]
    
    C --> G[Dashboard]
    D --> G
    E --> H[Email Delivery]
    F --> G
```

## Integration with Other Capabilities

| Capability | Integration |
|------------|-------------|
| **SCT01/02 - Channels** | Analytics dashboard access |
| **SCT05 - Subscriptions** | Subscription analytics |
| **SCT11 - Compliance** | Compliance reporting |
| **All Capabilities** | Cross-capability insights |

## Subscription Tier Availability

| Tier | Configuration Level |
|------|---------------------|
| Starter | Basic |
| Professional | Standard |
| Enterprise | Advanced |
| Custom | Configurable |


---

# SCT11 - Compliance Management

Tools and features to ensure regulatory compliance across operations


URL: /baas/corex/features/sct11-compliance-management



# SCT11 - Compliance Management

Tools and features to ensure regulatory compliance across operations, including KYC/AML workflows, transaction monitoring, and regulatory reporting.

## Overview

This capability provides comprehensive compliance management tools to help your platform meet regulatory requirements across all markets you operate in.

## Features

| Feature | Description |
|---------|-------------|
| **KYC/AML Workflows** | Customer verification processes |
| **Regulatory Reporting** | Automated regulatory reports |
| **Transaction Monitoring** | Real-time transaction screening |
| **Audit Trail** | Complete activity logging |
| **Documentation Management** | Compliance document storage |

## KYC/AML Features

| Feature | Description |
|---------|-------------|
| **Identity Verification** | Document and biometric verification |
| **Sanctions Screening** | Global sanctions list checking |
| **PEP Screening** | Politically Exposed Person checks |
| **Adverse Media** | Negative news monitoring |
| **Ongoing Monitoring** | Continuous customer monitoring |

## Configuration Options

| Level | Features | Automation |
|-------|----------|------------|
| **Basic** | Essential compliance | Manual workflows |
| **Standard** | Comprehensive management | Semi-automated |
| **Advanced** | Full automation | Regulatory updates auto-applied |

## Compliance Workflow

```mermaid
flowchart TD
    A[Customer Onboarding] --> B[Identity Verification]
    B --> C[Document Collection]
    C --> D[Sanctions Screening]
    D --> E[Risk Assessment]
    E --> F{Approved?}
    
    F -->|Yes| G[Account Active]
    F -->|No| H[Manual Review]
    H --> I{Decision}
    I -->|Approve| G
    I -->|Reject| J[Application Rejected]
    
    G --> K[Ongoing Monitoring]
    K --> L[Periodic Review]
    L --> G
```

## Regulatory Coverage

| Regulation | Coverage |
|------------|----------|
| **GDPR** | Data protection and privacy |
| **PSD2** | Payment services directive |
| **AML5/6** | Anti-money laundering directives |
| **FATF** | Financial action task force guidelines |
| **Local Regulations** | Country-specific requirements |

## Reporting Capabilities

| Report Type | Description |
|-------------|-------------|
| **SAR** | Suspicious Activity Reports |
| **CTR** | Currency Transaction Reports |
| **STR** | Suspicious Transaction Reports |
| **Regulatory Returns** | Periodic regulatory submissions |
| **Audit Reports** | Internal and external audit support |

## Integration with Other Capabilities

| Capability | Integration |
|------------|-------------|
| **SCT01/02 - Channels** | KYC flows in onboarding |
| **SCT03 - Country** | Country-specific compliance |
| **SCT04 - Payments** | Transaction screening |
| **SCT06 - Decision Support** | Compliance dashboards |

## Subscription Tier Availability

| Tier | Configuration Level |
|------|---------------------|
| Starter | Basic |
| Professional | Standard |
| Enterprise | Advanced |
| Custom | Configurable |


---

# SCT07 - Omni Channel

Seamless experience across multiple customer touchpoints and channels


URL: /baas/corex/features/sct07-omni-channel



# SCT07 - Omni Channel

Seamless experience across multiple customer touchpoints and channels, providing unified customer data and cross-channel continuity.

## Overview

This capability enables your platform to deliver a consistent and seamless customer experience across all channels - web, mobile, in-person, and support - with unified data and transaction continuity.

## Features

| Feature | Description |
|---------|-------------|
| **Consistent UX** | Unified experience across all channels |
| **Cross-Channel Continuity** | Continue transactions across channels |
| **Unified Customer View** | Single view of customer data |
| **Channel Optimization** | Channel-specific optimizations |
| **Centralized Management** | Single point of channel control |

## Supported Channels

| Channel | Description |
|---------|-------------|
| **Web** | Browser-based applications |
| **Mobile Apps** | Native iOS and Android |
| **SMS/USSD** | Text-based interactions |
| **Email** | Transactional and marketing |
| **Push Notifications** | Real-time alerts |
| **Voice** | Phone/IVR integration |
| **Chat** | In-app and web chat |

## Configuration Options

| Level | Channels | Features |
|-------|----------|----------|
| **Basic** | Limited (2-3 channels) | Basic integration |
| **Standard** | Core channels | Cross-channel continuity |
| **Advanced** | All channels | Complete omnichannel experience |

## Omni-Channel Architecture

```mermaid
flowchart TD
    subgraph Channels
        A[Web]
        B[Mobile]
        C[SMS]
        D[Email]
        E[Voice]
    end
    
    A --> F[Channel Hub]
    B --> F
    C --> F
    D --> F
    E --> F
    
    F --> G[Unified Customer Profile]
    F --> H[Transaction Engine]
    F --> I[Notification Engine]
    
    G --> J[Personalization]
    H --> K[Cross-Channel Continuity]
    I --> L[Multi-Channel Delivery]
```

## Cross-Channel Continuity

| Scenario | Description |
|----------|-------------|
| **Start Web, Finish Mobile** | Begin transaction on web, complete on mobile |
| **Support Handoff** | Transfer context from chat to phone |
| **Saved Sessions** | Resume incomplete transactions |
| **Synchronized State** | Real-time sync across devices |

## Personalization

- Channel preferences per customer
- Preferred notification channels
- Device-specific optimizations
- Language and locale settings

## Integration with Other Capabilities

| Capability | Integration |
|------------|-------------|
| **SCT01/02 - Channels** | B2C/B2B channel delivery |
| **SCT06 - Decision Support** | Channel analytics |
| **SCT11 - Compliance** | Channel-specific compliance |

## Subscription Tier Availability

| Tier | Configuration Level |
|------|---------------------|
| Starter | Not included |
| Professional | Standard |
| Enterprise | Advanced |
| Custom | Configurable |


---

# SCT12 - Financial Network Access

Connectivity to financial networks and banking systems


URL: /baas/corex/features/sct12-financial-network



# SCT12 - Financial Network Access

Connectivity to financial networks and banking systems, enabling access to payment schemes, banking networks, and correspondent relationships.

## Overview

This capability provides connectivity to global financial infrastructure, including payment networks, banking systems, and correspondent banking relationships.

## Features

| Feature | Description |
|---------|-------------|
| **Banking Network Integration** | Connect to banking systems |
| **Payment Scheme Access** | Access to payment rails |
| **Correspondent Banking** | Correspondent relationships |
| **Network Monitoring** | Real-time status monitoring |
| **Fallback Routing** | Alternative routing mechanisms |

## Supported Networks

### European Networks
| Network | Description |
|---------|-------------|
| **SEPA** | Single Euro Payments Area |
| **SEPA Instant** | Real-time euro payments |
| **TARGET2** | High-value euro transfers |
| **Faster Payments** | UK instant payments |
| **BACS** | UK batch payments |

### Global Networks
| Network | Description |
|---------|-------------|
| **SWIFT** | International wire transfers |
| **SWIFT gpi** | Enhanced cross-border payments |
| **Ripple** | Blockchain-based transfers |

### Regional Networks
| Network | Region |
|---------|--------|
| **ACH** | United States |
| **FedWire** | United States |
| **IMPS/UPI** | India |
| **NPP** | Australia |

## Configuration Options

| Level | Access | Features |
|-------|--------|----------|
| **Basic** | Limited networks | Single region |
| **Standard** | Regional access | Multi-network routing |
| **Advanced** | Global access | Full redundancy |

## Network Architecture

```mermaid
flowchart LR
    A[Platform] --> B[Network Gateway]
    
    B --> C[SEPA]
    B --> D[SWIFT]
    B --> E[Local Rails]
    B --> F[Card Networks]
    
    C --> G[EU Banks]
    D --> H[Global Banks]
    E --> I[Regional Banks]
    F --> J[Card Issuers]
```

## Network Features

| Feature | Description |
|---------|-------------|
| **Smart Routing** | Optimal network selection |
| **Fallback** | Automatic failover |
| **Status Monitoring** | Real-time network health |
| **Cost Optimization** | Lowest-cost routing |
| **Speed Optimization** | Fastest route selection |

## Integration with Other Capabilities

| Capability | Integration |
|------------|-------------|
| **SCT03 - Country** | Network availability per country |
| **SCT04 - Instant Payment** | Instant payment rails |
| **SCT09 - Multi-Currency** | Cross-border networks |

## Subscription Tier Availability

| Tier | Configuration Level |
|------|---------------------|
| Starter | Basic |
| Professional | Standard |
| Enterprise | Advanced |
| Custom | Configurable |


---

# SCT13 - Financial Asset Management

Tools for managing various financial assets and investments


URL: /baas/corex/features/sct13-asset-management



# SCT13 - Financial Asset Management

Tools for managing various financial assets and investments, including portfolio management, tracking, and analytics.

## Overview

This capability provides tools for managing financial assets beyond traditional banking, including investment portfolios, securities, and alternative assets.

## Features

| Feature | Description |
|---------|-------------|
| **Portfolio Management** | Manage asset portfolios |
| **Investment Tracking** | Track investment performance |
| **Risk Assessment** | Portfolio risk analysis |
| **Performance Analytics** | Returns and performance metrics |
| **Asset Allocation** | Optimization tools |

## Asset Types Supported

| Asset Type | Description |
|------------|-------------|
| **Equities** | Stocks and shares |
| **Fixed Income** | Bonds and securities |
| **Funds** | Mutual funds, ETFs |
| **Alternative** | Real estate, commodities |
| **Digital Assets** | Cryptocurrencies (where permitted) |
| **Structured Products** | Complex financial instruments |

## Configuration Options

| Level | Features | Assets |
|-------|----------|--------|
| **Basic** | Simple tracking | Limited asset types |
| **Standard** | Comprehensive management | Standard assets |
| **Advanced** | Sophisticated tools | All asset classes |

## Portfolio Management Features

### Portfolio Overview
- Total portfolio value
- Asset allocation breakdown
- Performance summary
- Risk metrics

### Position Management
- Buy/sell orders
- Position sizing
- Rebalancing tools
- Stop-loss management

### Reporting
- Performance reports
- Tax reports
- Regulatory reports
- Custom reports

## Investment Workflow

```mermaid
flowchart TD
    A[Investment Goal] --> B[Risk Assessment]
    B --> C[Asset Allocation]
    C --> D[Portfolio Construction]
    D --> E[Order Execution]
    E --> F[Position Monitoring]
    F --> G[Performance Review]
    G --> H{Rebalance?}
    H -->|Yes| C
    H -->|No| F
```

## Risk Management

| Feature | Description |
|---------|-------------|
| **VaR** | Value at Risk calculations |
| **Stress Testing** | Scenario analysis |
| **Concentration Limits** | Position limits |
| **Volatility Tracking** | Portfolio volatility |
| **Correlation Analysis** | Asset correlations |

## Integration with Other Capabilities

| Capability | Integration |
|------------|-------------|
| **SCT03 - Country** | Available assets per jurisdiction |
| **SCT06 - Decision Support** | Investment analytics |
| **SCT09 - Multi-Currency** | Multi-currency portfolios |
| **SCT11 - Compliance** | Investment compliance |

## Subscription Tier Availability

| Tier | Configuration Level |
|------|---------------------|
| Starter | Not included |
| Professional | Not included |
| Enterprise | Standard |
| Custom | Configurable |


---

# White-Labeling

Customize the CoreX Platform with your brand identity


URL: /baas/corex/white-labeling



# White-Labeling

The CoreX Platform offers comprehensive white-labeling capabilities, allowing you to deliver a seamless branded experience to your customers.

## What is White-Labeling?

White-labeling customizes the CoreX Platform with your brand identity, creating the appearance that the platform is your own proprietary solution.

<CardGroup cols={3}>
  <Card title="Visual Branding" icon="palette" href="/baas/corex/white-labeling/visual-branding">
    Colors, logos, fonts
  </Card>
  <Card title="Domain Setup" icon="globe" href="/baas/corex/white-labeling/domain-setup">
    Custom domains
  </Card>
  <Card title="Templates" icon="file" href="/baas/corex/white-labeling/templates">
    Email & notifications
  </Card>
</CardGroup>

## Branding Elements

### Visual Identity

- **Logo**: Replace FinHub logo with yours
- **Color Scheme**: Apply your brand colors
- **Typography**: Use your brand fonts
- **Icons**: Custom icon sets
- **Favicon**: Your logo in browser tabs

### Domain and URLs

- **Custom Domain**: banking.yourcompany.com
- **SSL Certificate**: Secure your domain
- **URL Structure**: Custom URL patterns

### Content Customization

- **Terminology**: Custom product names
- **Messages**: Welcome and error text
- **Legal Documents**: Your terms and privacy policy

### Communication Templates

- **Email Templates**: Branded emails
- **SMS Templates**: Custom notifications
- **PDF Reports**: Branded statements

## White-Labeling Tiers

| Tier | Customization Level |
|------|---------------------|
| **Starter** | Basic logo, primary color |
| **Professional** | Full visual customization, custom domain |
| **Enterprise** | Complete customization, mobile app branding |
| **Custom** | Bespoke design, custom app store presence |

## Next Steps

<CardGroup cols={2}>
  <Card title="Visual Branding" icon="palette" href="/baas/corex/white-labeling/visual-branding">
    Customize visuals
  </Card>
  <Card title="Domain Setup" icon="globe" href="/baas/corex/white-labeling/domain-setup">
    Set up your domain
  </Card>
</CardGroup>


---

# Visual Branding

Customize visual elements of your CoreX platform


URL: /baas/corex/white-labeling/visual-branding



# Visual Branding

Customize the visual elements of the CoreX platform to match your brand identity.

## Logo Integration

| Location | Format | Size |
|----------|--------|------|
| Header | SVG/PNG | 200x50px |
| Login | SVG/PNG | 300x100px |
| Mobile | PNG | 512x512px |
| Favicon | ICO/PNG | 32x32px |

## Color Scheme

### Primary Colors

- **Primary**: Main brand color (buttons, links)
- **Primary Dark**: Hover states
- **Primary Light**: Backgrounds

### Secondary Colors

- **Secondary**: Accent color
- **Background**: Page backgrounds
- **Surface**: Card backgrounds

### Status Colors

- **Success**: Green tones
- **Warning**: Yellow/orange tones
- **Error**: Red tones

## Typography

- **Heading Font**: For titles (H1-H6)
- **Body Font**: For paragraph text
- **Monospace**: For code/numbers

## Application

Visual branding is applied across:

- Web application
- Mobile apps
- Email templates
- PDF documents
- Admin panel


---

# Domain Setup

Configure custom domain for your CoreX platform


URL: /baas/corex/white-labeling/domain-setup



# Domain Setup

Deliver the CoreX platform under your own domain for a seamless branded experience.

## Custom Domain

Use your own domain instead of a FinHub subdomain:

| Type | Example |
|------|---------|
| **Custom** | banking.yourcompany.com |
| **Default** | yourcompany.finhub.cloud |

## Setup Process

1. **Choose Domain**: Select your custom domain
2. **DNS Configuration**: Add CNAME records
3. **SSL Certificate**: Automated via Let's Encrypt or your own
4. **Verification**: FinHub verifies DNS configuration
5. **Activation**: Domain goes live

## DNS Records

Add these records to your DNS:

```
CNAME  banking.yourcompany.com  →  yourcompany.finhub.cloud
```

## SSL Certificate

Options:
- **Automated**: FinHub provisions Let's Encrypt certificate
- **Custom**: Upload your own SSL certificate

## URL Structure

Customize URL patterns:

| Default | Custom Option |
|---------|---------------|
| /accounts | /my-accounts |
| /payments | /transfers |
| /cards | /my-cards |

*Available in Professional tier and above*


---

# Templates

Customize email and notification templates


URL: /baas/corex/white-labeling/templates



# Communication Templates

Brand all customer communications with your visual identity and voice.

## Email Templates

Customizable email types:

| Category | Templates |
|----------|-----------|
| **Onboarding** | Welcome, verification, activation |
| **Transactions** | Confirmation, receipt, failed |
| **Security** | Password reset, 2FA, login alert |
| **Statements** | Monthly, annual, custom |
| **Marketing** | Promotions (if enabled) |

## Email Elements

- Header with your logo
- Brand colors
- Custom footer
- Contact information
- Social media links

## SMS Templates

- OTP verification
- Transaction alerts
- Security notifications
- Payment reminders

## Push Notifications

Mobile app notifications with:

- Your app icon
- Custom sounds (optional)
- Deep links to app sections

## PDF Reports

Branded documents:

- Account statements
- Transaction receipts
- Tax documents
- Compliance reports

## Content Guidelines

- Use your brand voice
- Customize terminology
- Localize for markets
- Maintain compliance


---

# Settings Guide

CoreX platform configuration settings


URL: /baas/corex/configuration/settings-guide



# Settings Guide

Configure your CoreX platform settings during setup and ongoing operations.

## Configuration Categories

### Business Settings

- Company information
- Operating countries
- Supported currencies
- Business hours
- Contact information

### Product Configuration

- Enabled products (FinCore, FinTrans, etc.)
- Feature toggles
- Transaction limits
- Fee structures

### User Settings

- Registration requirements
- KYC levels
- Account types
- Default limits

### Security Settings

- Password policies
- 2FA requirements
- Session timeouts
- IP restrictions

### Notification Settings

- Email notifications
- SMS alerts
- Push notification preferences
- Webhook configurations

## Configuration Process

1. **Initial Setup**: FinHub configures based on your requirements
2. **Review**: You review settings in staging
3. **Adjustment**: Request changes as needed
4. **Production**: Settings applied to live environment

## Ongoing Changes

After go-live, request configuration changes through:

- Admin Panel (self-service options)
- Support ticket (complex changes)
- Account manager (enterprise clients)


---

# CoreX Operations

Day-to-day operations for CoreX clients


URL: /baas/corex/operations



# CoreX Operations

Manage your CoreX platform day-to-day through the Admin Panel and operational tools.

<CardGroup cols={2}>
  <Card title="Admin Panel" icon="gauge" href="/baas/corex/operations/admin-panel">
    Administrative dashboard
  </Card>
  <Card title="Go-Live" icon="rocket" href="/baas/corex/operations/go-live">
    Launch checklist
  </Card>
</CardGroup>

## Operational Responsibilities

### FinHub Manages

- Platform infrastructure
- Security updates
- Feature releases
- System monitoring
- Compliance framework

### You Manage

- Customer support
- Business operations
- Marketing
- Compliance reviews
- Manual approvals

## Key Tools

| Tool | Purpose |
|------|---------|
| **Admin Panel** | Customer management, reporting |
| **Support Interface** | Customer inquiries |
| **Reporting Suite** | Analytics and exports |

## Support Channels

| Tier | Support Level |
|------|---------------|
| **Starter** | Email support, 24h response |
| **Professional** | Priority email, 8h response |
| **Enterprise** | Dedicated support, 4h response |

## Next Steps

<CardGroup cols={2}>
  <Card title="Admin Panel" icon="gauge" href="/baas/corex/operations/admin-panel">
    Learn the admin tools
  </Card>
  <Card title="Go-Live" icon="rocket" href="/baas/corex/operations/go-live">
    Launch checklist
  </Card>
</CardGroup>


---

# Admin Panel

Administrative dashboard for CoreX tenant operations


URL: /baas/corex/operations/admin-panel



# Admin Panel

The Admin Panel is the administrative interface for managing your CoreX platform operations.

## Key Functions

| Function | Description |
|----------|-------------|
| **Customer Management** | View, search, manage customers |
| **Transaction Monitoring** | Monitor transactions, handle issues |
| **Approvals** | Manual approval workflows |
| **Reporting** | Analytics and report generation |
| **User Management** | Admin user access control |

## Customer Management

- Search customers by ID, email, phone
- View customer details and activity
- Manage KYC status
- Freeze/unfreeze accounts
- Update customer limits

## Transaction Monitoring

- Real-time transaction feed
- Search by reference, amount, status
- Flag suspicious transactions
- Handle failed transactions
- Export transaction data

## Approval Workflows

- High-value transaction approvals
- KYC review and approval
- Account opening approvals
- Compliance case management

## Reporting

- Dashboard with key metrics
- Custom report builder
- Scheduled report delivery
- Data export (CSV, Excel, PDF)

## Access Control

- Role-based permissions
- Audit logging
- Activity tracking
- Session management


---

# Go-Live

CoreX go-live checklist and launch process


URL: /baas/corex/operations/go-live



# Go-Live

Launch your CoreX platform to production with this go-live checklist.

## Pre-Launch Checklist

### Branding & Configuration

- [ ] Logo and visual branding approved
- [ ] Color scheme finalized
- [ ] Email templates reviewed
- [ ] Terms of service uploaded
- [ ] Privacy policy uploaded

### Domain & SSL

- [ ] Custom domain configured
- [ ] DNS records verified
- [ ] SSL certificate active
- [ ] Redirects tested

### Testing

- [ ] User registration flow tested
- [ ] KYC process verified
- [ ] Payment flows tested
- [ ] Admin panel functions verified
- [ ] Mobile apps tested (if applicable)

### Compliance

- [ ] KYC/AML workflows approved
- [ ] Regulatory requirements met
- [ ] Data protection verified
- [ ] Audit logging confirmed

### Operations

- [ ] Support team trained
- [ ] Admin users created
- [ ] Escalation procedures documented
- [ ] Monitoring alerts configured

## Launch Day

1. **Final Review**: Last check of staging
2. **DNS Switch**: Point domain to production
3. **Verification**: Test critical flows
4. **Monitoring**: Watch for issues
5. **Announcement**: Notify stakeholders

## Post-Launch

- Monitor transaction volumes
- Track error rates
- Gather user feedback
- Address issues promptly
- Plan first feature updates


---

# API Service Model

Direct API integration for custom implementations


URL: /baas/api/introduction



# API Service Model

The API Service Model provides direct access to FinHub's APIs for building custom financial applications with complete control over the user experience.

## What is the API Service Model?

Unlike the CoreX Service Model which provides a pre-built front-end, the API Service Model gives you direct access to FinHub's RESTful APIs, allowing you to build your own custom user interface and integration.

## Key Benefits

- **Complete Control**: Build your own UI/UX
- **Flexible Integration**: Integrate into existing applications
- **Custom Workflows**: Implement unique business logic
- **Developer-Friendly**: Comprehensive documentation, SDKs, sandbox
- **Real-Time Events**: Webhooks for instant notifications

## API vs. CoreX

| Feature | API | CoreX |
|---------|-----|-------|
| Implementation Time | 4-12 weeks | 2-4 weeks |
| Development Effort | Significant | Minimal |
| UI/UX Control | Complete | Theme-based |
| Maintenance | Self-managed | Managed by FinHub |
| Cost Model | Usage-based | Subscription-based |

## What You Get

- **Full API Access**: All FinHub endpoints
- **Sandbox Environment**: Test safely
- **Documentation**: Comprehensive API reference
- **SDKs**: Libraries for popular languages
- **Webhooks**: Real-time event notifications
- **Admin Panel**: Tenant operations dashboard

## Client Journey

<Steps>
  <Step title="Registration">
    Apply on the FinHub Developer Portal
  </Step>
  <Step title="Sandbox Access">
    Get credentials and explore APIs
  </Step>
  <Step title="Development">
    Build your integration
  </Step>
  <Step title="Certification">
    Complete security and integration review
  </Step>
  <Step title="Production">
    Go live with phased rollout
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Getting Started" icon="rocket" href="/baas/api/getting-started">
    Begin your API journey
  </Card>
  <Card title="Quick Start" icon="bolt" href="/baas/api/getting-started/quick-start">
    Make your first API call
  </Card>
  <Card title="Integration Guide" icon="plug" href="/baas/api/integration/flows">
    Complete integration flows
  </Card>
  <Card title="API Reference" icon="code" href="/baas/api/reference">
    Browse API documentation
  </Card>
</CardGroup>


---

# Getting Started

Complete the tenant registration process with FinHub API


URL: /baas/api/getting-started



# Getting Started

Before you can start integrating with FinHub API, you need to complete the tenant registration process. This section guides you through registration, compliance requirements, product selection, and receiving your API credentials.

## Getting Started Overview

```mermaid
flowchart LR
    A[Register] --> B[Compliance Review]
    B --> C[Select Products]
    C --> D[Receive Credentials]
    D --> E[Start Integration]
```

## Self-Service Registration

Get started immediately with our self-service signup:

<Card title="Register Now" icon="user-plus" href="https://bpm-beta.finhub.cloud/new-tenant/signup">
  Start your API tenant registration at bpm-beta.finhub.cloud
</Card>

## Steps to Get Started

<Steps>
  <Step title="Tenant Registration">
    Register your organization through our self-service portal
  </Step>
  <Step title="Compliance Requirements">
    Provide required compliance documentation (AML policy, KYC procedures)
  </Step>
  <Step title="Select Your Products">
    Choose which FinHub products you want to integrate
  </Step>
  <Step title="Receive Credentials">
    Get your sandbox tenant credentials and API access
  </Step>
</Steps>

## What You'll Need

Before starting the registration process, prepare the following:

### Business Documentation
- Certificate of Incorporation
- Business Registration Certificate
- Tax Identification Number

### Compliance Documentation
- AML Policy
- KYC Procedures
- Risk Assessment Framework

### Technical Contacts
- Primary Technical Contact
- Security Officer Contact
- Operations Manager Contact

## Timeline

| Phase | Duration | Activities |
|-------|----------|------------|
| Registration | Instant | Self-service signup, account creation |
| Compliance Review | 3-7 days | Document verification |
| Account Setup | 1-2 days | Credential provisioning |

## Next Steps

<CardGroup cols={2}>
  <Card title="Tenant Registration" icon="building" href="/baas/api/getting-started/tenant-registration">
    Start your registration process
  </Card>
  <Card title="Compliance Requirements" icon="shield-check" href="/baas/api/getting-started/compliance-requirements">
    Review compliance documentation
  </Card>
</CardGroup>


---

# Tenant Registration

Register your organization as a FinHub API tenant through self-service signup


URL: /baas/api/getting-started/tenant-registration



# Tenant Registration

Register your organization as a FinHub API tenant through our self-service portal to start your API integration.

## Self-Service Registration

FinHub offers a streamlined self-registration process. Visit our tenant signup portal to get started:

<Card title="Register Now" icon="user-plus" href="https://bpm-beta.finhub.cloud/new-tenant/signup">
  Start your API tenant registration at bpm-beta.finhub.cloud
</Card>

## Registration Process

```mermaid
sequenceDiagram
    participant You
    participant Signup Portal
    participant FinHub Platform
    participant Compliance
    
    You->>Signup Portal: Visit signup page
    Signup Portal->>You: Registration form
    You->>Signup Portal: Submit business details
    Signup Portal->>FinHub Platform: Create tenant account
    FinHub Platform->>Compliance: Submit for review
    Compliance-->>FinHub Platform: Approval
    FinHub Platform->>You: Issue API credentials
```

## Registration Steps

<Steps>
  <Step title="Visit Signup Portal">
    Navigate to [bpm-beta.finhub.cloud/new-tenant/signup](https://bpm-beta.finhub.cloud/new-tenant/signup)
  </Step>
  <Step title="Complete Registration Form">
    Provide your business and contact information
  </Step>
  <Step title="Verify Email">
    Confirm your email address via verification link
  </Step>
  <Step title="Submit Compliance Documents">
    Upload required business and compliance documentation
  </Step>
  <Step title="Receive API Credentials">
    Get your sandbox credentials after approval
  </Step>
</Steps>

## Required Documents

| Document Type | Description | Format |
|---------------|-------------|--------|
| Certificate of Incorporation | Proof of legal entity | PDF |
| Business Registration | Government registration | PDF |
| Tax ID Certificate | Tax identification | PDF |
| Authorized Signatories | List of authorized persons | PDF |
| Bank Reference Letter | Banking relationship proof | PDF |

## Account Creation

Upon approval, FinHub will:

1. Create your tenant account in our system
2. Configure your selected products
3. Set up your sandbox environment
4. Generate API credentials

## Credential Delivery

You will receive:

- **Sandbox URL**: Your dedicated sandbox endpoint
- **Tenant ID**: Your unique tenant identifier
- **API Credentials**: Client ID and Client Secret
- **Admin Access**: Tenant Operation Panel credentials

## Next Steps

After completing registration:

1. Review [Compliance Requirements](/baas/api/getting-started/compliance-requirements)
2. Proceed to [Selecting Your Products](/baas/api/getting-started/selecting-products)
3. Set up your [Development Environment](/baas/api/development)


---

# Compliance Requirements

Compliance documentation required for FinHub tenant registration


URL: /baas/api/getting-started/compliance-requirements



# Compliance Requirements

As a regulated financial services platform, FinHub requires all tenants to meet specific compliance requirements before accessing the platform.

## Required Compliance Documentation

### 1. Anti-Money Laundering (AML) Policy

Your AML policy should include:

- Customer due diligence procedures
- Transaction monitoring processes
- Suspicious activity reporting procedures
- Record-keeping requirements
- Staff training programs

### 2. Know Your Customer (KYC) Procedures

Document your KYC procedures covering:

- Customer identification requirements
- Verification methods and data sources
- Risk-based approach to customer due diligence
- Enhanced due diligence for high-risk customers
- Ongoing monitoring procedures

### 3. Risk Assessment Framework

Provide your risk assessment framework including:

- Risk categorization methodology
- Customer risk scoring criteria
- Geographic risk factors
- Product/service risk assessment
- Periodic review procedures

## Compliance Review Process

| Stage | Duration | Activities |
|-------|----------|------------|
| Document Submission | Day 1 | Submit all required documents |
| Initial Review | Days 2-3 | Completeness check |
| Detailed Assessment | Days 4-7 | Compliance team review |
| Clarifications | If needed | Address any questions |
| Approval | Final | Compliance sign-off |

## Regulatory Considerations

Depending on your business model and jurisdiction, you may need:

- **Financial Services License**: If operating as a regulated entity
- **Data Protection Registration**: GDPR compliance for EU operations
- **PCI DSS Compliance**: For card-related operations
- **Local Regulatory Approvals**: Country-specific requirements

## Ongoing Compliance

After registration, tenants must:

- Maintain updated compliance documentation
- Report material changes to FinHub
- Participate in periodic compliance reviews
- Complete required training programs

## Next Steps

<CardGroup cols={2}>
  <Card title="Select Products" icon="cube" href="/baas/api/getting-started/selecting-products">
    Choose your FinHub products
  </Card>
  <Card title="Receive Credentials" icon="key" href="/baas/api/getting-started/receiving-credentials">
    Get your API access
  </Card>
</CardGroup>


---

# Selecting Your Products

Choose the FinHub products that fit your business needs


URL: /baas/api/getting-started/selecting-products



# Selecting Your Products

FinHub offers a comprehensive suite of financial technology products. This guide helps you select the right products for your integration.

## Available Products

| Product | Description | Key Capabilities |
|---------|-------------|------------------|
| **FinCore™** | Core Banking System | Account management, transaction processing, multi-currency |
| **FinTrans™** | Transaction Processing | Domestic/international transfers, real-time payments |
| **FinCheck™** | RegTech & Compliance | KYC/KYB verification, AML screening |
| **FinCard™** | Card Issuing | Virtual/physical cards, card management |
| **FinExE™** | Currency Exchange | Multi-currency exchange, FX management |
| **FinPOS™** | Point of Sale | Payment acceptance, merchant management |

## Product Selection by Use Case

### For Embedded Finance
- FinCore™ (Core Banking)
- FinTrans™ (Payments)
- FinCheck™ (Compliance)

### For Banking-as-a-Service
- FinCore™ (Core Banking)
- FinTrans™ (Payments)
- FinCard™ (Card Issuing)
- FinCheck™ (Compliance)

### For Business Banking
- FinCore™ (Core Banking)
- FinTrans™ (Payments)
- FinCheck™ (Compliance)

## Product Dependencies

Some products require other products as prerequisites:

```mermaid
flowchart TD
    A[FinCore™] --> B[FinTrans™]
    A --> C[FinCard™]
    A --> D[FinExE™]
    E[FinCheck™] --> A
```

## Next Steps

After selecting your products:

1. Confirm your selection with your account manager
2. Proceed to [Receiving Credentials](/baas/api/getting-started/receiving-credentials)
3. Begin your [Development Environment](/baas/api/development) setup


---

# Receiving Credentials

Understand the credentials you receive after tenant registration


URL: /baas/api/getting-started/receiving-credentials



# Receiving Credentials

After completing the registration process, you will receive your FinHub credentials to access the platform.

## Credentials Package

You will receive the following credentials:

### API Credentials

| Credential | Description | Usage |
|------------|-------------|-------|
| **Tenant ID** | Unique identifier for your organization | Required in X-Tenant-ID header |
| **Client ID** | API client identifier | Used for authentication |
| **Client Secret** | API client secret | Used for authentication |
| **Sandbox URL** | Base URL for sandbox API | API endpoint |

### Portal Access

| Access | Description |
|--------|-------------|
| **Tenant Operation Panel** | Administrative dashboard for managing your tenant |
| **Developer Portal** | Access to API documentation and playground |

## Credential Delivery

Credentials are delivered securely via:

1. **Welcome Email** - Contains portal access and initial setup instructions
2. **Developer Portal** - API credentials available after first login
3. **Secure Channel** - Client secrets delivered via secure channel

## Security Best Practices

<Warning>
Never share your credentials or commit them to version control systems.
</Warning>

- Store credentials securely using environment variables or secret management
- Rotate credentials periodically
- Use different credentials for sandbox and production
- Implement proper access control for credential access

## Verifying Your Credentials

Test your credentials with a simple authentication request:

```bash
curl -X POST "https://gateway.sandbox.finhub.cloud/api/v2/auth/sandbox/token" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -d '{
    "username": "YOUR_USERNAME",
    "password": "YOUR_PASSWORD",
    "customerId": "YOUR_CLIENT_ID",
    "customerSecret": "YOUR_CLIENT_SECRET",
    "accountType": "b2b"
  }'
```

A successful response indicates your credentials are working correctly.

## Next Steps

<CardGroup cols={2}>
  <Card title="Development Environment" icon="laptop-code" href="/baas/api/development">
    Set up your sandbox
  </Card>
  <Card title="Categorization Hierarchy" icon="sitemap" href="/baas/api/integration/flows/common/categorization-hierarchy">
    Understand customer categories
  </Card>
</CardGroup>


---

# API Capabilities

Standard capability configurations available through the FinHub API


URL: /baas/api/capabilities



# API Capabilities

The FinHub API provides access to a comprehensive set of capabilities that can be configured based on your subscription tier. Each capability is identified by a standard code (SCTxx) and can be enabled or configured to different levels depending on your integration needs.

## Capability Categories

<CardGroup cols={2}>
  <Card title="Core Capabilities" icon="cube" href="/baas/api/capabilities/sct03-country-operation">
    SCT03, 10, 13: Country operations, wallets, asset management
  </Card>
  <Card title="Payment Capabilities" icon="credit-card" href="/baas/api/capabilities/sct04-instant-payment">
    SCT04, 09, 12: Payments, multi-currency, financial networks
  </Card>
  <Card title="Management Capabilities" icon="chart-line" href="/baas/api/capabilities/sct05-subscription-management">
    SCT05, 06, 11: Subscriptions, analytics, compliance
  </Card>
  <Card title="Advanced Capabilities" icon="rocket" href="/baas/api/capabilities/sct07-omni-channel">
    SCT07: Omni-channel integration
  </Card>
</CardGroup>

## Available Capabilities

### Core Capabilities

| Code | Capability | Description |
|------|------------|-------------|
| **SCT03** | Country of Operation | Define operational countries and regional compliance |
| **SCT10** | Closed-loop Operation | Internal wallet system and closed network transactions |
| **SCT13** | Financial Asset Management | Portfolio management and investment tracking |

### Payment Capabilities

| Code | Capability | Description |
|------|------------|-------------|
| **SCT04** | Instant Payment | Real-time payment processing and fund transfers |
| **SCT09** | Multi-Currency Financial Operation | Multi-currency accounts and FX services |
| **SCT12** | Financial Network Access | Connectivity to SEPA, SWIFT, and local rails |

### Management Capabilities

| Code | Capability | Description |
|------|------------|-------------|
| **SCT05** | Subscription Business Performance Management | Recurring billing and subscription analytics |
| **SCT06** | Decision Support System | Business intelligence and predictive analytics |
| **SCT11** | Compliance Management | KYC/AML workflows and regulatory reporting |

### Advanced Capabilities

| Code | Capability | Description |
|------|------------|-------------|
| **SCT07** | Omni Channel | Cross-channel transaction continuity |

## Capability Configuration by Subscription Tier

| Tier | Included Capabilities |
|------|----------------------|
| **Starter** | SCT03 (Single), SCT04 (Basic), SCT11 (Basic) |
| **Professional** | SCT03-04 (Standard), SCT05-06 (Standard), SCT09 (Standard), SCT11 (Standard) |
| **Enterprise** | All capabilities at Advanced level |
| **Custom** | Tailored configuration based on requirements |

Contact your account manager for detailed information on subscription tiers and availability.

## API vs CoreX Capabilities

<Note>
The API Service Model provides access to **10 of the 13** FinHub capabilities. Distribution channel capabilities (SCT01, SCT02) and external card processing (SCT08) are only available through the CoreX white-label platform.
</Note>

| Capability | API | CoreX |
|------------|-----|-------|
| SCT01 - B2C Distribution Channel | ❌ | ✅ |
| SCT02 - B2B Distribution Channel | ❌ | ✅ |
| SCT03 - Country of Operation | ✅ | ✅ |
| SCT04 - Instant Payment | ✅ | ✅ |
| SCT05 - Subscription Management | ✅ | ✅ |
| SCT06 - Decision Support | ✅ | ✅ |
| SCT07 - Omni Channel | ✅ | ✅ |
| SCT08 - External Bank Cards | ❌ | ✅ |
| SCT09 - Multi-Currency | ✅ | ✅ |
| SCT10 - Closed-loop | ✅ | ✅ |
| SCT11 - Compliance | ✅ | ✅ |
| SCT12 - Financial Network | ✅ | ✅ |
| SCT13 - Asset Management | ✅ | ✅ |

## Next Steps

<CardGroup cols={2}>
  <Card title="Country of Operation" icon="globe" href="/baas/api/capabilities/sct03-country-operation">
    SCT03 - Configure operational regions
  </Card>
  <Card title="Instant Payment" icon="bolt" href="/baas/api/capabilities/sct04-instant-payment">
    SCT04 - Real-time payment processing
  </Card>
</CardGroup>


---

# SCT03 - Country of Operation

Foundational capability defining where a tenant can operate via API


URL: /baas/api/capabilities/sct03-country-operation



# SCT03 - Country of Operation

A foundational core capability that defines where a tenant can operate and is used by all other capabilities. Each tenant can configure which countries they can operate in per capability.

## Overview

This capability forms the foundation of your API integration's geographic scope, enabling you to define allowed and restricted countries for operations, with localized compliance for each market.

## Features

| Feature | Description |
|---------|-------------|
| **Allowed Country Lists** | Countries where operations are permitted |
| **Denied Country Lists** | Countries where operations are restricted |
| **Country-Specific Compliance** | Regional regulatory requirements |
| **Regional Payment Methods** | Local payment rails and methods |
| **Local Currency Support** | Native currency handling per country |
| **Country-Specific Reporting** | Regulatory reports per jurisdiction |

## Per-Capability Configuration

| Configuration | Description |
|---------------|-------------|
| **Capability-Specific Countries** | Enable specific capabilities in specific countries |
| **Differentiated Compliance** | Different compliance requirements per country |
| **Gradual Rollout** | Phase capabilities into new countries over time |

## Configuration Options

| Level | Scope | Features |
|-------|-------|----------|
| **Single** | One country | Full compliance for single market |
| **Regional** | Multiple countries in region (EU, APAC) | Regional compliance framework |
| **Global** | Worldwide operation | Country-specific compliance per market |

## API Usage

### Get Tenant Country Configuration

```bash
GET /api/v1/configuration/countries
Authorization: Bearer {access_token}
```

**Response:**
```json
{
  "allowed_countries": ["GB", "DE", "FR", "NL", "BE"],
  "denied_countries": ["KP", "IR", "CU"],
  "default_country": "GB",
  "capabilities_by_country": {
    "GB": ["SCT03", "SCT04", "SCT09", "SCT11", "SCT12"],
    "DE": ["SCT03", "SCT04", "SCT11"],
    "FR": ["SCT03", "SCT04", "SCT11"]
  }
}
```

### Validate Country for Operation

```bash
POST /api/v1/configuration/countries/validate
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "country_code": "DE",
  "capability": "SCT04"
}
```

## Integration with Other Capabilities

| Capability | Integration |
|------------|-------------|
| **SCT04 - Instant Payment** | Available payment schemes per country |
| **SCT09 - Multi-Currency** | Available currencies per country |
| **SCT11 - Compliance** | Country-specific KYC/AML rules |
| **SCT12 - Financial Network** | Network access per country |

## Related API Reference

<Card title="Configuration APIs" icon="gear" href="/baas/api/reference/administration">
  View detailed API specifications
</Card>

## Subscription Tier Availability

| Tier | Configuration Level |
|------|---------------------|
| Starter | Single |
| Professional | Regional |
| Enterprise | Global |
| Custom | Configurable |


---

# SCT10 - Closed-loop Operation

Self-contained financial ecosystem for specific use cases via API


URL: /baas/api/capabilities/sct10-closed-loop



# SCT10 - Closed-loop Operation

Self-contained financial ecosystem for specific use cases, enabling controlled internal transactions and custom payment instruments through the API.

## Overview

This capability enables your platform to operate a closed-loop financial ecosystem where transactions occur within a controlled network, ideal for loyalty programs, corporate ecosystems, or specialized marketplaces.

## Features

| Feature | Description |
|---------|-------------|
| **Internal Wallet System** | Closed-loop wallet balances |
| **Network Transactions** | Internal peer-to-peer transfers |
| **Custom Instruments** | Branded payment instruments |
| **Loyalty Integration** | Points and rewards systems |
| **Ecosystem Management** | Control participant access |

## Configuration Options

| Level | Features | External Access |
|-------|----------|-----------------|
| **Basic** | Simple closed-loop transactions | None |
| **Standard** | Full ecosystem with loyalty | Limited (load only) |
| **Advanced** | Hybrid closed/open loop | Full external connections |

## API Usage

### Create Closed-loop Wallet

```bash
POST /api/v1/wallets
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "customer_id": "cust_abc123",
  "wallet_type": "CLOSED_LOOP",
  "currency": "EUR",
  "name": "Loyalty Wallet"
}
```

**Response:**
```json
{
  "wallet_id": "wal_xyz789",
  "customer_id": "cust_abc123",
  "wallet_type": "CLOSED_LOOP",
  "currency": "EUR",
  "balance": 0.00,
  "status": "ACTIVE"
}
```

### Internal Transfer

```bash
POST /api/v1/wallets/transfers/internal
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "source_wallet_id": "wal_xyz789",
  "destination_wallet_id": "wal_merchant001",
  "amount": 50.00,
  "currency": "EUR",
  "reference": "Purchase at Store A"
}
```

### Load Wallet from External Source (Advanced)

```bash
POST /api/v1/wallets/{wallet_id}/load
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "amount": 100.00,
  "source_type": "BANK_TRANSFER",
  "source_reference": "ref_123456"
}
```

## Use Cases

| Use Case | Description |
|----------|-------------|
| **Corporate Ecosystem** | Internal corporate payments and expenses |
| **Marketplace** | Buyer-seller transactions within platform |
| **Loyalty Program** | Points earning and redemption |
| **Gift Cards** | Closed-loop gift card systems |

## Integration with Other Capabilities

| Capability | Integration |
|------------|-------------|
| **SCT03 - Country** | Wallet availability per country |
| **SCT05 - Subscription** | Recurring value loads |
| **SCT11 - Compliance** | Internal transaction monitoring |

## Related API Reference

<Card title="Wallet APIs" icon="wallet" href="/baas/api/reference/financial-operations/account-information">
  View detailed wallet API specifications
</Card>

## Subscription Tier Availability

| Tier | Configuration Level |
|------|---------------------|
| Starter | Not included |
| Professional | Basic |
| Enterprise | Advanced |
| Custom | Configurable |


---

# SCT13 - Financial Asset Management

Tools for managing various financial assets and investments via API


URL: /baas/api/capabilities/sct13-asset-management



# SCT13 - Financial Asset Management

Tools for managing various financial assets and investments, including portfolio management, tracking, and analytics through the API.

## Overview

This capability provides API access to tools for managing financial assets beyond traditional banking, including investment portfolios, securities, and alternative assets.

## Features

| Feature | Description |
|---------|-------------|
| **Portfolio Management** | Manage asset portfolios |
| **Investment Tracking** | Track investment performance |
| **Risk Assessment** | Portfolio risk analysis |
| **Performance Analytics** | Returns and performance metrics |
| **Asset Allocation** | Optimization tools |

## Configuration Options

| Level | Features | Assets |
|-------|----------|--------|
| **Basic** | Simple tracking | Limited asset types |
| **Standard** | Comprehensive management | Standard assets |
| **Advanced** | Sophisticated tools | All asset classes |

## API Usage

### Get Portfolio Summary

```bash
GET /api/v1/portfolios/{portfolio_id}
Authorization: Bearer {access_token}
```

**Response:**
```json
{
  "portfolio_id": "port_abc123",
  "customer_id": "cust_xyz789",
  "total_value": 150000.00,
  "currency": "EUR",
  "positions": [
    {
      "asset_type": "EQUITY",
      "symbol": "AAPL",
      "quantity": 100,
      "current_value": 17500.00,
      "unrealized_pnl": 2500.00
    },
    {
      "asset_type": "FIXED_INCOME",
      "symbol": "BOND_EU_10Y",
      "quantity": 50,
      "current_value": 52500.00,
      "unrealized_pnl": -500.00
    }
  ],
  "performance": {
    "ytd_return": 8.5,
    "total_return": 15.2
  }
}
```

### Get Risk Assessment

```bash
GET /api/v1/portfolios/{portfolio_id}/risk
Authorization: Bearer {access_token}
```

**Response:**
```json
{
  "portfolio_id": "port_abc123",
  "risk_metrics": {
    "var_95": 5200.00,
    "volatility": 12.5,
    "sharpe_ratio": 1.2,
    "beta": 0.85
  },
  "concentration_risk": {
    "top_holding_pct": 35.0,
    "sector_concentration": "MODERATE"
  }
}
```

### Execute Trade

```bash
POST /api/v1/portfolios/{portfolio_id}/orders
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "asset_type": "EQUITY",
  "symbol": "MSFT",
  "side": "BUY",
  "quantity": 25,
  "order_type": "MARKET"
}
```

## Asset Types Supported

| Asset Type | Description |
|------------|-------------|
| **Equities** | Stocks and shares |
| **Fixed Income** | Bonds and securities |
| **Funds** | Mutual funds, ETFs |
| **Alternative** | Real estate, commodities |

## Integration with Other Capabilities

| Capability | Integration |
|------------|-------------|
| **SCT03 - Country** | Available assets per jurisdiction |
| **SCT06 - Decision Support** | Investment analytics |
| **SCT09 - Multi-Currency** | Multi-currency portfolios |
| **SCT11 - Compliance** | Investment compliance |

## Related API Reference

<Card title="Portfolio APIs" icon="chart-pie" href="/baas/api/reference/financial-operations">
  View detailed portfolio API specifications
</Card>

## Subscription Tier Availability

| Tier | Configuration Level |
|------|---------------------|
| Starter | Not included |
| Professional | Not included |
| Enterprise | Standard |
| Custom | Configurable |


---

# SCT04 - Instant Payment

Real-time payment processing capabilities for immediate fund transfers via API


URL: /baas/api/capabilities/sct04-instant-payment



# SCT04 - Instant Payment

Real-time payment processing capabilities for immediate fund transfers with 24/7 availability through the API.

## Overview

This capability enables your platform to process payments in real-time via API, providing instant confirmation and immediate fund availability for your customers.

## Features

| Feature | Description |
|---------|-------------|
| **Real-Time Processing** | Immediate transaction execution |
| **Instant Notifications** | Real-time payment confirmations via webhooks |
| **24/7 Availability** | Round-the-clock payment processing |
| **Status Tracking** | Live transaction status updates |
| **Fallback Mechanisms** | Automatic retry and alternative routing |

## Configuration Options

| Level | Processing Time | Features |
|-------|-----------------|----------|
| **Basic** | Standard (T+1) | Batch processing |
| **Standard** | Same-day | Intraday settlement |
| **Advanced** | Real-time | Instant confirmation, 24/7 |

## API Usage

### Initiate Instant Transfer

```bash
POST /api/v1/transfers
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "source_account_id": "acc_123456",
  "destination": {
    "type": "IBAN",
    "iban": "DE89370400440532013000",
    "name": "John Doe"
  },
  "amount": 250.00,
  "currency": "EUR",
  "payment_type": "INSTANT",
  "reference": "Invoice #12345"
}
```

**Response:**
```json
{
  "transfer_id": "txn_abc789",
  "status": "COMPLETED",
  "amount": 250.00,
  "currency": "EUR",
  "payment_type": "INSTANT",
  "executed_at": "2024-01-15T10:30:00Z",
  "settlement_time": "INSTANT"
}
```

### Get Transfer Status

```bash
GET /api/v1/transfers/{transfer_id}
Authorization: Bearer {access_token}
```

**Response:**
```json
{
  "transfer_id": "txn_abc789",
  "status": "COMPLETED",
  "status_history": [
    {"status": "INITIATED", "timestamp": "2024-01-15T10:29:58Z"},
    {"status": "PROCESSING", "timestamp": "2024-01-15T10:29:59Z"},
    {"status": "COMPLETED", "timestamp": "2024-01-15T10:30:00Z"}
  ]
}
```

## Webhook Notifications

```json
{
  "event": "transfer.completed",
  "transfer_id": "txn_abc789",
  "status": "COMPLETED",
  "amount": 250.00,
  "currency": "EUR",
  "timestamp": "2024-01-15T10:30:00Z"
}
```

## Payment Schemes Supported

| Scheme | Region | Settlement Time |
|--------|--------|-----------------|
| **SEPA Instant** | EU/EEA | < 10 seconds |
| **Faster Payments** | UK | < 2 hours |
| **SWIFT gpi** | Global | Same-day |

## Integration with Other Capabilities

| Capability | Integration |
|------------|-------------|
| **SCT03 - Country** | Available payment schemes per country |
| **SCT09 - Multi-Currency** | Cross-currency instant payments |
| **SCT11 - Compliance** | Real-time fraud screening |
| **SCT12 - Financial Network** | Network connectivity |

## Related API Reference

<Card title="Transfer APIs" icon="paper-plane" href="/baas/api/reference/financial-operations/transfers">
  View detailed transfer API specifications
</Card>

## Subscription Tier Availability

| Tier | Configuration Level |
|------|---------------------|
| Starter | Basic |
| Professional | Standard |
| Enterprise | Advanced |
| Custom | Configurable |


---

# SCT09 - Multi-Currency Financial Operation

Support for operations across multiple currencies with exchange capabilities via API


URL: /baas/api/capabilities/sct09-multi-currency



# SCT09 - Multi-Currency Financial Operation

Support for operations across multiple currencies with exchange capabilities, enabling global financial services through the API.

## Overview

This capability enables your platform to operate across multiple currencies via API, providing foreign exchange services, multi-currency accounts, and international payment processing.

## Features

| Feature | Description |
|---------|-------------|
| **Multi-Currency Accounts** | Hold balances in multiple currencies |
| **Foreign Exchange** | Real-time currency conversion |
| **International Payments** | Cross-border payment processing |
| **FX Reporting** | Currency conversion reporting |
| **Exchange Rate Management** | Competitive rate sourcing |

## Configuration Options

| Level | Currencies | Features |
|-------|------------|----------|
| **Basic** | Major currencies only (8) | Standard FX rates |
| **Standard** | Extended (30+) | Competitive rates, FX reporting |
| **Advanced** | Global (100+) | Real-time FX, rate locking |

## API Usage

### Get Exchange Rate

```bash
GET /api/v1/fx/rates?from=EUR&to=USD
Authorization: Bearer {access_token}
```

**Response:**
```json
{
  "from_currency": "EUR",
  "to_currency": "USD",
  "rate": 1.0850,
  "inverse_rate": 0.9217,
  "timestamp": "2024-01-15T10:30:00Z",
  "valid_until": "2024-01-15T10:31:00Z"
}
```

### Execute Currency Conversion

```bash
POST /api/v1/fx/convert
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "source_account_id": "acc_eur_123",
  "destination_account_id": "acc_usd_456",
  "source_amount": 1000.00,
  "source_currency": "EUR",
  "destination_currency": "USD"
}
```

**Response:**
```json
{
  "conversion_id": "fx_abc789",
  "source_amount": 1000.00,
  "source_currency": "EUR",
  "destination_amount": 1085.00,
  "destination_currency": "USD",
  "rate_applied": 1.0850,
  "fee": 5.00,
  "status": "COMPLETED"
}
```

### Create Multi-Currency Account

```bash
POST /api/v1/accounts
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "customer_id": "cust_123456",
  "account_type": "MULTI_CURRENCY",
  "currencies": ["EUR", "USD", "GBP"],
  "primary_currency": "EUR"
}
```

## Supported Currencies

### Major Currencies
USD, EUR, GBP, JPY, CHF, CAD, AUD, NZD

### European Currencies
SEK, NOK, DKK, PLN, CZK, HUF, RON, BGN

### Other Currencies
AED, SAR, ZAR, BRL, MXN, SGD, HKD, and 100+ more

## Integration with Other Capabilities

| Capability | Integration |
|------------|-------------|
| **SCT03 - Country** | Available currencies per country |
| **SCT04 - Instant Payment** | Cross-currency instant transfers |
| **SCT12 - Financial Network** | International payment rails |

## Related API Reference

<Card title="FX APIs" icon="banknote" href="/baas/api/reference/financial-operations/transfers">
  View detailed FX API specifications
</Card>

## Subscription Tier Availability

| Tier | Configuration Level |
|------|---------------------|
| Starter | Not included |
| Professional | Standard |
| Enterprise | Advanced |
| Custom | Configurable |


---

# SCT12 - Financial Network Access

Connectivity to financial networks and banking systems via API


URL: /baas/api/capabilities/sct12-financial-network



# SCT12 - Financial Network Access

Connectivity to financial networks and banking systems, enabling access to payment schemes, banking networks, and correspondent relationships through the API.

## Overview

This capability provides API access to global financial infrastructure, including payment networks, banking systems, and correspondent banking relationships.

## Features

| Feature | Description |
|---------|-------------|
| **Banking Network Integration** | Connect to banking systems |
| **Payment Scheme Access** | Access to payment rails |
| **Smart Routing** | Optimal network selection |
| **Network Monitoring** | Real-time status monitoring |
| **Fallback Routing** | Alternative routing mechanisms |

## Configuration Options

| Level | Access | Features |
|-------|--------|----------|
| **Basic** | Limited networks | Single region |
| **Standard** | Regional access | Multi-network routing |
| **Advanced** | Global access | Full redundancy |

## API Usage

### Get Available Networks

```bash
GET /api/v1/networks
Authorization: Bearer {access_token}
```

**Response:**
```json
{
  "networks": [
    {
      "network_id": "SEPA",
      "name": "Single Euro Payments Area",
      "status": "OPERATIONAL",
      "settlement_time": "T+1",
      "currencies": ["EUR"],
      "countries": ["DE", "FR", "NL", "BE", "IT", "ES"]
    },
    {
      "network_id": "SEPA_INSTANT",
      "name": "SEPA Instant Credit Transfer",
      "status": "OPERATIONAL",
      "settlement_time": "INSTANT",
      "currencies": ["EUR"]
    },
    {
      "network_id": "SWIFT",
      "name": "SWIFT International",
      "status": "OPERATIONAL",
      "settlement_time": "T+1 to T+3",
      "currencies": ["*"]
    }
  ]
}
```

### Get Network Status

```bash
GET /api/v1/networks/{network_id}/status
Authorization: Bearer {access_token}
```

**Response:**
```json
{
  "network_id": "SEPA_INSTANT",
  "status": "OPERATIONAL",
  "availability": 99.95,
  "last_incident": null,
  "maintenance_windows": []
}
```

### Get Routing Options

```bash
POST /api/v1/networks/route
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "destination_country": "DE",
  "destination_type": "IBAN",
  "amount": 5000.00,
  "currency": "EUR",
  "urgency": "INSTANT"
}
```

**Response:**
```json
{
  "recommended_network": "SEPA_INSTANT",
  "alternatives": [
    {
      "network": "SEPA",
      "settlement_time": "T+1",
      "fee": 0.50
    },
    {
      "network": "SWIFT",
      "settlement_time": "T+2",
      "fee": 15.00
    }
  ]
}
```

## Supported Networks

| Network | Region | Settlement |
|---------|--------|------------|
| **SEPA** | EU/EEA | T+1 |
| **SEPA Instant** | EU/EEA | < 10 seconds |
| **Faster Payments** | UK | < 2 hours |
| **SWIFT** | Global | T+1 to T+3 |
| **SWIFT gpi** | Global | Same-day |

## Integration with Other Capabilities

| Capability | Integration |
|------------|-------------|
| **SCT03 - Country** | Network availability per country |
| **SCT04 - Instant Payment** | Instant payment rails |
| **SCT09 - Multi-Currency** | Cross-border networks |

## Related API Reference

<Card title="Network APIs" icon="network-wired" href="/baas/api/reference/financial-operations/transfers">
  View detailed network API specifications
</Card>

## Subscription Tier Availability

| Tier | Configuration Level |
|------|---------------------|
| Starter | Basic |
| Professional | Standard |
| Enterprise | Advanced |
| Custom | Configurable |


---

# SCT05 - Subscription Business Performance Management

Tools for managing subscription-based business models and recurring revenue via API


URL: /baas/api/capabilities/sct05-subscription-management



# SCT05 - Subscription Business Performance Management

Tools for managing subscription-based business models and recurring revenue, enabling automated billing and customer lifecycle management through the API.

## Overview

This capability provides API access to comprehensive tools for managing subscription-based services, from plan creation to billing automation and churn prevention.

## Features

| Feature | Description |
|---------|-------------|
| **Plan Management** | Create and manage subscription plans |
| **Recurring Billing** | Automated billing cycles |
| **Analytics & Reporting** | Subscription metrics and insights |
| **Lifecycle Management** | Customer journey automation |
| **Churn Prevention** | Predictive churn analytics |

## Configuration Options

| Level | Features | Automation |
|-------|----------|------------|
| **Basic** | Essential plan management | Manual billing |
| **Standard** | Full subscription tools | Automated billing |
| **Advanced** | AI-powered optimization | Predictive analytics |

## API Usage

### Create Subscription Plan

```bash
POST /api/v1/subscriptions/plans
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "name": "Professional Plan",
  "billing_cycle": "MONTHLY",
  "price": 49.99,
  "currency": "EUR",
  "features": ["feature_1", "feature_2", "feature_3"],
  "trial_days": 14
}
```

**Response:**
```json
{
  "plan_id": "plan_pro_001",
  "name": "Professional Plan",
  "billing_cycle": "MONTHLY",
  "price": 49.99,
  "currency": "EUR",
  "status": "ACTIVE"
}
```

### Create Customer Subscription

```bash
POST /api/v1/subscriptions
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "customer_id": "cust_123456",
  "plan_id": "plan_pro_001",
  "payment_method_id": "pm_card_789",
  "start_date": "2024-02-01"
}
```

**Response:**
```json
{
  "subscription_id": "sub_abc123",
  "customer_id": "cust_123456",
  "plan_id": "plan_pro_001",
  "status": "TRIALING",
  "trial_end": "2024-02-15",
  "next_billing_date": "2024-02-15"
}
```

### Get Subscription Metrics

```bash
GET /api/v1/subscriptions/metrics
Authorization: Bearer {access_token}
```

**Response:**
```json
{
  "mrr": 125000.00,
  "arr": 1500000.00,
  "active_subscriptions": 2500,
  "churn_rate": 2.5,
  "ltv": 850.00,
  "new_subscriptions_mtd": 150
}
```

## Webhook Events

```json
{
  "event": "subscription.renewed",
  "subscription_id": "sub_abc123",
  "plan_id": "plan_pro_001",
  "amount": 49.99,
  "next_billing_date": "2024-03-15"
}
```

## Integration with Other Capabilities

| Capability | Integration |
|------------|-------------|
| **SCT04 - Instant Payment** | Payment collection |
| **SCT06 - Decision Support** | Subscription analytics |
| **SCT10 - Closed-loop** | Wallet-based subscriptions |

## Related API Reference

<Card title="Subscription APIs" icon="repeat" href="/baas/api/reference/financial-operations">
  View detailed subscription API specifications
</Card>

## Subscription Tier Availability

| Tier | Configuration Level |
|------|---------------------|
| Starter | Not included |
| Professional | Standard |
| Enterprise | Advanced |
| Custom | Configurable |


---

# SCT06 - Decision Support System

Analytics and intelligence tools to support business decision-making via API


URL: /baas/api/capabilities/sct06-decision-support



# SCT06 - Decision Support System

Analytics and intelligence tools to support business decision-making with data visualization and predictive insights through the API.

## Overview

This capability provides API access to business intelligence dashboards, data visualization, and predictive analytics to help you make informed decisions about your financial services platform.

## Features

| Feature | Description |
|---------|-------------|
| **BI Dashboards** | Interactive business intelligence views |
| **Data Visualization** | Charts, graphs, and visual reports |
| **Predictive Analytics** | AI-powered forecasting |
| **Custom Reporting** | Build custom report templates |
| **Recommendations** | Decision recommendation engine |

## Configuration Options

| Level | Features | Analytics |
|-------|----------|-----------|
| **Basic** | Standard reports | Historical data |
| **Standard** | Interactive dashboards, custom reports | Trend analysis |
| **Advanced** | AI-powered insights | Predictive analytics |

## API Usage

### Get Dashboard Summary

```bash
GET /api/v1/analytics/dashboard
Authorization: Bearer {access_token}
```

**Response:**
```json
{
  "period": "2024-01",
  "summary": {
    "total_transactions": 125000,
    "transaction_volume": 5250000.00,
    "active_customers": 8500,
    "new_customers": 450,
    "revenue": 125000.00
  },
  "trends": {
    "transaction_growth": 12.5,
    "customer_growth": 8.2,
    "revenue_growth": 15.0
  }
}
```

### Get Custom Report

```bash
POST /api/v1/analytics/reports
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "report_type": "TRANSACTION_SUMMARY",
  "date_from": "2024-01-01",
  "date_to": "2024-01-31",
  "group_by": "DAY",
  "filters": {
    "currency": "EUR",
    "transaction_type": "TRANSFER"
  }
}
```

**Response:**
```json
{
  "report_id": "rpt_abc123",
  "data": [
    {"date": "2024-01-01", "count": 4200, "volume": 175000.00},
    {"date": "2024-01-02", "count": 4500, "volume": 185000.00}
  ],
  "totals": {
    "count": 125000,
    "volume": 5250000.00
  }
}
```

### Get Predictions (Advanced)

```bash
GET /api/v1/analytics/predictions?metric=revenue&period=3months
Authorization: Bearer {access_token}
```

**Response:**
```json
{
  "metric": "revenue",
  "predictions": [
    {"month": "2024-02", "predicted": 135000.00, "confidence": 0.85},
    {"month": "2024-03", "predicted": 142000.00, "confidence": 0.80},
    {"month": "2024-04", "predicted": 150000.00, "confidence": 0.75}
  ],
  "factors": ["seasonal_trend", "customer_growth", "market_conditions"]
}
```

## Report Types

| Type | Description |
|------|-------------|
| **TRANSACTION_SUMMARY** | Transaction volumes and counts |
| **CUSTOMER_ANALYTICS** | Customer metrics and segments |
| **REVENUE_REPORT** | Revenue breakdown and trends |
| **RISK_ASSESSMENT** | Risk metrics and alerts |

## Integration with Other Capabilities

| Capability | Integration |
|------------|-------------|
| **SCT05 - Subscriptions** | Subscription analytics |
| **SCT11 - Compliance** | Compliance dashboards |
| **All Capabilities** | Cross-capability insights |

## Related API Reference

<Card title="Analytics APIs" icon="chart-bar" href="/baas/api/reference/administration">
  View detailed analytics API specifications
</Card>

## Subscription Tier Availability

| Tier | Configuration Level |
|------|---------------------|
| Starter | Basic |
| Professional | Standard |
| Enterprise | Advanced |
| Custom | Configurable |


---

# SCT11 - Compliance Management

Tools and features to ensure regulatory compliance across operations via API


URL: /baas/api/capabilities/sct11-compliance-management



# SCT11 - Compliance Management

Tools and features to ensure regulatory compliance across operations, including KYC/AML workflows, transaction monitoring, and regulatory reporting through the API.

## Overview

This capability provides API access to comprehensive compliance management tools to help your platform meet regulatory requirements across all markets you operate in.

## Features

| Feature | Description |
|---------|-------------|
| **KYC/AML Workflows** | Customer verification processes |
| **Regulatory Reporting** | Automated regulatory reports |
| **Transaction Monitoring** | Real-time transaction screening |
| **Audit Trail** | Complete activity logging |
| **Sanctions Screening** | Global sanctions list checking |

## Configuration Options

| Level | Features | Automation |
|-------|----------|------------|
| **Basic** | Essential compliance | Manual workflows |
| **Standard** | Comprehensive management | Semi-automated |
| **Advanced** | Full automation | Regulatory updates auto-applied |

## API Usage

### Initiate KYC Verification

```bash
POST /api/v1/verification/kyc
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "customer_id": "cust_123456",
  "verification_level": "STANDARD",
  "documents": [
    {"type": "PASSPORT", "document_id": "doc_abc123"},
    {"type": "PROOF_OF_ADDRESS", "document_id": "doc_def456"}
  ]
}
```

**Response:**
```json
{
  "verification_id": "ver_xyz789",
  "customer_id": "cust_123456",
  "status": "IN_PROGRESS",
  "checks": [
    {"type": "IDENTITY", "status": "PENDING"},
    {"type": "SANCTIONS", "status": "PASSED"},
    {"type": "PEP", "status": "PASSED"}
  ]
}
```

### Screen Transaction

```bash
POST /api/v1/compliance/screen
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "transaction_id": "txn_abc123",
  "amount": 5000.00,
  "currency": "EUR",
  "sender": {"name": "John Doe", "country": "DE"},
  "recipient": {"name": "Jane Smith", "country": "GB"}
}
```

**Response:**
```json
{
  "screening_id": "scr_123456",
  "result": "PASSED",
  "risk_score": 15,
  "checks_performed": [
    {"type": "SANCTIONS", "result": "CLEAR"},
    {"type": "PEP", "result": "CLEAR"},
    {"type": "ADVERSE_MEDIA", "result": "CLEAR"}
  ]
}
```

### Get Compliance Report

```bash
GET /api/v1/compliance/reports/sar?period=2024-01
Authorization: Bearer {access_token}
```

**Response:**
```json
{
  "report_type": "SAR",
  "period": "2024-01",
  "total_alerts": 45,
  "filed_reports": 3,
  "pending_review": 12,
  "dismissed": 30
}
```

## Verification Levels

| Level | Checks Included |
|-------|-----------------|
| **BASIC** | Identity verification |
| **STANDARD** | Identity + Address + Sanctions |
| **ENHANCED** | Standard + Source of Funds + PEP |

## Webhook Events

```json
{
  "event": "verification.completed",
  "verification_id": "ver_xyz789",
  "customer_id": "cust_123456",
  "result": "APPROVED",
  "timestamp": "2024-01-15T10:30:00Z"
}
```

## Integration with Other Capabilities

| Capability | Integration |
|------------|-------------|
| **SCT03 - Country** | Country-specific compliance rules |
| **SCT04 - Payments** | Transaction screening |
| **SCT06 - Decision Support** | Compliance dashboards |

## Related API Reference

<Card title="Verification APIs" icon="shield-check" href="/baas/api/reference/verification-compliance">
  View detailed compliance API specifications
</Card>

## Subscription Tier Availability

| Tier | Configuration Level |
|------|---------------------|
| Starter | Basic |
| Professional | Standard |
| Enterprise | Advanced |
| Custom | Configurable |


---

# SCT07 - Omni Channel

Seamless experience across multiple customer touchpoints and channels via API


URL: /baas/api/capabilities/sct07-omni-channel



# SCT07 - Omni Channel

Seamless experience across multiple customer touchpoints and channels, providing unified customer data and cross-channel continuity through the API.

## Overview

This capability enables your platform to deliver a consistent and seamless customer experience across all channels with unified data and transaction continuity via API integration.

## Features

| Feature | Description |
|---------|-------------|
| **Cross-Channel Continuity** | Continue transactions across channels |
| **Unified Customer View** | Single view of customer data |
| **Channel Management** | Centralized channel control |
| **Session Handoff** | Transfer sessions between channels |
| **Multi-Device Support** | Synchronized state across devices |

## Configuration Options

| Level | Channels | Features |
|-------|----------|----------|
| **Basic** | Limited (2-3 channels) | Basic integration |
| **Standard** | Core channels | Cross-channel continuity |
| **Advanced** | All channels | Complete omnichannel experience |

## API Usage

### Get Unified Customer Profile

```bash
GET /api/v1/customers/{customer_id}/profile/unified
Authorization: Bearer {access_token}
```

**Response:**
```json
{
  "customer_id": "cust_123456",
  "profile": {
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+44123456789"
  },
  "channels": {
    "web": {"last_active": "2024-01-15T10:30:00Z", "sessions": 45},
    "mobile_ios": {"last_active": "2024-01-15T09:15:00Z", "sessions": 120},
    "mobile_android": {"last_active": "2024-01-10T14:00:00Z", "sessions": 30}
  },
  "preferences": {
    "notification_channel": "PUSH",
    "preferred_language": "en"
  }
}
```

### Create Cross-Channel Session

```bash
POST /api/v1/sessions/handoff
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "source_session_id": "sess_web_123",
  "target_channel": "MOBILE_IOS",
  "context": {
    "current_flow": "PAYMENT",
    "transaction_draft_id": "draft_abc789"
  }
}
```

**Response:**
```json
{
  "handoff_token": "ho_xyz123",
  "expires_at": "2024-01-15T10:35:00Z",
  "target_channel": "MOBILE_IOS",
  "context_preserved": true
}
```

### Resume Session on New Channel

```bash
POST /api/v1/sessions/resume
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "handoff_token": "ho_xyz123",
  "channel": "MOBILE_IOS",
  "device_id": "device_abc123"
}
```

**Response:**
```json
{
  "session_id": "sess_mobile_456",
  "customer_id": "cust_123456",
  "context": {
    "current_flow": "PAYMENT",
    "transaction_draft_id": "draft_abc789"
  },
  "handoff_complete": true
}
```

### Get Channel Activity

```bash
GET /api/v1/analytics/channels
Authorization: Bearer {access_token}
```

**Response:**
```json
{
  "channels": [
    {"channel": "WEB", "active_users": 1200, "transactions": 3500},
    {"channel": "MOBILE_IOS", "active_users": 2500, "transactions": 8200},
    {"channel": "MOBILE_ANDROID", "active_users": 1800, "transactions": 5100},
    {"channel": "API", "active_users": 150, "transactions": 25000}
  ],
  "cross_channel_journeys": 450
}
```

## Channel Types

| Channel | Description |
|---------|-------------|
| **WEB** | Browser-based access |
| **MOBILE_IOS** | iOS application |
| **MOBILE_ANDROID** | Android application |
| **API** | Direct API integration |
| **WEBHOOK** | Event notifications |

## Integration with Other Capabilities

| Capability | Integration |
|------------|-------------|
| **SCT04 - Payments** | Cross-channel payment flows |
| **SCT06 - Decision Support** | Channel analytics |
| **SCT11 - Compliance** | Channel-specific compliance |

## Related API Reference

<Card title="Session APIs" icon="arrows-rotate" href="/baas/api/integration/flows/individual-customer/session-management">
  View detailed session API specifications
</Card>

## Subscription Tier Availability

| Tier | Configuration Level |
|------|---------------------|
| Starter | Not included |
| Professional | Standard |
| Enterprise | Advanced |
| Custom | Configurable |


---

# Development Environment

Set up your development environment for FinHub integration


URL: /baas/api/development



# Development Environment

This section guides you through setting up your development environment, understanding authentication, and exploring the FinHub APIs.

## Environment Overview

FinHub provides three environments for your integration journey:

| Environment | Purpose | URL Pattern |
|-------------|---------|-------------|
| **Sandbox** | Development and testing | `*.sandbox.finhub.cloud` |
| **Integration** | Pre-production testing | `*.integration.finhub.cloud` |
| **Production** | Live operations | `*.finhub.cloud` |

## Development Journey

```mermaid
flowchart LR
    A[Sandbox] --> B[Integration]
    B --> C[Production]
    
    A1[Development & Testing] --> A
    B1[Pre-production Validation] --> B
    C1[Live Operations] --> C
```

## Getting Started

<Steps>
  <Step title="Sandbox Setup">
    Configure your sandbox environment and credentials
  </Step>
  <Step title="Authentication">
    Implement the authentication flow to get access tokens
  </Step>
  <Step title="Playground Exploration">
    Use the playground to explore and test APIs
  </Step>
  <Step title="Testing Tools">
    Set up testing tools and utilities
  </Step>
</Steps>

## Quick Start

### 1. Get Your Credentials

Ensure you have received:
- Tenant ID
- Client ID
- Client Secret
- Sandbox username and password

### 2. Authenticate

```bash
curl -X POST "https://gateway.sandbox.finhub.cloud/api/v2/auth/sandbox/token" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -d '{
    "username": "YOUR_USERNAME",
    "password": "YOUR_PASSWORD",
    "customerId": "YOUR_CLIENT_ID",
    "customerSecret": "YOUR_CLIENT_SECRET",
    "accountType": "b2b"
  }'
```

### 3. Make Your First API Call

```bash
curl -X GET "https://gateway.sandbox.finhub.cloud/api/v2/customers" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID"
```

## Development Resources

<CardGroup cols={2}>
  <Card title="Sandbox Setup" icon="flask" href="/baas/api/development/sandbox-setup">
    Configure your sandbox
  </Card>
  <Card title="Playground" icon="gamepad" href="/baas/api/development/playground">
    Explore APIs interactively
  </Card>
  <Card title="Testing Tools" icon="vial" href="/baas/api/development/testing-tools">
    Testing utilities
  </Card>
  <Card title="API Reference" icon="code" href="/baas/api/reference">
    Browse API documentation
  </Card>
</CardGroup>


---

# Sandbox Configuration and Activation

Setting up and activating your FinHub sandbox environment


URL: /baas/api/development/sandbox-setup



# Sandbox Configuration and Activation

This guide explains how to set up and activate your FinHub sandbox environment, allowing you to test and develop your integration before moving to production.

## Sandbox Overview

The FinHub sandbox is a fully functional testing environment that mimics the production environment. It allows you to:

- Test API integrations without affecting real data or transactions
- Explore API capabilities and features
- Develop and debug your integration
- Validate your implementation against FinHub requirements

## Prerequisites

Before configuring your sandbox, ensure you have:

1. Completed the registration process as a FinHub API client
2. Received your sandbox tenant credentials via email
3. Access to the FinHub Developer Portal

## Sandbox Characteristics

| Feature | Sandbox Behavior |
|---------|------------------|
| **Data** | Test data only, regularly reset |
| **Transactions** | Simulated, no real money movement |
| **KYC/KYB** | Simplified verification for testing |
| **Rate Limits** | Relaxed limits for development |
| **Notifications** | Sent to test endpoints only |
| **Payment Networks** | Simulated/test environments |

## Sandbox Configuration Steps

### Step 1: Access the Developer Portal

Log in to the [FinHub Sandbox Portal](https://sandbox.finhub.cloud) using the credentials provided during registration:

1. Navigate to `https://sandbox.finhub.cloud`
2. Enter your sandbox username and password
3. Complete any required verification

### Step 2: Create a Sandbox Tenant

1. Navigate to the "Sandbox" section in the Developer Portal
2. Click "Create New Sandbox Tenant"
3. Fill in the required information:
   - Tenant name
   - Technical contact information
   - Selected products for testing
4. Submit the form to create your sandbox tenant

### Step 3: Configure API Access

1. Once your sandbox tenant is created, navigate to the "API Access" section
2. Generate your client credentials:
   - **Client ID**: Your unique identifier for API requests
   - **Client Secret**: Your secret key (keep this secure!)
3. Note down these credentials as they will be required for authentication

<Warning>
Store your credentials securely - the Client Secret is shown only once. If lost, you'll need to regenerate it.
</Warning>

### Step 4: Configure IP Whitelisting

For security reasons, you need to whitelist the IP addresses that will access the FinHub APIs:

1. Go to the "Security" section in the Developer Portal
2. Add the IP addresses of your development and testing environments
3. Save your changes

<Note>
IP whitelisting is required for both sandbox and production environments. Ensure all development, staging, and CI/CD environments are whitelisted.
</Note>

### Step 5: Configure Webhook Endpoints (Optional)

If your integration requires webhooks:

1. Navigate to the "Webhooks" section
2. Add the URLs where FinHub should send event notifications
3. Configure the events you want to receive
4. Test the webhook connection using the "Send Test Event" feature

### Step 6: Activate Your Sandbox

After completing the configuration:

1. Go to the "Activation" section
2. Review your configuration settings
3. Click "Activate Sandbox"
4. Confirm the activation

<Info>
Your sandbox will be activated within **15 minutes**, and you'll receive a confirmation email with your sandbox details.
</Info>

## Environment Variables

Set up your development environment with these variables:

```bash
# FinHub Sandbox Configuration
FINHUB_BASE_URL=https://gateway.sandbox.finhub.cloud
FINHUB_TENANT_ID=your_tenant_id
FINHUB_CLIENT_ID=your_client_id
FINHUB_CLIENT_SECRET=your_client_secret
FINHUB_USERNAME=your_sandbox_username
FINHUB_PASSWORD=your_sandbox_password

# Webhook Configuration (Optional)
FINHUB_WEBHOOK_SECRET=your_webhook_secret
```

## Test Data

The sandbox comes pre-configured with test data for common testing scenarios:

| Data Type | Description |
|-----------|-------------|
| **Test Customers** | Pre-created individual and business customers |
| **Test Accounts** | Accounts with test balances |
| **Test Cards** | Virtual cards for testing |
| **Test IBANs** | IBANs for payment testing |
| **Test Documents** | Sample KYC documents |

### Test Card Numbers

| Card Type | Number | Use Case |
|-----------|--------|----------|
| Visa | 4111 1111 1111 1111 | Successful transactions |
| Mastercard | 5555 5555 5555 4444 | Successful transactions |
| Visa | 4000 0000 0000 0002 | Declined transactions |
| Mastercard | 5100 0000 0000 0004 | Insufficient funds |

### Test Bank Accounts

| IBAN | Bank | Use Case |
|------|------|----------|
| DE89370400440532013000 | Deutsche Bank (Test) | Successful SEPA transfers |
| GB82WEST12345698765432 | Test Bank UK | Successful UK transfers |
| FR7630006000011234567890189 | Test Bank FR | Failed transfers (test) |

## Sandbox Limitations

<Warning>
Be aware of these limitations when testing your integration.
</Warning>

- **Transaction Limits**: Lower transaction limits than production
- **Simulated Behavior**: Some features have simulated behavior
- **External Integrations**: Card networks and bank connections use test environments
- **Response Times**: May differ from production
- **Data Resets**: Data may be reset periodically (typically monthly)

## Quick Verification

```bash
# Get an access token
curl -X POST "https://gateway.sandbox.finhub.cloud/api/v2/auth/sandbox/token" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: your_tenant_id" \
  -d '{
    "username": "your_username",
    "password": "your_password",
    "customerId": "your_customer_id",
    "customerSecret": "your_customer_secret",
    "accountType": "b2c"
  }'

# Test with the received token
curl -X GET "https://gateway.sandbox.finhub.cloud/api/v2/settings/countries" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Playground" icon="gamepad" href="/baas/api/development/playground">
    Explore the API playground
  </Card>
  <Card title="Testing Tools" icon="flask" href="/baas/api/development/testing-tools">
    Learn about testing utilities
  </Card>
</CardGroup>


---

# Playground Exploration

Explore and test FinHub APIs in the interactive playground


URL: /baas/api/development/playground



# Playground Exploration

The FinHub Playground provides an interactive environment to explore APIs, test endpoints, and understand request/response patterns.

## Accessing the Playground

1. Log in to the [FinHub Sandbox Portal](https://sandbox.finhub.cloud)
2. Navigate to **API Playground**
3. Select the API you want to explore

## Playground Features

| Feature | Description |
|---------|-------------|
| **Interactive Testing** | Execute API calls directly from the browser |
| **Auto-Authentication** | Automatic token management |
| **Request Builder** | Visual request construction |
| **Response Viewer** | Formatted response display |
| **Code Generation** | Generate code snippets |

## Using the Playground

### Step 1: Select an API

Choose from available API categories:
- Customer API
- Wallet API
- Payment API
- Compliance API

### Step 2: Configure Parameters

Fill in the required parameters:
- Path parameters
- Query parameters
- Request body

### Step 3: Execute Request

Click **Send** to execute the request and view the response.

### Step 4: Review Response

Examine the response:
- Status code
- Response headers
- Response body
- Response time

## Recommended Exploration Path

<Steps>
  <Step title="Authenticate">
    Test the authentication endpoint to understand token flow
  </Step>
  <Step title="Create Customer">
    Register a test customer using the Customer API
  </Step>
  <Step title="Verify Customer">
    Complete KYC verification for the test customer
  </Step>
  <Step title="Open Account">
    Open a wallet/account for the verified customer
  </Step>
  <Step title="Make Transaction">
    Execute a test transaction
  </Step>
</Steps>

## Code Generation

The playground generates code snippets in multiple languages:

- cURL
- JavaScript (Axios/Fetch)
- Python (Requests)
- Java
- PHP

## Next Steps

<CardGroup cols={2}>
  <Card title="Testing Tools" icon="vial" href="/baas/api/development/testing-tools">
    Set up testing utilities
  </Card>
  <Card title="Core Flows" icon="diagram-project" href="/baas/api/integration/flows">
    Implement integration flows
  </Card>
</CardGroup>


---

# Testing Tools

Tools and utilities for testing your FinHub integration


URL: /baas/api/development/testing-tools



# Testing Tools

This guide covers tools and utilities available for testing your FinHub integration.

## Available Tools

### Sandbox Test Data

The sandbox includes pre-configured test data:

| Data Type | Description |
|-----------|-------------|
| **Test Customers** | Pre-created customers for testing |
| **Test Accounts** | Accounts with test balances |
| **Test Cards** | Virtual cards for testing |
| **Test IBANs** | Valid test IBANs for transfers |

### Test Utilities API

Use the Test Utilities API for sandbox-specific operations:

| Endpoint | Description |
|----------|-------------|
| `POST /test/customers/create` | Create test customer with specific state |
| `POST /test/accounts/fund` | Add funds to test account |
| `POST /test/kyc/approve` | Auto-approve KYC for testing |
| `POST /test/transactions/simulate` | Simulate incoming transactions |

## Testing Workflows

### Customer Flow Testing

```bash
# Create a test customer with pre-approved KYC
curl -X POST "/api/v2/test/customers/create" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"type": "individual", "kycStatus": "approved"}'
```

### Transaction Testing

```bash
# Simulate an incoming transfer
curl -X POST "/api/v2/test/transactions/simulate" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"type": "credit", "amount": 1000, "currency": "EUR", "accountId": "acc_123"}'
```

## Webhook Testing

### Local Development

Use tools like ngrok to expose local webhooks:

```bash
ngrok http 3000
# Use the generated URL as your webhook endpoint
```

### Webhook Simulator

Trigger webhook events from the Developer Portal:

1. Go to **Settings** > **Webhooks**
2. Click **Test Webhook**
3. Select event type
4. Click **Send Test**

## Postman Collection

Import the FinHub Postman collection for comprehensive API testing:

1. Download collection from Developer Portal
2. Import into Postman
3. Configure environment variables
4. Run pre-built test sequences

## Automated Testing

### Integration Tests

Example test structure:

```javascript
describe('Customer Registration', () => {
  it('should create individual customer', async () => {
    const response = await api.post('/customers/individual', {
      firstName: 'Test',
      lastName: 'User',
      email: 'test@example.com'
    });
    expect(response.status).toBe(201);
    expect(response.data.id).toBeDefined();
  });
});
```

## Next Steps

<Card title="Core Integration Flows" icon="diagram-project" href="/baas/api/integration/flows">
  Implement the core integration flows
</Card>


---

# Core Integration Flows

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


URL: /baas/api/integration/flows



# 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
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
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
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="banknote" 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 |


---

# Architecture

Integration architecture overview


URL: /baas/api/integration/architecture



# Integration Architecture

Overview of FinHub API integration architecture.

## Architecture Diagram

```
Your Application
       │
       ▼
   API Gateway ─────► Authentication
       │
       ▼
   FinHub APIs
   ┌─────────────────────────────┐
   │  FinCore  FinTrans  FinCard │
   │  FinCheck FinPOS   FinExE   │
   └─────────────────────────────┘
       │
       ▼
   Webhooks ──────► Your Webhook Handler
```

## Key Components

| Component | Description |
|-----------|-------------|
| **API Gateway** | Entry point, authentication |
| **Microservices** | Product-specific services |
| **Webhooks** | Event notifications |

## Integration Patterns

- **Synchronous**: Request/response
- **Asynchronous**: Webhooks for events
- **Batch**: Bulk operations

## Best Practices

- Implement retry logic
- Handle webhooks idempotently
- Use correlation IDs
- Log all transactions


---

# Individual Customer (B2C) Flow

Complete lifecycle guide for Individual customer onboarding and operations


URL: /baas/api/integration/flows/individual-customer



# Individual Customer (B2C) Flow

Complete end-to-end guide for onboarding individual (B2C) customers - from registration through to active payment operations.

## Flow Overview

The Individual Customer flow encompasses the complete customer journey from initial registration through to active wallet operations and payments. This is a **LINEAR FLOW** with strict prerequisites at each stage.

```mermaid
flowchart LR
    A[Registration] --> B[Session]
    B --> C[Verification]
    C --> D[Consents]
    D --> E[Activation]
    E --> F[Wallet Ops]
    F --> G[Payments]
    
    style A fill:#e3f2fd
    style B fill:#e3f2fd
    style C fill:#fff8e1
    style D fill:#fff8e1
    style E fill:#e8f5e9
    style F fill:#e8f5e9
    style G fill:#e8f5e9
```

## Timeline

```
Registration → Verification → Consent → Activation → Operations
   (5 min)      (1-3 days)    (5 min)   (instant)    (ongoing)
```

## Key Characteristics

| Characteristic | Description |
|----------------|-------------|
| **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 |
| **Tenant Isolation** | Complete tenant-level data isolation |

---

## The 7 Phases

<Steps>
  <Step title="Phase 1: Registration & Onboarding">
    Create customer record, user credentials, and default inactive wallet with optional categorization assignment.
    
    **Key Endpoint:** `POST /api/v2.1/customer/individual/registration`
    
    **Duration:** ~5 minutes
  </Step>
  
  <Step title="Phase 2: Session Management">
    Authenticate user and generate JWT token for subsequent API calls.
    
    **Key Endpoint:** `POST /api/v2.1/customer/individual/{customerId}/users/{userId}/sessions`
    
    **Duration:** Instant
  </Step>
  
  <Step title="Phase 3: Verification Process">
    Submit identity documents and await approval. High-risk customers require POWER_TENANT approval.
    
    **Key Endpoint:** `POST /api/v2.1/customer/individual/{customerId}/verification`
    
    **Duration:** 1-3 business days
  </Step>
  
  <Step title="Phase 4: Consent Management">
    Accept three mandatory consents: Terms & Conditions, Privacy Policy, Data Processing.
    
    **Key Endpoint:** `POST /api/v2.1/customer/individual/{customerId}/consents/{type}`
    
    **Duration:** ~5 minutes
  </Step>
  
  <Step title="Phase 5: Account Activation">
    Activate customer account, generate IBAN, and activate wallet.
    
    **Key Endpoint:** `POST /api/v2.1/customer/individual/{customerId}/activation`
    
    **Duration:** Instant
  </Step>
  
  <Step title="Phase 6: Wallet Operations">
    Query balance, check allowed operations, and view transaction limits.
    
    **Key Endpoint:** `GET /api/v2.1/fintrans/{accountId}/balance`
    
    **Duration:** Ongoing
  </Step>
  
  <Step title="Phase 7: Payment Operations">
    Add beneficiaries, prepare orders, and execute transfers.
    
    **Key Endpoint:** `POST /api/v2.1/fintrans/{accountId}/types/transfer/execute`
    
    **Duration:** Ongoing
  </Step>
</Steps>

---

## Critical Prerequisites

### For Registration
- Valid email address
- Strong password (min 8 chars, mixed case, numbers, special chars)
- Tenant access credentials

### For Verification
- Customer record created
- Valid session token

### For Activation

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

### For Operations
- Active wallet
- Valid payment consents
- Pre-registered beneficiaries

---

## Phase Navigation

<CardGroup cols={2}>
  <Card title="Phase 1: Registration" icon="user-plus" href="/baas/api/integration/flows/individual-customer/registration">
    Customer registration with categorization
  </Card>
  <Card title="Phase 2: Session Management" icon="key" href="/baas/api/integration/flows/individual-customer/session-management">
    Authentication and JWT tokens
  </Card>
  <Card title="Phase 3: Verification" icon="shield-check" href="/baas/api/integration/flows/individual-customer/verification">
    KYC verification process
  </Card>
  <Card title="Phase 4: Consent Management" icon="file-signature" href="/baas/api/integration/flows/individual-customer/consent-management">
    Mandatory consent acceptance
  </Card>
  <Card title="Phase 5: Activation" icon="check-circle" href="/baas/api/integration/flows/individual-customer/activation">
    Account activation & IBAN generation
  </Card>
  <Card title="Phase 6: Wallet Operations" icon="wallet" href="/baas/api/integration/flows/individual-customer/wallet-operations">
    Balance and allowed operations
  </Card>
  <Card title="Phase 7: Payment Operations" icon="banknote" href="/baas/api/integration/flows/individual-customer/payment-operations">
    Beneficiaries and transfers
  </Card>
</CardGroup>

---

## Quick Reference: All Endpoints

| Phase | Endpoint | Method | Description |
|-------|----------|--------|-------------|
| 1 | `/api/v2.1/customer/individual/categorization/hierarchy/{tenantId}` | GET | Get categorization options |
| 1 | `/api/v2.1/customer/individual/registration` | POST | Register customer |
| 2 | `/api/v2.1/customer/individual/{customerId}/users/{userId}/sessions` | POST | Create session (login) |
| 2 | `/api/v2.1/customer/individual/{customerId}/users/{userId}/sessions/{sessionId}` | DELETE | Delete session (logout) |
| 3 | `/api/v2.1/customer/individual/{customerId}/verification/initiate` | POST | Initiate verification |
| 3 | `/api/v2.1/customer/individual/{customerId}/verification` | POST | Submit verification |
| 3 | `/api/v2.1/verifications/{verificationId}` | GET | Check verification status |
| 4 | `/api/v2.1/customer/individual/{customerId}/consents/terms` | POST | Accept terms |
| 4 | `/api/v2.1/customer/individual/{customerId}/consents/privacy` | POST | Accept privacy |
| 4 | `/api/v2.1/customer/individual/{customerId}/consents/data-processing` | POST | Accept data processing |
| 5 | `/api/v2.1/customer/individual/{customerId}/activation` | POST | Activate customer |
| 6 | `/api/v2.1/fintrans/{accountId}/balance` | GET | Get balance |
| 6 | `/api/v2.1/fintrans/{accountId}/allowed-operations` | GET | Get allowed operations |
| 7 | `/api/v2.1/fintrans/{accountId}/beneficiaries` | POST | Add beneficiary |
| 7 | `/api/v2.1/fintrans/{accountId}/types/transfer/prepare` | POST | Prepare transfer |
| 7 | `/api/v2.1/fintrans/{accountId}/types/transfer/execute` | POST | Execute transfer |


---

# Phase 1: Registration & Onboarding

Individual customer registration with categorization and validation


URL: /baas/api/integration/flows/individual-customer/registration



# Phase 1: Registration & Onboarding

Registration is the entry point for all individual customers. This phase creates the customer record, user credentials, and default inactive wallet.

## What Gets Created

| Component | Status | Description |
|-----------|--------|-------------|
| Customer Record | `PENDING_VERIFICATION` | Core customer entity |
| User Credentials | Active | Login credentials (hashed) |
| Wallet | `INACTIVE` | Default wallet (activated later) |
| Categorization | Assigned | Feature-based category (if provided) |

---

## Step 1: Get Categorization Hierarchy

Before registration, retrieve available categories and features for smart categorization.

<Tabs>
  <Tab title="Request">
    **Endpoint:** `GET /api/v2.1/customer/individual/categorization/hierarchy/{tenantId}`

    **Headers:**
    ```http
    Authorization: Bearer {admin-jwt-token}
    X-Tenant-ID: fh_api_finsei_ltd_7f957f77
    ```
  </Tab>
  <Tab title="Response">
    **Status:** `200 OK`

    ```json
    {
      "code": 200,
      "message": "Hierarchy retrieved successfully",
      "data": {
        "tenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
        "tenantName": "Finsei Ltd",
        "complianceLevel": "ENHANCED",
        "categories": {
          "HIGH_RISK_INDIVIDUAL": {
            "databaseId": "550e8400-e29b-41d4-a716-446655440001",
            "categoryId": "HIGH_RISK_INDIVIDUAL",
            "categoryName": "High Risk Individual Customer",
            "description": "High-risk customers requiring enhanced monitoring",
            "availableFeatures": [
              {
                "featureCode": "ENHANCED_AML_MONITORING",
                "featureName": "Enhanced AML Monitoring",
                "mandatoryKeys": [
                  "riskLevel", "riskScore", "pep", 
                  "sanctionsCheck", "monitoring", "edd"
                ],
                "allowedValues": {
                  "riskLevel": ["LOW", "MEDIUM", "HIGH", "CRITICAL"],
                  "riskScore": ["0-100"],
                  "pep": ["true", "false"],
                  "pepCategory": ["DOMESTIC_PEP", "FOREIGN_PEP", "RCA", "HIO"],
                  "sanctionsCheck": ["STANDARD", "ENHANCED", "REAL_TIME"],
                  "monitoring": ["WEEKLY", "DAILY", "REAL_TIME"],
                  "edd": ["true", "false"]
                }
              }
            ]
          },
          "STANDARD_INDIVIDUAL": {
            "databaseId": "550e8400-e29b-41d4-a716-446655440010",
            "categoryId": "STANDARD_INDIVIDUAL",
            "categoryName": "Standard Individual Customer"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

---

## Step 2: Register Individual Customer

<Tabs>
  <Tab title="Request">
    **Endpoint:** `POST /api/v2.1/customer/individual/registration`

    **Headers:**
    ```http
    X-Tenant-ID: fh_api_finsei_ltd_7f957f77
    Authorization: Bearer {admin-jwt-token}
    Content-Type: application/json
    ```

    **Request Body:**
    ```json
    {
      "tenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
      "email": "john.doe@example.com",
      "password": "SecurePass123!@#",
      "matchingPassword": "SecurePass123!@#",
      "firstName": "John",
      "lastName": "Doe",
      "individualCustomer": {
        "tenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
        "email": "john.doe@example.com",
        "firstName": "John",
        "lastName": "Doe",
        "middleName": "Robert",
        "dateOfBirth": "1990-05-15",
        "placeOfBirth": "New York",
        "nationality": "US",
        "phoneNumber": "+12125551234",
        "alternatePhoneNumber": "+12125559876",
        "address": {
          "street": "123 Main Street",
          "streetNumber": "123",
          "apartment": "Apt 4B",
          "city": "New York",
          "state": "NY",
          "postalCode": "10001",
          "country": "US",
          "addressType": "RESIDENTIAL"
        },
        "occupation": "Software Engineer",
        "employerName": "Tech Corp Inc",
        "annualIncome": "150000",
        "sourceOfFunds": "SALARY",
        "categorization": {
          "id": "550e8400-e29b-41d4-a716-446655440001",
          "name": "HIGH_RISK_INDIVIDUAL",
          "isActive": true,
          "categoryFeatureRelations": [
            {
              "feature": {
                "id": "660e8400-e29b-41d4-a716-446655440002",
                "code": "ENHANCED_AML_MONITORING"
              },
              "enabled": true,
              "parametrization": [
                { "name": "riskLevel", "value": "HIGH" },
                { "name": "riskScore", "value": "85" },
                { "name": "pep", "value": "true" },
                { "name": "pepCategory", "value": "DOMESTIC_PEP" },
                { "name": "sanctionsCheck", "value": "ENHANCED" },
                { "name": "monitoring", "value": "DAILY" },
                { "name": "edd", "value": "true" }
              ]
            },
            {
              "feature": {
                "id": "770e8400-e29b-41d4-a716-446655440003",
                "code": "TRANSACTION_LIMITS"
              },
              "enabled": true,
              "parametrization": [
                { "name": "dailyLimit", "value": "5000" },
                { "name": "monthlyLimit", "value": "50000" },
                { "name": "singleTransactionLimit", "value": "2000" }
              ]
            }
          ]
        }
      }
    }
    ```
  </Tab>
  <Tab title="Success Response">
    **Status:** `201 Created`

    ```json
    {
      "code": 201,
      "message": "Account created successfully",
      "data": {
        "id": "cust-550e8400-e29b-41d4-a716-446655440010",
        "userId": "user-660e8400-e29b-41d4-a716-446655440011",
        "email": "john.doe@example.com",
        "firstName": "John",
        "lastName": "Doe",
        "status": "PENDING_VERIFICATION",
        "categorization": {
          "id": "550e8400-e29b-41d4-a716-446655440001",
          "name": "HIGH_RISK_INDIVIDUAL",
          "categoryFeatureRelations": [...]
        },
        "createdAt": "2026-01-13T10:30:00.000Z",
        "updatedAt": "2026-01-13T10:30:00.000Z"
      }
    }
    ```

    **Key IDs to Store:**
    - `id` → Customer ID (for all subsequent calls)
    - `userId` → User ID (for session creation)
  </Tab>
  <Tab title="Error Responses">
    **400 - Password Mismatch:**
    ```json
    {
      "code": 400,
      "message": "Request validation failed",
      "data": {
        "errors": [
          {
            "field": "matchingPassword",
            "message": "Password and matching password must be identical"
          }
        ]
      }
    }
    ```

    **400 - Invalid Categorization:**
    ```json
    {
      "code": 400,
      "message": "Categorization validation failed",
      "data": {
        "error": "Invalid categorization",
        "details": "Feature 'ENHANCED_AML_MONITORING' requires mandatory key 'riskLevel'",
        "missingKeys": ["riskLevel"],
        "invalidValues": {
          "monitoring": "HOURLY is not in allowed values: [WEEKLY, DAILY, REAL_TIME]"
        }
      }
    }
    ```

    **403 - Tenant Access Denied:**
    ```json
    {
      "code": 403,
      "message": "Tenant access denied or categorization not available",
      "data": {
        "error": "Tenant access denied",
        "tenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd"
      }
    }
    ```
  </Tab>
</Tabs>

---

## Business Logic

### Tenant ID Resolution

The system resolves tenant ID from the header:

```
1. Extract X-Tenant-ID header (e.g., "fh_api_finsei_ltd_7f957f77")
2. Resolve to UUID (e.g., "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd")
3. Override tenant ID in request body
```

### Password Validation Rules

| Rule | Requirement |
|------|-------------|
| Minimum Length | 8 characters |
| Uppercase | At least 1 |
| Lowercase | At least 1 |
| Numbers | At least 1 |
| Special Characters | At least 1 |
| Must Match | `matchingPassword` field |
| Cannot Contain | Username or email |

### Categorization Validation

```
1. Check if categorization provided
2. Validate category exists in tenant hierarchy
3. For each feature:
   a. Validate feature exists for tenant
   b. Check all mandatory keys provided
   c. Validate values against allowedValues
4. Store validated categorization
```

### Auto-Generated Components

| Component | Format |
|-----------|--------|
| Customer ID | UUID v4 |
| User ID | UUID v4 |
| Wallet ID | UUID v4 (inactive) |
| Email Verification Token | 64-char hex string |

---

## Smart Categorization Examples

### High-Risk Customer

**Selection Criteria:**
- PEP (Politically Exposed Person)
- High transaction volume expected
- High-risk occupation or industry
- High-risk country

**Configuration:**
```json
{
  "riskLevel": "HIGH",
  "riskScore": "85",
  "pep": "true",
  "pepCategory": "DOMESTIC_PEP",
  "sanctionsCheck": "ENHANCED",
  "monitoring": "DAILY",
  "edd": "true",
  "transactionMonitoring": "REAL_TIME"
}
```

### Standard Customer

**Configuration:**
```json
{
  "riskLevel": "MEDIUM",
  "riskScore": "45",
  "pep": "false",
  "sanctionsCheck": "STANDARD",
  "monitoring": "WEEKLY",
  "edd": "false",
  "transactionMonitoring": "BATCH_DAILY"
}
```

---

## Next Step

After successful registration, proceed to **Phase 2: Session Management** to authenticate the customer.

<Card title="Phase 2: Session Management" icon="arrow-right" href="/baas/api/integration/flows/individual-customer/session-management">
  Create customer session and obtain JWT token
</Card>


---

# Phase 2: Session Management

Authentication, JWT tokens, and session lifecycle


URL: /baas/api/integration/flows/individual-customer/session-management



# Phase 2: Session Management

Session management handles user authentication and maintains user state across API calls using JWT tokens.

## Overview

| Aspect | Details |
|--------|---------|
| **Token Type** | JWT (JSON Web Token) |
| **Algorithm** | HS256 |
| **Expiry** | 1 hour (3600 seconds) |
| **Refresh** | Via refresh token |

---

## Create Session (Login)

<Tabs>
  <Tab title="Request">
    **Endpoint:** `POST /api/v2.1/customer/individual/{customerId}/users/{userId}/sessions`

    **Path Parameters:**
    - `customerId`: Customer UUID from registration
    - `userId`: User UUID from registration

    **Request Body:**
    ```json
    {
      "username": "john.doe@example.com",
      "password": "SecurePass123!@#",
      "tenantKey": "fh_api_finsei_ltd_7f957f77",
      "tenantSecret": "your-tenant-secret-key"
    }
    ```
  </Tab>
  <Tab title="Success Response">
    **Status:** `200 OK`

    ```json
    {
      "code": 200,
      "message": "Session created successfully",
      "data": {
        "success": true,
        "sessionId": "sess-770e8400-e29b-41d4-a716-446655440020",
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "tokenType": "Bearer",
        "expiresIn": 3600,
        "userId": "user-660e8400-e29b-41d4-a716-446655440011",
        "customerId": "cust-550e8400-e29b-41d4-a716-446655440010",
        "roles": ["USER"],
        "tenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
        "sessionMetadata": {
          "clientIp": "192.168.1.100",
          "clientPlatform": "Windows",
          "userAgent": "Mozilla/5.0...",
          "createdAt": "2026-01-13T11:00:00.000Z"
        }
      }
    }
    ```
  </Tab>
  <Tab title="Error Responses">
    **401 - Invalid Credentials:**
    ```json
    {
      "code": 401,
      "message": "Authentication failed",
      "data": {
        "success": false,
        "errorType": "AUTHENTICATION",
        "message": "Invalid username or password",
        "attempts": 3,
        "maxAttempts": 5,
        "lockoutTime": null
      }
    }
    ```

    **401 - Account Locked:**
    ```json
    {
      "code": 401,
      "message": "Account locked",
      "data": {
        "success": false,
        "errorType": "AUTHENTICATION",
        "message": "Account locked due to multiple failed login attempts",
        "attempts": 5,
        "maxAttempts": 5,
        "lockoutTime": "2026-01-13T11:30:00.000Z",
        "lockoutDuration": "30 minutes"
      }
    }
    ```

    **404 - User Not Found:**
    ```json
    {
      "code": 404,
      "message": "User not found",
      "data": {
        "success": false,
        "errorType": "NOT_FOUND",
        "message": "User with username 'john.doe@example.com' not found in tenant"
      }
    }
    ```
  </Tab>
</Tabs>

---

## JWT Token Structure

### Decoded Token

```json
{
  "header": {
    "alg": "HS256",
    "typ": "JWT"
  },
  "payload": {
    "sub": "user-660e8400-e29b-41d4-a716-446655440011",
    "customerId": "cust-550e8400-e29b-41d4-a716-446655440010",
    "tenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
    "roles": ["USER"],
    "email": "john.doe@example.com",
    "sessionId": "sess-770e8400-e29b-41d4-a716-446655440020",
    "iat": 1705148400,
    "exp": 1705152000,
    "iss": "muse-proxy-bff",
    "aud": "finhub-services"
  }
}
```

### Token Claims

| Claim | Description |
|-------|-------------|
| `sub` | User ID (subject) |
| `customerId` | Customer ID |
| `tenantId` | Tenant UUID |
| `roles` | User roles array |
| `sessionId` | Session identifier |
| `iat` | Issued at timestamp |
| `exp` | Expiration timestamp |
| `iss` | Issuer |
| `aud` | Audience |

---

## Using the JWT Token

Include the token in all subsequent API calls:

```http
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

<Warning>
  **Token Expiry:** Tokens expire after 1 hour. Use the refresh token to obtain a new access token before expiry.
</Warning>

---

## Delete Session (Logout)

<Tabs>
  <Tab title="Request">
    **Endpoint:** `DELETE /api/v2.1/customer/individual/{customerId}/users/{userId}/sessions/{sessionId}`

    **Headers:**
    ```http
    Authorization: Bearer {jwt-token}
    User-Agent: Mozilla/5.0...
    ```
  </Tab>
  <Tab title="Response">
    **Status:** `200 OK`

    ```json
    {
      "code": 200,
      "message": "Session deleted successfully",
      "data": {
        "success": true,
        "sessionId": "sess-770e8400-e29b-41d4-a716-446655440020",
        "deletedAt": "2026-01-13T12:00:00.000Z"
      }
    }
    ```
  </Tab>
</Tabs>

---

## Session Security

### Lockout Policy

| Metric | Value |
|--------|-------|
| Max Failed Attempts | 5 |
| Lockout Duration | 30 minutes |
| Lockout Reset | After successful login |

### Session Metadata Captured

- Client IP address
- User agent string
- Platform information
- Creation timestamp
- Last activity timestamp

---

## Next Step

After creating a session, proceed to **Phase 3: Verification** to complete KYC verification.

<Card title="Phase 3: Verification" icon="arrow-right" href="/baas/api/integration/flows/individual-customer/verification">
  Submit identity documents for KYC verification
</Card>


---

# Phase 3: Verification Process

KYC verification, document submission, and approval workflow


URL: /baas/api/integration/flows/individual-customer/verification



# Phase 3: Verification Process

Verification is the **MOST CRITICAL** phase. Without APPROVED verification, customers CANNOT be activated.

## Verification Levels

| Level | Approver | Customer Type |
|-------|----------|---------------|
| `TENANT_VERIFIED` | Tenant Admin | Standard/Low-risk |
| `POWER_TENANT_VERIFIED` | Power Tenant (Sonnect) | High-risk |

<Warning>
  **High-risk customers** (PEP, high-risk countries, etc.) require POWER_TENANT approval which may take 1-3 business days.
</Warning>

---

## Step 1: Initiate Verification

<Tabs>
  <Tab title="Request">
    **Endpoint:** `POST /api/v2.1/customer/individual/{customerId}/verification/initiate`

    **Headers:**
    ```http
    X-Tenant-Id: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd
    Authorization: Bearer {customer-jwt-token}
    ```
  </Tab>
  <Tab title="Response">
    **Status:** `200 OK`

    ```json
    {
      "code": 200,
      "message": "Verification initiated successfully",
      "data": {
        "verificationId": "verif-880e8400-e29b-41d4-a716-446655440030",
        "customerId": "cust-550e8400-e29b-41d4-a716-446655440010",
        "status": "IN_PROGRESS",
        "level": "ENHANCED",
        "requiredDocuments": [
          "GOVERNMENT_ID",
          "PROOF_OF_ADDRESS",
          "SOURCE_OF_FUNDS",
          "PEP_DECLARATION",
          "BENEFICIAL_OWNERSHIP"
        ],
        "verificationTypes": [
          "IDENTITY_VERIFICATION",
          "DOCUMENT_VERIFICATION",
          "ENHANCED_DUE_DILIGENCE",
          "SANCTIONS_CHECK"
        ],
        "startedAt": "2026-01-13T12:00:00.000Z",
        "dueDate": "2026-01-16T12:00:00.000Z",
        "priority": "HIGH"
      }
    }
    ```
  </Tab>
</Tabs>

---

## Step 2: Submit Verification Documents

<Tabs>
  <Tab title="Request">
    **Endpoint:** `POST /api/v2.1/customer/individual/{customerId}/verification`

    **Request Body (Identity Verification):**
    ```json
    {
      "verificationType": "IDENTITY",
      "verificationData": {
        "documentType": "PASSPORT",
        "documentNumber": "AB1234567",
        "issuingCountry": "US",
        "issuingAuthority": "U.S. Department of State",
        "issueDate": "2020-01-15",
        "expiryDate": "2030-01-14",
        "selfieImage": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
        "documentFrontImage": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
        "documentBackImage": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
        "additionalData": {
          "hologramPresent": true,
          "chipPresent": true,
          "biometricData": true
        }
      }
    }
    ```
  </Tab>
  <Tab title="Response">
    **Status:** `200 OK`

    ```json
    {
      "code": 200,
      "message": "Verification submitted successfully",
      "data": {
        "verificationId": "verif-880e8400-e29b-41d4-a716-446655440030",
        "status": "PENDING_REVIEW",
        "submittedAt": "2026-01-13T12:30:00.000Z",
        "reviewedBy": null,
        "approvalRequired": "POWER_TENANT",
        "estimatedReviewTime": "1-3 business days",
        "nextSteps": [
          "Wait for power tenant review",
          "You will be notified via email when review is complete",
          "Additional documents may be requested if needed"
        ]
      }
    }
    ```
  </Tab>
</Tabs>

---

## Document Types

### Required Documents by Verification Level

| Verification Type | Required Documents |
|-------------------|-------------------|
| `IDENTITY_VERIFICATION` | PASSPORT or GOVERNMENT_ID |
| `DOCUMENT_VERIFICATION` | PROOF_OF_ADDRESS |
| `ENHANCED_DUE_DILIGENCE` | SOURCE_OF_FUNDS, BENEFICIAL_OWNERSHIP, PEP_DECLARATION |
| `SANCTIONS_CHECK` | All above documents |

### Document Specifications

| Document Type | Accepted Formats | Max Size |
|---------------|------------------|----------|
| PASSPORT | PDF, JPEG, PNG | 5 MB |
| GOVERNMENT_ID | PDF, JPEG, PNG | 5 MB |
| PROOF_OF_ADDRESS | PDF, JPEG | 5 MB |
| SOURCE_OF_FUNDS | PDF | 10 MB |
| PEP_DECLARATION | PDF | 5 MB |

---

## Step 3: Check Verification Status

<Tabs>
  <Tab title="Request">
    **Endpoint:** `GET /api/v2.1/verifications/{verificationId}`

    **Headers:**
    ```http
    Authorization: Bearer {jwt-token}
    ```
  </Tab>
  <Tab title="Response - Approved">
    **Status:** `200 OK`

    ```json
    {
      "code": 200,
      "message": "Verification status retrieved successfully",
      "data": {
        "verificationId": "verif-880e8400-e29b-41d4-a716-446655440030",
        "customerId": "cust-550e8400-e29b-41d4-a716-446655440010",
        "status": "APPROVED",
        "type": "IDENTITY_VERIFICATION",
        "level": "POWER_TENANT_VERIFIED",
        "startedAt": "2026-01-13T12:00:00.000Z",
        "submittedAt": "2026-01-13T12:30:00.000Z",
        "reviewedAt": "2026-01-14T10:00:00.000Z",
        "approvedAt": "2026-01-14T10:00:00.000Z",
        "reviewedBy": "power-tenant-admin-id",
        "completedAt": "2026-01-14T10:00:00.000Z",
        "expiresAt": "2027-01-14T10:00:00.000Z",
        "submittedDocuments": 5,
        "reviewNotes": "All documents verified. Customer identity confirmed.",
        "verificationHistory": [
          {
            "status": "INITIATED",
            "timestamp": "2026-01-13T12:00:00.000Z",
            "actor": "system"
          },
          {
            "status": "IN_PROGRESS",
            "timestamp": "2026-01-13T12:00:00.000Z",
            "actor": "customer"
          },
          {
            "status": "PENDING_REVIEW",
            "timestamp": "2026-01-13T12:30:00.000Z",
            "actor": "customer"
          },
          {
            "status": "UNDER_REVIEW",
            "timestamp": "2026-01-14T09:30:00.000Z",
            "actor": "power-tenant-admin"
          },
          {
            "status": "APPROVED",
            "timestamp": "2026-01-14T10:00:00.000Z",
            "actor": "power-tenant-admin"
          }
        ]
      }
    }
    ```
  </Tab>
  <Tab title="Response - Pending">
    ```json
    {
      "code": 200,
      "message": "Verification status retrieved successfully",
      "data": {
        "verificationId": "verif-880e8400-e29b-41d4-a716-446655440030",
        "status": "PENDING_REVIEW",
        "estimatedCompletionTime": "1-2 business days",
        "submittedDocuments": 5,
        "requiredDocuments": 5
      }
    }
    ```
  </Tab>
</Tabs>

---

## Verification Status Flow

```mermaid
flowchart LR
    A[INITIATED] --> B[IN_PROGRESS]
    B --> C[PENDING_REVIEW]
    C --> D[UNDER_REVIEW]
    D --> E{Decision}
    E -->|Approved| F[APPROVED]
    E -->|Rejected| G[REJECTED]
    E -->|More Info| H[ADDITIONAL_INFO_REQUIRED]
    H --> B
```

### Status Descriptions

| Status | Description |
|--------|-------------|
| `INITIATED` | Verification process started |
| `IN_PROGRESS` | Customer submitting documents |
| `PENDING_REVIEW` | All documents submitted, awaiting review |
| `UNDER_REVIEW` | Admin reviewing documents |
| `APPROVED` | Verification approved ✅ |
| `REJECTED` | Verification rejected ❌ |
| `ADDITIONAL_INFO_REQUIRED` | More documents needed |

---

## Verification Approval (Admin)

<Tabs>
  <Tab title="Request">
    **Endpoint:** `POST /api/v2.1/verifications/{verificationId}/approve`

    **Headers:**
    ```http
    Authorization: Bearer {admin-jwt-token}
    X-User-ID: admin-user-id
    X-User-Roles: COMPLIANCE_OFFICER
    ```

    **Request Body:**
    ```json
    {
      "adminNotes": "All documents verified. Customer identity confirmed.",
      "approvedBy": "ADMIN_USER",
      "approvalReason": "All documents verified for individual customer"
    }
    ```
  </Tab>
  <Tab title="Response">
    **Status:** `200 OK`

    ```json
    {
      "code": 200,
      "message": "Verification approved successfully",
      "data": {
        "level": "TENANT_VERIFIED",
        "approvedBy": "admin-user",
        "approvedAt": "2026-01-14T10:00:00.000Z",
        "verificationId": "verif-880e8400-e29b-41d4-a716-446655440030",
        "status": "APPROVED"
      }
    }
    ```
  </Tab>
</Tabs>

---

## Next Step

After verification is APPROVED, proceed to **Phase 4: Consent Management**.

<Card title="Phase 4: Consent Management" icon="arrow-right" href="/baas/api/integration/flows/individual-customer/consent-management">
  Accept mandatory consents before activation
</Card>


---

# Phase 4: Consent Management

Accept mandatory consents before account activation


URL: /baas/api/integration/flows/individual-customer/consent-management



# Phase 4: Consent Management

Three mandatory consents must be accepted before account activation can proceed.

## Required Consents

| Consent Type | Required | Description |
|--------------|----------|-------------|
| `TERMS_AND_CONDITIONS` | ✅ Yes | Platform terms of service |
| `PRIVACY_POLICY` | ✅ Yes | Data privacy policy |
| `DATA_PROCESSING` | ✅ Yes | Data processing agreement |

<Warning>
  **All three consents must be ACCEPTED** before activation can proceed. Missing consents will block activation.
</Warning>

---

## Accept Terms and Conditions

<Tabs>
  <Tab title="Request">
    **Endpoint:** `POST /api/v2.1/customer/individual/{customerId}/consents/terms`

    **Headers:**
    ```http
    Authorization: Bearer {jwt-token}
    User-Agent: Mozilla/5.0...
    ```

    **Request Body:**
    ```json
    {
      "accepted": true,
      "version": "1.0",
      "acceptanceTimestamp": "2026-01-14T11:00:00.000Z"
    }
    ```
  </Tab>
  <Tab title="Response">
    **Status:** `200 OK`

    ```json
    {
      "code": 200,
      "message": "Terms and conditions accepted successfully",
      "data": {
        "id": "consent-990e8400-e29b-41d4-a716-446655440040",
        "customerId": "cust-550e8400-e29b-41d4-a716-446655440010",
        "tenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
        "consentType": "TERMS_AND_CONDITIONS",
        "status": "ACCEPTED",
        "version": "1.0",
        "grantedAt": "2026-01-14T11:00:00.000Z",
        "expiresAt": "2027-01-14T11:00:00.000Z",
        "ipAddress": "192.168.1.100",
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)...",
        "metadata": {
          "acceptanceMethod": "WEB_UI",
          "documentUrl": "https://finhub.com/terms/v1.0",
          "language": "en-US"
        }
      }
    }
    ```
  </Tab>
</Tabs>

---

## Accept Privacy Policy

<Tabs>
  <Tab title="Request">
    **Endpoint:** `POST /api/v2.1/customer/individual/{customerId}/consents/privacy`

    **Request Body:**
    ```json
    {
      "accepted": true,
      "version": "1.0",
      "acceptanceTimestamp": "2026-01-14T11:01:00.000Z"
    }
    ```
  </Tab>
  <Tab title="Response">
    **Status:** `200 OK`

    ```json
    {
      "code": 200,
      "message": "Privacy policy accepted successfully",
      "data": {
        "id": "consent-990e8400-e29b-41d4-a716-446655440041",
        "consentType": "PRIVACY_POLICY",
        "status": "ACCEPTED",
        "version": "1.0",
        "grantedAt": "2026-01-14T11:01:00.000Z",
        "expiresAt": "2027-01-14T11:01:00.000Z"
      }
    }
    ```
  </Tab>
</Tabs>

---

## Accept Data Processing Agreement

<Tabs>
  <Tab title="Request">
    **Endpoint:** `POST /api/v2.1/customer/individual/{customerId}/consents/data-processing`

    **Request Body:**
    ```json
    {
      "accepted": true,
      "version": "1.0",
      "acceptanceTimestamp": "2026-01-14T11:02:00.000Z"
    }
    ```
  </Tab>
  <Tab title="Response">
    **Status:** `200 OK`

    ```json
    {
      "code": 200,
      "message": "Data processing agreement accepted successfully",
      "data": {
        "id": "consent-990e8400-e29b-41d4-a716-446655440042",
        "consentType": "DATA_PROCESSING",
        "status": "ACCEPTED",
        "version": "1.0",
        "grantedAt": "2026-01-14T11:02:00.000Z",
        "expiresAt": "2027-01-14T11:02:00.000Z"
      }
    }
    ```
  </Tab>
</Tabs>

---

## Consent Response Fields

| Field | Description |
|-------|-------------|
| `id` | Unique consent record ID |
| `consentType` | Type of consent |
| `status` | `ACCEPTED` or `PENDING` |
| `version` | Consent document version |
| `grantedAt` | Timestamp of acceptance |
| `expiresAt` | Consent expiry (typically 1 year) |
| `ipAddress` | IP address at time of acceptance |
| `userAgent` | Browser/client information |

---

## Consent Metadata Captured

For audit and compliance purposes, the following is recorded:

| Data Point | Example |
|------------|---------|
| **IP Address** | 192.168.1.100 |
| **User Agent** | Mozilla/5.0 (Windows NT 10.0; Win64; x64)... |
| **Acceptance Method** | WEB_UI, MOBILE_APP, API |
| **Document URL** | https://finhub.com/terms/v1.0 |
| **Language** | en-US |
| **Timestamp** | 2026-01-14T11:00:00.000Z |

---

## Check Consent Status

Before activation, verify all consents are in place:

```javascript
async function checkActivationReadiness(customerId, tenantId) {
  const required = ['TERMS_AND_CONDITIONS', 'PRIVACY_POLICY', 'DATA_PROCESSING'];
  const missing = [];
  
  for (const type of required) {
    const hasConsent = await checkConsent(customerId, tenantId, type);
    if (!hasConsent) {
      missing.push(type);
    }
  }
  
  return {
    ready: missing.length === 0,
    missing: missing
  };
}
```

---

## B2C vs B2B Consent Differences

<Info>
  **Individual consents** only require `accepted: true`. Organization consents require additional fields:
  - `acceptedBy` (user ID)
  - `acceptedDate` (timestamp)
</Info>

| Field | Individual (B2C) | Organization (B2B) |
|-------|------------------|-------------------|
| `accepted` | Required | Required |
| `acceptedBy` | Not required | Required |
| `acceptedDate` | Not required | Required |

---

## Next Step

After all consents are accepted, proceed to **Phase 5: Account Activation**.

<Card title="Phase 5: Activation" icon="arrow-right" href="/baas/api/integration/flows/individual-customer/activation">
  Activate account and generate IBAN
</Card>


---

# Phase 5: Account Activation

Activate customer account, generate IBAN, and enable wallet


URL: /baas/api/integration/flows/individual-customer/activation



# Phase 5: Account Activation

Activation is the final step before the customer can perform financial operations. This phase generates the IBAN and activates the wallet.

## Prerequisites Checklist

<Warning>
  **ALL prerequisites must be met before activation:**
</Warning>

| Prerequisite | Required Status | Check |
|--------------|-----------------|-------|
| Verification | `APPROVED` | ✅ |
| Terms & Conditions | `ACCEPTED` | ✅ |
| Privacy Policy | `ACCEPTED` | ✅ |
| Data Processing | `ACCEPTED` | ✅ |
| Customer Status | Not `ACTIVE` | ✅ |

---

## Check Activation Readiness

Before attempting activation, verify all prerequisites are met.

<Tabs>
  <Tab title="Request">
    **Endpoint:** `GET /api/v2.1/customer/individual/{customerId}/owner/{tenantId}/activation/check`

    **Headers:**
    ```http
    Authorization: Bearer {jwt-token}
    ```
  </Tab>
  <Tab title="Response - Ready">
    **Status:** `200 OK`

    ```json
    {
      "code": 200,
      "message": "Activation check completed",
      "data": {
        "activationAllowed": true,
        "consentOk": true,
        "verificationOk": true,
        "powerTenantApprovalOk": true,
        "powerTenantApprovalRequired": false,
        "riskLevel": "LOW",
        "isHighRisk": false,
        "customerId": "cust-550e8400-e29b-41d4-a716-446655440010",
        "powerTenant": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
        "ownerTenant": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd"
      }
    }
    ```
  </Tab>
  <Tab title="Response - Not Ready">
    ```json
    {
      "code": 200,
      "message": "Activation check completed",
      "data": {
        "activationAllowed": false,
        "consentOk": false,
        "verificationOk": true,
        "riskLevel": "LOW",
        "customerId": "cust-550e8400-e29b-41d4-a716-446655440010",
        "missingConsents": ["PRIVACY_POLICY", "DATA_PROCESSING"]
      }
    }
    ```
  </Tab>
</Tabs>

---

## Activate Customer Account

<Tabs>
  <Tab title="Request">
    **Endpoint:** `POST /api/v2.1/customer/individual/{customerId}/activation`

    **Headers:**
    ```http
    Authorization: Bearer {admin-jwt-token}
    ```

    **Request Body:**
    ```json
    {
      "activationReason": "All verification and consents completed successfully",
      "activatedBy": "admin-user-id"
    }
    ```
  </Tab>
  <Tab title="Success Response">
    **Status:** `200 OK`

    ```json
    {
      "code": 200,
      "message": "Customer activated successfully",
      "data": {
        "activationStatus": "ACTIVATED",
        "customerId": "cust-550e8400-e29b-41d4-a716-446655440010",
        "iban": "FR7630001007941234567890185",
        "bic": "SOGEFRPP",
        "activatedAt": "2026-01-14T14:00:00.000Z",
        "wallet": {
          "walletId": "wallet-aa0e8400-e29b-41d4-a716-446655440050",
          "id": "wallet-aa0e8400-e29b-41d4-a716-446655440050",
          "iban": "FR7630001007941234567890185",
          "bic": "SOGEFRPP",
          "currency": "EUR",
          "balance": "0.00",
          "reservedBalance": "0.00",
          "status": "ACTIVE",
          "asset": {
            "assetId": "asset-bb0e8400-e29b-41d4-a716-446655440051",
            "assetType": "FIAT",
            "currency": "EUR",
            "currentBalance": "0.00",
            "availableBalance": "0.00",
            "blockedBalance": "0.00",
            "lastUpdated": "2026-01-14T14:00:00.000Z"
          },
          "createdAt": "2026-01-13T10:30:00.000Z",
          "activatedAt": "2026-01-14T14:00:00.000Z"
        }
      }
    }
    ```
  </Tab>
  <Tab title="Error - Missing Consents">
    **Status:** `400 Bad Request`

    ```json
    {
      "code": 400,
      "message": "Missing required consents",
      "data": {
        "activationStatus": "CONSENT_REQUIRED",
        "customerId": "cust-550e8400-e29b-41d4-a716-446655440010",
        "missingConsentTypes": ["PRIVACY_POLICY", "DATA_PROCESSING"],
        "missingConsentDetails": {
          "PRIVACY_POLICY": {
            "consentType": "PRIVACY_POLICY",
            "title": "Privacy Policy and Data Protection",
            "required": true,
            "status": "MISSING",
            "reason": "Customer has not provided active consent",
            "acceptUrl": "/api/v2.1/customer/individual/{customerId}/consents/privacy"
          },
          "DATA_PROCESSING": {
            "consentType": "DATA_PROCESSING",
            "title": "Data Processing Agreement",
            "required": true,
            "status": "MISSING",
            "acceptUrl": "/api/v2.1/customer/individual/{customerId}/consents/data-processing"
          }
        },
        "totalRequiredConsents": 3,
        "totalMissingConsents": 2,
        "nextSteps": [
          "Accept Privacy Policy",
          "Accept Data Processing Agreement",
          "Retry activation"
        ]
      }
    }
    ```
  </Tab>
  <Tab title="Error - Not Verified">
    **Status:** `422 Unprocessable Entity`

    ```json
    {
      "code": 422,
      "message": "Customer not verified",
      "data": {
        "activationStatus": "VERIFICATION_REQUIRED",
        "customerId": "cust-550e8400-e29b-41d4-a716-446655440010",
        "verificationStatus": "PENDING_REVIEW",
        "reason": "Customer verification must be APPROVED before activation",
        "currentVerificationId": "verif-880e8400-e29b-41d4-a716-446655440030",
        "verificationStatusUrl": "/api/v2.1/verifications/{verificationId}",
        "estimatedCompletionTime": "1-2 business days"
      }
    }
    ```
  </Tab>
</Tabs>

---

## What Happens During Activation

```mermaid
flowchart TD
    A[Activation Request] --> B{Check Prerequisites}
    B -->|All Met| C[Generate IBAN]
    B -->|Missing| D[Return Error]
    C --> E[Activate Wallet]
    E --> F[Update Customer Status]
    F --> G[Publish Events]
    G --> H[Return Success]
    
    style C fill:#e8f5e9
    style E fill:#e8f5e9
    style F fill:#e8f5e9
```

### Activation Steps

1. **Validate Prerequisites** - Check verification and consents
2. **Generate IBAN** - Create unique IBAN for customer
3. **Activate Wallet** - Change wallet status from INACTIVE to ACTIVE
4. **Update Status** - Set customer status to ACTIVE
5. **Publish Events** - CustomerActivated, WalletActivated (Kafka)
6. **Send Notifications** - Email confirmation to customer

---

## Key IDs Created

| Field | Example Value | Description |
|-------|---------------|-------------|
| `iban` | FR7630001007941234567890185 | Customer's IBAN for payments |
| `bic` | SOGEFRPP | Bank Identifier Code |
| `walletId` | wallet-aa0e8400... | Wallet identifier for transactions |

---

## IBAN Format

```
FR76 + [Bank Code] + [Account Number] + [Check Digits]
     └─── Country Code (France)
```

---

## Next Step

After activation, proceed to **Phase 6: Wallet Operations** to manage the customer's wallet.

<Card title="Phase 6: Wallet Operations" icon="arrow-right" href="/baas/api/integration/flows/individual-customer/wallet-operations">
  Query balance and allowed operations
</Card>


---

# Phase 6: Wallet Operations

Query balance, check allowed operations, and view transaction limits


URL: /baas/api/integration/flows/individual-customer/wallet-operations



# Phase 6: Wallet Operations

After activation, the customer can query their wallet balance, check allowed operations, and view transaction limits.

## Prerequisites

| Requirement | Status |
|-------------|--------|
| Customer Status | `ACTIVE` |
| Wallet Status | `ACTIVE` |
| Valid Session | JWT token |

---

## Get Wallet Balance

<Tabs>
  <Tab title="Request">
    **Endpoint:** `GET /api/v2.1/fintrans/{accountId}/balance`

    **Path Parameters:**
    - `accountId`: Wallet ID from activation response

    **Headers:**
    ```http
    Authorization: Bearer {jwt-token}
    ```
  </Tab>
  <Tab title="Response">
    **Status:** `200 OK`

    ```json
    {
      "code": 200,
      "message": "Balance retrieved successfully",
      "data": {
        "walletId": "wallet-aa0e8400-e29b-41d4-a716-446655440050",
        "iban": "FR7630001007941234567890185",
        "currency": "EUR",
        "status": "ACTIVE",
        "currentBalance": "500000",
        "currentBalanceFormatted": "5000.00",
        "availableBalance": "450000",
        "availableBalanceFormatted": "4500.00",
        "blockedBalance": "50000",
        "blockedBalanceFormatted": "500.00",
        "lastTransaction": "2026-01-14T15:30:00.000Z",
        "balanceHistory": [
          {
            "date": "2026-01-14",
            "balance": "5000.00"
          }
        ]
      }
    }
    ```
  </Tab>
</Tabs>

### Balance Fields

| Field | Description |
|-------|-------------|
| `currentBalance` | Total balance in minor units (cents) |
| `currentBalanceFormatted` | Formatted balance with currency |
| `availableBalance` | Balance available for transactions |
| `blockedBalance` | Balance blocked for pending transactions |

<Info>
  **Balance Format:** Balances are returned in minor units (cents). Divide by 100 for the actual amount. Example: `500000` = €5000.00
</Info>

---

## Get Allowed Operations

<Tabs>
  <Tab title="Request">
    **Endpoint:** `GET /api/v2.1/fintrans/{accountId}/allowed-operations`

    **Query Parameters:**
    - `includeBeneficiaries`: true/false
    - `includeConsents`: true/false

    **Headers:**
    ```http
    Authorization: Bearer {jwt-token}
    ```
  </Tab>
  <Tab title="Response">
    **Status:** `200 OK`

    ```json
    {
      "code": 200,
      "message": "Allowed operations retrieved successfully",
      "data": {
        "accountId": "wallet-aa0e8400-e29b-41d4-a716-446655440050",
        "operations": [
          {
            "operationType": "TRANSFER",
            "allowedNetworks": ["SEPA", "SWIFT"],
            "requiresConsent": true,
            "requiresApproval": false,
            "enabled": true
          },
          {
            "operationType": "PAYMENT",
            "allowedNetworks": ["SEPA"],
            "requiresConsent": true,
            "requiresApproval": false,
            "enabled": true
          },
          {
            "operationType": "TOPUP",
            "allowedNetworks": ["SEPA"],
            "requiresConsent": false,
            "requiresApproval": false,
            "enabled": true
          }
        ],
        "limits": {
          "perTxn": {
            "EUR": 2000
          },
          "daily": {
            "EUR": 5000
          },
          "monthly": {
            "EUR": 50000
          }
        },
        "accountLimits": {
          "dailyTransactionLimit": 5000,
          "monthlyTransactionLimit": 50000,
          "singleTransactionLimit": 2000,
          "currency": "EUR",
          "limitType": "CATEGORY_BASED",
          "categoryName": "HIGH_RISK_INDIVIDUAL"
        },
        "consentStatus": {
          "hasValidPaymentConsent": true,
          "hasRecurringPaymentConsent": false,
          "hasPreApprovalConsent": false,
          "hasInternationalTransferConsent": true,
          "missingConsents": [],
          "allRequiredConsentsValid": true,
          "lastUpdated": "2026-01-14T14:00:00.000Z"
        },
        "enabledFeatures": [
          "TRANSFER",
          "PAYMENT",
          "INTERNATIONAL",
          "SCHEDULED_PAYMENT"
        ],
        "beneficiaries": [],
        "beneficiaryRules": [
          {
            "ruleType": "ALLOWED_TYPES",
            "allowedValues": ["INTERNAL", "SEPA", "SWIFT"],
            "description": "Allowed beneficiary types"
          },
          {
            "ruleType": "REQUIRE_PRE_REGISTRATION",
            "value": true,
            "description": "Beneficiaries must be pre-registered"
          }
        ]
      }
    }
    ```
  </Tab>
</Tabs>

---

## Operation Types

| Operation | Description | Networks |
|-----------|-------------|----------|
| `TRANSFER` | Send money to beneficiary | SEPA, SWIFT |
| `PAYMENT` | Make a payment | SEPA |
| `TOPUP` | Add funds to wallet | SEPA |

---

## Transaction Limits

Limits are determined by customer categorization:

### High-Risk Individual

| Limit Type | Amount (EUR) |
|------------|--------------|
| Per Transaction | 2,000 |
| Daily | 5,000 |
| Monthly | 50,000 |

### Standard Individual

| Limit Type | Amount (EUR) |
|------------|--------------|
| Per Transaction | 5,000 |
| Daily | 10,000 |
| Monthly | 100,000 |

<Warning>
  Limits are enforced at transaction time. Exceeding limits will result in transaction rejection.
</Warning>

---

## Consent Status

The `consentStatus` object indicates which payment consents are in place:

| Field | Description |
|-------|-------------|
| `hasValidPaymentConsent` | Basic payment consent active |
| `hasRecurringPaymentConsent` | Recurring payments enabled |
| `hasPreApprovalConsent` | Pre-approved payments enabled |
| `hasInternationalTransferConsent` | International transfers enabled |
| `allRequiredConsentsValid` | All required consents are active |

---

## Get Transaction History

<Tabs>
  <Tab title="Request">
    **Endpoint:** `GET /api/v2.1/fintrans/{accountId}/orders`

    **Query Parameters:**
    - `page`: Page number (default: 0)
    - `size`: Page size (default: 20)
    - `status`: Filter by status
    - `fromDate`: Start date filter
    - `toDate`: End date filter

    **Headers:**
    ```http
    Authorization: Bearer {jwt-token}
    ```
  </Tab>
  <Tab title="Response">
    **Status:** `200 OK`

    ```json
    {
      "code": 200,
      "message": "Orders retrieved successfully",
      "data": {
        "content": [
          {
            "orderId": "order-ff0e8400-e29b-41d4-a716-446655440081",
            "operationType": "TRANSFER",
            "status": "COMPLETED",
            "amount": "100000",
            "amountFormatted": "1000.00",
            "currency": "EUR",
            "beneficiaryName": "Jane Smith",
            "beneficiaryIban": "GB82WEST12345698765432",
            "reference": "FAM-2026-001",
            "createdAt": "2026-01-14T15:45:00.000Z",
            "executedAt": "2026-01-14T15:45:30.000Z"
          }
        ],
        "page": 0,
        "size": 20,
        "totalElements": 1,
        "totalPages": 1
      }
    }
    ```
  </Tab>
</Tabs>

---

## Next Step

Proceed to **Phase 7: Payment Operations** to add beneficiaries and execute transfers.

<Card title="Phase 7: Payment Operations" icon="arrow-right" href="/baas/api/integration/flows/individual-customer/payment-operations">
  Add beneficiaries and execute transfers
</Card>


---

# Phase 7: Payment Operations

Add beneficiaries, prepare orders, and execute transfers


URL: /baas/api/integration/flows/individual-customer/payment-operations



# Phase 7: Payment Operations

The final phase covers payment operations: adding beneficiaries, preparing orders, and executing transfers.

## Payment Flow

```mermaid
flowchart LR
    A[Add Beneficiary] --> B[Prepare Order]
    B --> C[Execute Order]
    C --> D[Monitor Status]
    
    style A fill:#e3f2fd
    style B fill:#fff8e1
    style C fill:#e8f5e9
    style D fill:#e8f5e9
```

---

## Step 1: Add Beneficiary

Beneficiaries must be pre-registered before making transfers.

<Tabs>
  <Tab title="Request">
    **Endpoint:** `POST /api/v2.1/fintrans/{accountId}/beneficiaries`

    **Headers:**
    ```http
    Authorization: Bearer {jwt-token}
    Content-Type: application/json
    ```

    **Request Body:**
    ```json
    {
      "partyType": "INDIVIDUAL_CUSTOMER",
      "firstName": "Jane",
      "lastName": "Smith",
      "iban": "GB82WEST12345698765432",
      "currency": "EUR",
      "country": "GB",
      "email": "jane.smith@example.com",
      "phoneNumber": "+442071234567",
      "shortName": "Jane S",
      "bicSwiftCode": "WESTGB21",
      "networkName": "SEPA",
      "bankName": "Westminster Bank",
      "bankAddress": "London, UK",
      "purposeCode": "FAMILY_SUPPORT"
    }
    ```
  </Tab>
  <Tab title="Response">
    **Status:** `201 Created`

    ```json
    {
      "code": 201,
      "message": "Beneficiary created successfully",
      "data": {
        "beneficiaryId": "benef-cc0e8400-e29b-41d4-a716-446655440060",
        "accountId": "wallet-aa0e8400-e29b-41d4-a716-446655440050",
        "partyType": "INDIVIDUAL_CUSTOMER",
        "beneficiaryName": "Jane Smith",
        "iban": "GB82WEST12345698765432",
        "bic": "WESTGB21",
        "bicType": "external",
        "currency": "EUR",
        "country": "GB",
        "networkName": "SEPA",
        "pepCheckResult": "VERIFIED",
        "status": "active",
        "createdAt": "2026-01-14T15:00:00.000Z"
      }
    }
    ```
  </Tab>
</Tabs>

### Beneficiary Party Types

| Party Type | Description |
|------------|-------------|
| `INDIVIDUAL_CUSTOMER` | Personal beneficiary |
| `BUSINESS_CUSTOMER` | Business beneficiary |

### PEP Check Results

| Result | Description |
|--------|-------------|
| `VERIFIED` | PEP check passed |
| `PENDING` | PEP check in progress |
| `FLAGGED` | Requires additional review |

---

## Step 2: List Beneficiaries

<Tabs>
  <Tab title="Request">
    **Endpoint:** `GET /api/v2.1/fintrans/{accountId}/beneficiaries`

    **Headers:**
    ```http
    Authorization: Bearer {jwt-token}
    ```
  </Tab>
  <Tab title="Response">
    **Status:** `200 OK`

    ```json
    {
      "code": 200,
      "message": "Beneficiaries retrieved successfully",
      "data": [
        {
          "beneficiaryId": "benef-cc0e8400-e29b-41d4-a716-446655440060",
          "beneficiaryName": "Jane Smith",
          "iban": "GB82WEST12345698765432",
          "network": "SEPA",
          "status": "active",
          "lastUsed": null
        }
      ]
    }
    ```
  </Tab>
</Tabs>

---

## Step 3: Prepare Transfer Order

<Tabs>
  <Tab title="Request">
    **Endpoint:** `POST /api/v2.1/fintrans/{accountId}/types/transfer/prepare`

    **Request Body:**
    ```json
    {
      "sourceAccount": {
        "walletId": "wallet-aa0e8400-e29b-41d4-a716-446655440050",
        "iban": "FR7630001007941234567890185"
      },
      "targetAccount": {
        "iban": "GB82WEST12345698765432",
        "beneficiaryName": "Jane Smith",
        "bic": "WESTGB21"
      },
      "amount": {
        "value": "100000",
        "currency": "EUR"
      },
      "description": "Family support payment",
      "reference": "FAM-2026-001"
    }
    ```
  </Tab>
  <Tab title="Response">
    **Status:** `200 OK`

    ```json
    {
      "code": 200,
      "message": "Order prepared successfully",
      "data": {
        "preparedOrderId": "prep-dd0e8400-e29b-41d4-a716-446655440070",
        "operationType": "TRANSFER",
        "status": "PREPARED",
        "amount": {
          "value": "100000",
          "valueFormatted": "1000.00",
          "currency": "EUR"
        },
        "fees": {
          "value": "150",
          "valueFormatted": "1.50",
          "currency": "EUR"
        },
        "totalAmount": {
          "value": "100150",
          "valueFormatted": "1001.50",
          "currency": "EUR"
        },
        "estimatedExecutionTime": "2026-01-14T16:00:00.000Z",
        "validUntil": "2026-01-14T18:00:00.000Z",
        "warnings": [],
        "requiredApprovals": []
      }
    }
    ```
  </Tab>
</Tabs>

### Prepared Order Fields

| Field | Description |
|-------|-------------|
| `preparedOrderId` | ID for executing the order |
| `amount` | Transfer amount |
| `fees` | Transaction fees |
| `totalAmount` | Amount + fees |
| `validUntil` | Order expiry time |

<Warning>
  **Order Validity:** Prepared orders expire after 2-3 hours. Execute before `validUntil` timestamp.
</Warning>

---

## Step 4: Execute Transfer Order

<Tabs>
  <Tab title="Request">
    **Endpoint:** `POST /api/v2.1/fintrans/{accountId}/types/transfer/execute`

    **Request Body:**
    ```json
    {
      "preparedOrderId": "prep-dd0e8400-e29b-41d4-a716-446655440070",
      "consentConfirmation": {
        "confirmed": true,
        "confirmationMethod": "EXPLICIT",
        "confirmationTimestamp": "2026-01-14T15:45:00.000Z"
      }
    }
    ```
  </Tab>
  <Tab title="Response">
    **Status:** `200 OK`

    ```json
    {
      "code": 200,
      "message": "Order executed successfully",
      "data": {
        "executionId": "exec-ee0e8400-e29b-41d4-a716-446655440080",
        "orderId": "order-ff0e8400-e29b-41d4-a716-446655440081",
        "preparedOrderId": "prep-dd0e8400-e29b-41d4-a716-446655440070",
        "status": "EXECUTING",
        "executionTimestamp": "2026-01-14T15:45:30.000Z",
        "estimatedCompletionTime": "2026-01-14T16:00:00.000Z",
        "transactionReference": "TXN-20260114-001",
        "confirmationNumber": "CNF-20260114-001"
      }
    }
    ```
  </Tab>
</Tabs>

---

## Order Status Flow

```mermaid
flowchart LR
    A[PREPARED] --> B[EXECUTING]
    B --> C{Outcome}
    C -->|Success| D[COMPLETED]
    C -->|Failure| E[FAILED]
    C -->|Cancelled| F[CANCELLED]
```

### Order Statuses

| Status | Description |
|--------|-------------|
| `PREPARED` | Order created, awaiting execution |
| `EXECUTING` | Order being processed |
| `COMPLETED` | Order successfully completed |
| `FAILED` | Order failed |
| `CANCELLED` | Order cancelled |

---

## Step 5: Check Order Status

<Tabs>
  <Tab title="Request">
    **Endpoint:** `GET /api/v2.1/fintrans/{accountId}/orders/{orderId}`

    **Headers:**
    ```http
    Authorization: Bearer {jwt-token}
    ```
  </Tab>
  <Tab title="Response">
    **Status:** `200 OK`

    ```json
    {
      "code": 200,
      "message": "Order retrieved successfully",
      "data": {
        "orderId": "order-ff0e8400-e29b-41d4-a716-446655440081",
        "operationType": "TRANSFER",
        "status": "COMPLETED",
        "amount": "100000",
        "amountFormatted": "1000.00",
        "currency": "EUR",
        "fees": "150",
        "feesFormatted": "1.50",
        "beneficiaryName": "Jane Smith",
        "beneficiaryIban": "GB82WEST12345698765432",
        "reference": "FAM-2026-001",
        "transactionReference": "TXN-20260114-001",
        "createdAt": "2026-01-14T15:45:00.000Z",
        "executedAt": "2026-01-14T15:45:30.000Z",
        "completedAt": "2026-01-14T15:50:00.000Z"
      }
    }
    ```
  </Tab>
</Tabs>

---

## Transfer Types

| Type | Endpoint Suffix | Description |
|------|-----------------|-------------|
| Transfer | `/types/transfer/prepare` | Standard transfer |
| Topup | `/types/topup/prepare` | Add funds to wallet |
| Payment | `/types/payment/prepare` | Make a payment |

---

## Fee Structure

| Transaction Type | Fee |
|------------------|-----|
| SEPA Transfer | €1.50 |
| SWIFT Transfer | €15.00 |
| Internal Transfer | Free |

---

## Complete Flow Summary

```
┌─────────────────────────────────────────────────────────────┐
│ INDIVIDUAL CUSTOMER COMPLETE LIFECYCLE                       │
└─────────────────────────────────────────────────────────────┘

Phase 1: Registration (5 min)
  └─→ Customer + User + Wallet created

Phase 2: Session (instant)
  └─→ JWT token for API calls

Phase 3: Verification (1-3 days)
  └─→ KYC documents submitted and approved

Phase 4: Consents (5 min)
  └─→ Terms, Privacy, Data Processing accepted

Phase 5: Activation (instant)
  └─→ IBAN generated, wallet activated

Phase 6: Wallet Operations (ongoing)
  └─→ Balance queries, limits check

Phase 7: Payment Operations (ongoing)
  └─→ Beneficiaries, transfers, payments
```

---

## Related Resources

<CardGroup cols={2}>
  <Card title="Error Handling" icon="triangle-exclamation" href="/baas/api/integration/flows/common/error-handling">
    Common errors and troubleshooting
  </Card>
  <Card title="Best Practices" icon="lightbulb" href="/baas/api/integration/flows/common/best-practices">
    Implementation best practices
  </Card>
</CardGroup>


---

# Organization Customer (B2B) Flow

Complete lifecycle guide for Organization customer onboarding and operations


URL: /baas/api/integration/flows/organization-customer



# Organization Customer (B2B) Flow

Complete end-to-end guide for onboarding organization (B2B) customers - from registration through to active transaction operations.

## Flow Overview

The Organization Customer flow is more complex than individual customers, involving multiple stakeholders (employees, directors, shareholders) and additional compliance requirements.

```mermaid
flowchart LR
    A[Registration] --> B[Personnel]
    B --> C[Verification]
    C --> D[Consents]
    D --> E[Activation]
    E --> F[Beneficiaries]
    F --> G[Payment Consent]
    G --> H[Transactions]
    
    style A fill:#e3f2fd
    style B fill:#e3f2fd
    style C fill:#fff8e1
    style D fill:#fff8e1
    style E fill:#e8f5e9
    style F fill:#e8f5e9
    style G fill:#e8f5e9
    style H fill:#e8f5e9
```

## Timeline

```
Registration → Personnel → Verification → Consent → Activation → Operations
   (10 min)     (20 min)    (2-5 days)    (10 min)   (instant)    (ongoing)
```

## Key Characteristics

| Characteristic | Description |
|----------------|-------------|
| **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 (Know Your Business) + UBO verification |
| **Categorization-Based Limits** | Transaction limits based on risk category |
| **Tenant-Level Approval** | Medium-risk approved by tenant admin |

---

## The 8 Phases

<Steps>
  <Step title="Phase 1: Organization Registration">
    Create organization record with legal information, addresses, and representatives.
    
    **Key Endpoint:** `POST /api/v2.1/customer/organization/registration`
    
    **Duration:** ~10 minutes
  </Step>
  
  <Step title="Phase 2: Personnel Management">
    Add directors, shareholders, and employees. Each creates an individual customer record.
    
    **Key Endpoints:**
    - `POST /api/v2.1/customer/organization/{orgId}/director`
    - `POST /api/v2.1/customer/organization/{orgId}/shareholders`
    - `POST /api/v2.1/customer/organization/{orgId}/employee`
    
    **Duration:** ~20 minutes
  </Step>
  
  <Step title="Phase 3: Organization Verification">
    KYB verification with business documents and UBO verification.
    
    **Key Endpoint:** `POST /api/v2.1/customer/organization/{orgId}/verify`
    
    **Duration:** 2-5 business days
  </Step>
  
  <Step title="Phase 4: Consent Management">
    Accept organization-level consents with authorized signatory details.
    
    **Key Endpoint:** `POST /api/v2.1/customer/organization/{orgId}/consents/{type}`
    
    **Duration:** ~10 minutes
  </Step>
  
  <Step title="Phase 5: Organization Activation">
    Validate roles, activate organization, generate IBAN and wallet.
    
    **Key Endpoint:** `POST /api/v2.1/customer/organization/{orgId}/activation`
    
    **Duration:** Instant
  </Step>
  
  <Step title="Phase 6: Beneficiary Management">
    Add business beneficiaries with enhanced due diligence.
    
    **Key Endpoint:** `POST /api/v2.1/fintrans/{accountId}/beneficiaries`
    
    **Duration:** Ongoing
  </Step>
  
  <Step title="Phase 7: Payment Consent Setup">
    Create payment consents with limits and beneficiary restrictions.
    
    **Key Endpoint:** `POST /api/v2.1/fintrans/{walletId}/payment-consents/types/transfer`
    
    **Duration:** ~5 minutes
  </Step>
  
  <Step title="Phase 8: Transaction Operations">
    Fund wallet, prepare transfers, execute payments with document requirements.
    
    **Key Endpoint:** `POST /api/v2.1/fintrans/{accountId}/types/transfer/execute`
    
    **Duration:** Ongoing
  </Step>
</Steps>

---

## Critical Prerequisites

### For Registration
- Legal documents (registration number, tax ID)
- Registered address
- Contact person details
- Representatives information

### For Personnel
- Organization must be registered
- Valid admin session

### For Activation

<Warning>
  **ALL prerequisites must be met:**
  1. User has `COMPLIANCE_OFFICER` or `ADMIN_USER` role
  2. Organization status: Not already `ACTIVE`
  3. Verification: `APPROVED`
  4. Role requirements met for business type
  5. Organization consents: All three `ACCEPTED`
</Warning>

### For Transactions
- Active wallet
- Payment consents in place
- Pre-registered beneficiaries
- Supporting documents (for high-value)

---

## B2B vs B2C Key Differences

| Aspect | Organization (B2B) | Individual (B2C) |
|--------|-------------------|------------------|
| **Registration** | Requires separate personnel endpoints | Single endpoint |
| **Personnel** | Directors, Shareholders, Employees | N/A |
| **First Employee** | Must have `ADMIN_USER` role | N/A |
| **Verification** | KYB (Business + UBO) | KYC (Identity) |
| **Consent Format** | Requires `acceptedBy` + `acceptedDate` | `accepted: true` only |
| **Activation** | Requires `activationReason` + admin headers | Simple code |
| **Documents** | Additional metadata fields | Basic fields |

---

## Phase Navigation

<CardGroup cols={2}>
  <Card title="Phase 1: Registration" icon="building" href="/baas/api/integration/flows/organization-customer/registration">
    Organization registration with legal details
  </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 4: Consents" icon="file-signature" href="/baas/api/integration/flows/organization-customer/consent-management">
    Organization consent acceptance
  </Card>
  <Card title="Phase 5: Activation" icon="check-circle" href="/baas/api/integration/flows/organization-customer/activation">
    Role validation & activation
  </Card>
  <Card title="Phase 6: Beneficiaries" icon="address-book" href="/baas/api/integration/flows/organization-customer/beneficiary-management">
    Business beneficiary management
  </Card>
  <Card title="Phase 7: Payment Consent" icon="credit-card" href="/baas/api/integration/flows/organization-customer/payment-consent-setup">
    Payment consent with restrictions
  </Card>
  <Card title="Phase 8: Transactions" icon="banknote" href="/baas/api/integration/flows/organization-customer/transaction-operations">
    Transfers and payments
  </Card>
</CardGroup>

---

## Quick Reference: All Endpoints

| Phase | Endpoint | Method | Description |
|-------|----------|--------|-------------|
| 1 | `/api/v2.1/customer/organization/registration` | POST | Register organization |
| 1 | `/api/v2.1/customer/organization/{orgId}` | GET | Get organization details |
| 2 | `/api/v2.1/customer/organization/{orgId}/director` | POST | Add director |
| 2 | `/api/v2.1/customer/organization/{orgId}/shareholders` | POST | Add shareholders (bulk) |
| 2 | `/api/v2.1/customer/organization/{orgId}/employee` | POST | Add employee |
| 3 | `/api/v2.1/customer/organization/{orgId}/verify` | POST | Initiate verification |
| 3 | `/api/v2.1/verifications/{id}/documents` | POST | Upload documents |
| 3 | `/api/v2.1/verifications/{id}/approve` | POST | Approve verification |
| 4 | `/api/v2.1/customer/organization/{orgId}/consents/terms` | POST | Accept terms |
| 4 | `/api/v2.1/customer/organization/{orgId}/consents/privacy` | POST | Accept privacy |
| 4 | `/api/v2.1/customer/organization/{orgId}/consents/data-processing` | POST | Accept data processing |
| 5 | `/api/v2.1/customer/organization/{orgId}/activation` | POST | Activate organization |
| 6 | `/api/v2.1/fintrans/{accountId}/beneficiaries` | POST | Add beneficiary |
| 6 | `/api/v2.1/fintrans/{accountId}/beneficiaries` | GET | List beneficiaries |
| 7 | `/api/v2.1/fintrans/{walletId}/payment-consents/types/transfer` | POST | Create payment consent |
| 8 | `/api/v2.1/fintrans/{accountId}/types/topup/prepare` | POST | Prepare topup |
| 8 | `/api/v2.1/fintrans/{accountId}/types/transfer/prepare` | POST | Prepare transfer |
| 8 | `/api/v2.1/fintrans/{accountId}/types/transfer/execute` | POST | Execute transfer |


---

# Phase 1: Organization Registration

Register organization with legal information and representatives


URL: /baas/api/integration/flows/organization-customer/registration



# Phase 1: Organization Registration

Organization registration creates the foundation for all B2B operations including the organization entity, legal information, addresses, and default admin user.

## What Gets Created

| Component | Status | Description |
|-----------|--------|-------------|
| Organization Record | `PENDING_VERIFICATION` | Core organization entity |
| Default Admin User | `PENDING_ACTIVATION` | Created via Kafka event |
| Wallet | `INACTIVE` | Default wallet (activated later) |
| Categorization | Assigned | Feature-based category (if provided) |

<Info>
  **Important:** Employees, directors, and shareholders arrays in the registration request are **ignored**. Use separate endpoints to add these entities.
</Info>

---

## Register Organization

<Tabs>
  <Tab title="Request">
    **Endpoint:** `POST /api/v2.1/customer/organization/registration`

    **Headers:**
    ```http
    X-Tenant-ID: fh_api_finsei_ltd_7f957f77
    Authorization: Bearer {admin-jwt-token}
    Content-Type: application/json
    ```

    **Request Body:**
    ```json
    {
      "tenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
      "legalName": "Acme Corporation Limited",
      "tradingName": "Acme Corp",
      "businessType": "B2B",
      "registrationNumber": "REG123456789",
      "taxId": "TAX987654321",
      "vatNumber": "GB123456789",
      "incorporationDate": "2010-05-20",
      "legalForm": "LIMITED_LIABILITY_COMPANY",
      "industry": "TECHNOLOGY",
      "sector": "SOFTWARE_DEVELOPMENT",
      "numberOfEmployees": 50,
      "annualRevenue": "5000000",
      "website": "https://www.acme-corp.com",
      "description": "Leading provider of enterprise software solutions",
      "registeredAddress": {
        "street": "456 Business Avenue",
        "streetNumber": "456",
        "building": "Tech Tower",
        "floor": "5th Floor",
        "city": "London",
        "state": "Greater London",
        "postalCode": "EC1A 1BB",
        "country": "GB",
        "addressType": "REGISTERED_OFFICE"
      },
      "tradingAddress": {
        "street": "456 Business Avenue",
        "city": "London",
        "postalCode": "EC1A 1BB",
        "country": "GB",
        "addressType": "TRADING_ADDRESS"
      },
      "contactEmail": "contact@acme-corp.com",
      "contactPhone": "+442071234567",
      "contactPerson": {
        "firstName": "Jane",
        "lastName": "Smith",
        "position": "CEO",
        "email": "jane.smith@acme-corp.com",
        "phone": "+442071234569"
      },
      "representatives": [
        {
          "firstName": "Jane",
          "lastName": "Smith",
          "role": "CEO",
          "email": "jane.smith@acme-corp.com",
          "ownershipPercentage": 60.0,
          "nationality": "GB",
          "dateOfBirth": "1975-03-15",
          "isPEP": false
        },
        {
          "firstName": "John",
          "lastName": "Doe",
          "role": "CFO",
          "email": "john.doe@acme-corp.com",
          "ownershipPercentage": 40.0,
          "nationality": "GB",
          "dateOfBirth": "1978-07-22",
          "isPEP": false
        }
      ],
      "categorization": {
        "id": "org-cat-550e8400-e29b-41d4-a716-446655440100",
        "name": "MEDIUM_RISK_BUSINESS",
        "isActive": true,
        "categoryFeatureRelations": [
          {
            "feature": {
              "id": "org-feat-660e8400-e29b-41d4-a716-446655440101",
              "code": "BUSINESS_TRANSACTION_LIMITS"
            },
            "enabled": true,
            "parametrization": [
              { "name": "riskLevel", "value": "MEDIUM" },
              { "name": "riskScore", "value": "55" },
              { "name": "monthlyLimit", "value": "500000" },
              { "name": "transactionLimit", "value": "100000" },
              { "name": "dailyLimit", "value": "200000" }
            ]
          },
          {
            "feature": {
              "id": "org-feat-770e8400-e29b-41d4-a716-446655440102",
              "code": "INTERNATIONAL_PAYMENTS"
            },
            "enabled": true,
            "parametrization": [
              { "name": "swiftEnabled", "value": "true" },
              { "name": "sepaEnabled", "value": "true" },
              { "name": "crossBorderLimit", "value": "50000" }
            ]
          }
        ]
      }
    }
    ```
  </Tab>
  <Tab title="Success Response">
    **Status:** `201 Created`

    ```json
    {
      "code": 201,
      "message": "Organization registered successfully. Default admin will be created automatically. Use separate endpoints to add employees, directors, and shareholders.",
      "data": {
        "id": "org-880e8400-e29b-41d4-a716-446655440110",
        "legalName": "Acme Corporation Limited",
        "tradingName": "Acme Corp",
        "businessType": "B2B",
        "status": "PENDING_VERIFICATION",
        "registrationNumber": "REG123456789",
        "taxId": "TAX987654321",
        "incorporationDate": "2010-05-20",
        "industry": "TECHNOLOGY",
        "categorization": {
          "id": "org-cat-550e8400-e29b-41d4-a716-446655440100",
          "name": "MEDIUM_RISK_BUSINESS"
        },
        "addresses": {
          "registered": {...},
          "trading": {...}
        },
        "contacts": {
          "email": "contact@acme-corp.com",
          "phone": "+442071234567"
        },
        "representatives": [...],
        "employees": [],
        "directors": [],
        "shareholders": [],
        "createdAt": "2026-01-13T10:00:00.000Z"
      }
    }
    ```

    **Key ID to Store:**
    - `id` → Organization ID (for all subsequent calls)
  </Tab>
  <Tab title="Error Responses">
    **400 - Missing Required Fields:**
    ```json
    {
      "code": 400,
      "message": "Validation failed",
      "data": {
        "errors": [
          {
            "field": "registrationNumber",
            "message": "Registration number is required"
          },
          {
            "field": "taxId",
            "message": "Tax ID is required"
          }
        ]
      }
    }
    ```

    **409 - Organization Already Exists:**
    ```json
    {
      "code": 409,
      "message": "Organization already exists",
      "data": {
        "error": "Duplicate organization",
        "registrationNumber": "REG123456789",
        "existingOrganizationId": "org-880e8400..."
      }
    }
    ```
  </Tab>
</Tabs>

---

## Required Fields

| Field | Required | Description |
|-------|----------|-------------|
| `legalName` | ✅ | Official legal name |
| `businessType` | ✅ | B2B, B2C, etc. |
| `registrationNumber` | ✅ | Company registration number |
| `taxId` | ✅ | Tax identification number |
| `incorporationDate` | ✅ | Date of incorporation |
| `registeredAddress` | ✅ | Official registered address |
| `contactEmail` | ✅ | Primary contact email |
| `vatNumber` | Conditional | Required if VAT registered |

---

## Ownership Validation

Representatives' ownership must total 100%:

```javascript
function validateOwnership(representatives) {
  const totalOwnership = representatives.reduce(
    (sum, rep) => sum + rep.ownershipPercentage, 0
  );
  
  if (totalOwnership !== 100) {
    throw new ValidationError(
      `Total ownership must equal 100%. Current: ${totalOwnership}%`
    );
  }
}
```

---

## Default Admin Creation

After organization creation, a Kafka event triggers automatic admin user creation:

```
OrganizationCreatedEvent → Create Admin User
                         → Send Activation Email
```

The default admin receives:
- Email: `contactEmail` from registration
- Roles: `ADMIN`, `ADMIN_USER`
- Status: `PENDING_ACTIVATION`

---

## Get Organization Details

<Tabs>
  <Tab title="Request">
    **Endpoint:** `GET /api/v2.1/customer/organization/{organizationId}`

    **Headers:**
    ```http
    Authorization: Bearer {jwt-token}
    ```
  </Tab>
  <Tab title="Response">
    **Status:** `200 OK`

    ```json
    {
      "code": 200,
      "message": "Organization retrieved successfully",
      "data": {
        "id": "org-880e8400-e29b-41d4-a716-446655440110",
        "legalName": "Acme Corporation Limited",
        "status": "PENDING_VERIFICATION",
        "employees": [],
        "directors": [],
        "shareholders": [],
        "verificationStatus": null,
        "activationStatus": null,
        "wallet": {
          "id": "wallet-aa0e8400...",
          "status": "INACTIVE",
          "iban": null
        },
        "metadata": {
          "personnelCount": {
            "employees": 0,
            "directors": 0,
            "shareholders": 0
          },
          "complianceStatus": {
            "verification": "NOT_STARTED",
            "consents": "NOT_STARTED",
            "activation": "NOT_ELIGIBLE"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

---

## Next Step

After registration, proceed to **Phase 2: Personnel Management** to add directors, shareholders, and employees.

<Card title="Phase 2: Personnel Management" icon="arrow-right" href="/baas/api/integration/flows/organization-customer/personnel-management">
  Add directors, shareholders, and employees
</Card>


---

# Phase 2: Personnel Management

Add directors, shareholders, and employees to the organization


URL: /baas/api/integration/flows/organization-customer/personnel-management



# Phase 2: Personnel Management

Personnel must be added **AFTER** organization registration. Each person added also creates an individual customer record with login credentials.

## Personnel Types

| Type | Description | Creates Individual Record |
|------|-------------|---------------------------|
| **Directors** | Board members (verification required) | ✅ Yes |
| **Shareholders** | Ownership stakeholders | ✅ Yes (for individuals) |
| **Employees** | Operations staff with specific roles | ✅ Yes |

<Warning>
  **First Employee Rule:** The first employee added to an organization MUST have the `ADMIN_USER` role. Without this role, the request will fail with a 400 error.
</Warning>

---

## Add Director

Directors are automatically created as individual customers with temporary passwords.

<Tabs>
  <Tab title="Request">
    **Endpoint:** `POST /api/v2.1/customer/organization/{organizationId}/director`

    **Headers:**
    ```http
    Authorization: Bearer {admin-jwt-token}
    Content-Type: application/json
    ```

    **Request Body:**
    ```json
    {
      "tenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
      "organizationId": "org-880e8400-e29b-41d4-a716-446655440110",
      "email": "director@acme-corp.com",
      "firstName": "Michael",
      "middleName": "Robert",
      "lastName": "Brown",
      "dateOfBirth": "1970-09-25",
      "nationality": "GB",
      "phoneNumber": "+442071234572",
      "position": "Board Director",
      "directorType": "NON_EXECUTIVE",
      "appointmentDate": "2010-06-01",
      "isPEP": false,
      "ownershipPercentage": 0,
      "address": {
        "street": "321 Director Avenue",
        "city": "London",
        "postalCode": "EC3A 1BB",
        "country": "GB"
      },
      "identificationDocument": {
        "type": "PASSPORT",
        "number": "GB987654321",
        "issuingCountry": "GB",
        "expiryDate": "2030-12-31"
      }
    }
    ```
  </Tab>
  <Tab title="Response">
    **Status:** `200 OK`

    ```json
    {
      "code": 200,
      "message": "Director added successfully",
      "data": {
        "organization": {
          "id": "org-dir-bb0e8400-e29b-41d4-a716-446655440140",
          "organizationId": "org-880e8400-e29b-41d4-a716-446655440110",
          "email": "director@acme-corp.com",
          "firstName": "Michael",
          "lastName": "Brown",
          "position": "Board Director",
          "directorType": "NON_EXECUTIVE",
          "appointmentDate": "2010-06-01",
          "status": "ACTIVE",
          "verificationStatus": "PENDING"
        },
        "individual": {
          "id": "ind-cc0e8400-e29b-41d4-a716-446655440141",
          "email": "director@acme-corp.com",
          "firstName": "Michael",
          "lastName": "Brown",
          "username": "director@acme-corp.com",
          "password": "Auto-Generated-P@ssw0rd456",
          "status": "ACTIVE",
          "linkedOrganization": "org-880e8400-e29b-41d4-a716-446655440110"
        }
      }
    }
    ```

    **Key IDs Created:**
    - Director's individual customer ID
    - Director's user ID
    - Temporary password (should be changed on first login)
  </Tab>
</Tabs>

### Director Types

| Type | Description |
|------|-------------|
| `EXECUTIVE` | Full-time executive director |
| `NON_EXECUTIVE` | Part-time non-executive director |
| `MANAGING` | Managing director |
| `CHAIRMAN` | Board chairman |

---

## Add Shareholders (Bulk)

Shareholders can be added in bulk using an array.

<Tabs>
  <Tab title="Request">
    **Endpoint:** `POST /api/v2.1/customer/organization/{organizationId}/shareholders`

    **Request Body (Array):**
    ```json
    [
      {
        "tenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
        "organizationId": "org-880e8400-e29b-41d4-a716-446655440110",
        "name": "Investment Fund Alpha Ltd",
        "shareholderType": "CORPORATE",
        "ownershipPercentage": 55.0,
        "numberOfShares": 5500,
        "shareClass": "ORDINARY",
        "votingRights": true,
        "registrationNumber": "REG-FUND-001",
        "taxId": "TAX-FUND-001",
        "country": "GB",
        "address": {
          "street": "100 Investment Street",
          "city": "London",
          "postalCode": "EC4A 1BB",
          "country": "GB"
        },
        "contactPerson": {
          "name": "Fund Manager",
          "email": "manager@investment-alpha.com",
          "phone": "+442071234580"
        }
      },
      {
        "tenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
        "organizationId": "org-880e8400-e29b-41d4-a716-446655440110",
        "name": "John Investor",
        "shareholderType": "INDIVIDUAL",
        "ownershipPercentage": 45.0,
        "numberOfShares": 4500,
        "shareClass": "ORDINARY",
        "votingRights": true,
        "dateOfBirth": "1965-04-12",
        "nationality": "GB",
        "identificationDocument": {
          "type": "PASSPORT",
          "number": "GB123789456",
          "issuingCountry": "GB"
        },
        "address": {
          "street": "200 Investor Road",
          "city": "London",
          "postalCode": "EC5A 1BB",
          "country": "GB"
        }
      }
    ]
    ```
  </Tab>
  <Tab title="Response">
    **Status:** `200 OK`

    ```json
    {
      "code": 200,
      "message": "Shareholders added successfully",
      "data": {
        "count": 2,
        "shareholders": [
          {
            "id": "share-dd0e8400-e29b-41d4-a716-446655440150",
            "name": "Investment Fund Alpha Ltd",
            "shareholderType": "CORPORATE",
            "ownershipPercentage": 55.0
          },
          {
            "id": "share-ee0e8400-e29b-41d4-a716-446655440151",
            "name": "John Investor",
            "shareholderType": "INDIVIDUAL",
            "ownershipPercentage": 45.0
          }
        ],
        "totalOwnership": 100.0,
        "validationStatus": "VALID"
      }
    }
    ```
  </Tab>
</Tabs>

### Shareholder Types

| Type | Description |
|------|-------------|
| `INDIVIDUAL` | Personal shareholder |
| `CORPORATE` | Company shareholder |

### Share Classes

| Class | Description |
|-------|-------------|
| `ORDINARY` | Standard voting shares |
| `PREFERENCE` | Preference shares with dividends |
| `REDEEMABLE` | Redeemable shares |

---

## Add Employee

<Tabs>
  <Tab title="Request">
    **Endpoint:** `POST /api/v2.1/customer/organization/{organizationId}/employee`

    **Request Body:**
    ```json
    {
      "tenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
      "organizationId": "org-880e8400-e29b-41d4-a716-446655440110",
      "email": "compliance@acme-corp.com",
      "firstName": "Sarah",
      "middleName": "Jane",
      "lastName": "Johnson",
      "dateOfBirth": "1985-06-10",
      "nationality": "GB",
      "phoneNumber": "+442071234571",
      "department": "Compliance",
      "position": "Chief Compliance Officer",
      "employeeNumber": "EMP001",
      "startDate": "2015-03-01",
      "roles": ["EMPLOYEE", "COMPLIANCE_OFFICER", "ADMIN_USER"],
      "permissions": [
        "VIEW_TRANSACTIONS",
        "INITIATE_VERIFICATION",
        "APPROVE_SMALL_TRANSACTIONS"
      ],
      "address": {
        "street": "789 Employee Street",
        "city": "London",
        "postalCode": "EC2A 1BB",
        "country": "GB"
      }
    }
    ```
  </Tab>
  <Tab title="Success Response">
    **Status:** `200 OK`

    ```json
    {
      "code": 200,
      "message": "Employee added successfully with role validation",
      "data": {
        "organization": {
          "id": "org-emp-990e8400-e29b-41d4-a716-446655440130",
          "organizationId": "org-880e8400-e29b-41d4-a716-446655440110",
          "email": "compliance@acme-corp.com",
          "firstName": "Sarah",
          "lastName": "Johnson",
          "department": "Compliance",
          "position": "Chief Compliance Officer",
          "roles": ["EMPLOYEE", "COMPLIANCE_OFFICER", "ADMIN_USER"],
          "status": "ACTIVE",
          "createdAt": "2026-01-13T10:30:00.000Z"
        },
        "individual": {
          "id": "ind-aa0e8400-e29b-41d4-a716-446655440131",
          "email": "compliance@acme-corp.com",
          "firstName": "Sarah",
          "lastName": "Johnson",
          "username": "compliance@acme-corp.com",
          "password": "Auto-Generated-P@ssw0rd123",
          "status": "ACTIVE",
          "linkedOrganization": "org-880e8400-e29b-41d4-a716-446655440110"
        }
      }
    }
    ```
  </Tab>
  <Tab title="Error - Missing ADMIN_USER">
    **Status:** `400 Bad Request`

    ```json
    {
      "code": 400,
      "message": "Missing required role 'ADMIN_USER' for BUSINESS_TYPE_CLIENT_TO_TENANT organization. At least one employee must have this role."
    }
    ```
  </Tab>
</Tabs>

---

## Employee Roles

| Role | Description |
|------|-------------|
| `EMPLOYEE` | Base role for all employees |
| `ADMIN_USER` | Administrative access (required for first employee) |
| `COMPLIANCE_OFFICER` | Compliance and verification access |
| `TRANSACTION_APPROVER` | Approve transactions |
| `OPERATIONS_MANAGER` | Operations management |

### Auto-Role Assignment

Roles can be auto-assigned based on department:

| Department | Auto-Assigned Roles |
|------------|---------------------|
| Compliance | `COMPLIANCE_OFFICER` |
| Finance | `TRANSACTION_APPROVER` |
| Management | `ADMIN_USER` |
| Operations | `OPERATIONS_MANAGER` |

---

## Get Organization Definitions

<Tabs>
  <Tab title="Request">
    **Endpoint:** `GET /api/v2.1/customer/organization/definitions`
  </Tab>
  <Tab title="Response">
    ```json
    {
      "code": 200,
      "message": "Definitions retrieved successfully",
      "data": {
        "ORG_REQUIRED_FIELDS": {
          "mandatory": [
            "legalName",
            "businessType",
            "registrationNumber",
            "taxId",
            "incorporationDate",
            "registeredAddress"
          ]
        },
        "SHAREHOLDER_RULES": {
          "totalOwnership": {
            "mustEqual": 100,
            "message": "Total ownership must equal 100%"
          },
          "minimumShareholders": 1,
          "shareholderTypes": ["INDIVIDUAL", "CORPORATE"],
          "shareClasses": ["ORDINARY", "PREFERENCE", "REDEEMABLE"]
        }
      }
    }
    ```
  </Tab>
</Tabs>

---

## Next Step

After adding personnel, proceed to **Phase 3: Verification** for KYB verification.

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


---

# Phase 3: Organization Verification

KYB verification, document upload, and approval workflow


URL: /baas/api/integration/flows/organization-customer/verification



# Phase 3: Organization Verification

Organization verification (KYB - Know Your Business) is more comprehensive than individual verification, including business entity verification, UBO verification, and financial statement review.

## Verification Requirements

| Verification Type | Description |
|-------------------|-------------|
| `BUSINESS_VERIFICATION` | Company registration and legal status |
| `DOCUMENT_VERIFICATION` | Business documents authentication |
| `BENEFICIAL_OWNER_VERIFICATION` | UBO identification and verification |
| `FINANCIAL_VERIFICATION` | Financial statements review |

---

## Required Documents

| Document Type | Description | Format | Max Size |
|---------------|-------------|--------|----------|
| `CERTIFICATE_OF_INCORPORATION` | Official incorporation certificate | PDF | 5 MB |
| `ARTICLES_OF_ASSOCIATION` | Company articles | PDF | 10 MB |
| `PROOF_OF_REGISTERED_ADDRESS` | Utility bill or bank statement | PDF/JPEG | 5 MB |
| `BENEFICIAL_OWNERS_DECLARATION` | UBO declaration form | PDF | 5 MB |
| `FINANCIAL_STATEMENTS` | Latest audited statements | PDF | 20 MB |
| `DIRECTOR_IDS` | ID documents for each director | PDF/JPEG | 5 MB each |
| `BANK_REFERENCE_LETTER` | Bank reference letter | PDF | 5 MB |
| `BUSINESS_LICENSE` | Industry-specific licenses | PDF | 5 MB |
| `TAX_CLEARANCE_CERTIFICATE` | Tax authority clearance | PDF | 5 MB |

---

## Initiate Organization Verification

<Tabs>
  <Tab title="Request">
    **Endpoint:** `POST /api/v2.1/customer/organization/{organizationId}/verify`

    **Required Role:** `COMPLIANCE_OFFICER` or `ADMIN_USER`

    **Headers:**
    ```http
    X-User-ID: user-660e8400-e29b-41d4-a716-446655440011
    X-User-Roles: COMPLIANCE_OFFICER
    Authorization: Bearer {jwt-token}
    ```

    **Request Body:**
    ```json
    {
      "verificationType": "KYB",
      "verificationLevel": "ENHANCED",
      "priority": "NORMAL",
      "verificationData": {
        "businessType": "B2B",
        "annualRevenue": "5000000",
        "employeeCount": "50",
        "businessDescription": "Enterprise software development",
        "mainProducts": ["Software Development", "Cloud Services"],
        "targetMarkets": ["UK", "EU", "US"],
        "regulatoryCompliance": ["GDPR", "PCI-DSS", "ISO27001"],
        "bankingRelationships": [
          {
            "bankName": "Westminster Bank",
            "accountNumber": "12345678",
            "sortCode": "12-34-56"
          }
        ]
      }
    }
    ```
  </Tab>
  <Tab title="Success Response">
    **Status:** `200 OK`

    ```json
    {
      "code": 200,
      "message": "Verification initiated successfully",
      "data": {
        "verificationId": "verif-ff0e8400-e29b-41d4-a716-446655440160",
        "organizationId": "org-880e8400-e29b-41d4-a716-446655440110",
        "status": "IN_PROGRESS",
        "type": "IDENTITY_VERIFICATION",
        "level": "ENHANCED",
        "startedAt": "2026-01-13T12:00:00.000Z",
        "dueDate": "2026-01-20T12:00:00.000Z",
        "requiredDocuments": [
          "CERTIFICATE_OF_INCORPORATION",
          "ARTICLES_OF_ASSOCIATION",
          "PROOF_OF_REGISTERED_ADDRESS",
          "BENEFICIAL_OWNERS_DECLARATION",
          "FINANCIAL_STATEMENTS",
          "BANK_REFERENCE_LETTER",
          "DIRECTOR_IDS",
          "BUSINESS_LICENSE",
          "TAX_CLEARANCE_CERTIFICATE"
        ],
        "verificationTypes": [
          "BUSINESS_VERIFICATION",
          "DOCUMENT_VERIFICATION",
          "BENEFICIAL_OWNER_VERIFICATION",
          "FINANCIAL_VERIFICATION"
        ],
        "assignedTo": "compliance-team",
        "estimatedCompletionTime": "3-5 business days"
      }
    }
    ```
  </Tab>
  <Tab title="Error - Insufficient Permission">
    **Status:** `403 Forbidden`

    ```json
    {
      "code": 403,
      "message": "Access denied: Only COMPLIANCE_OFFICER or ADMIN_USER can initiate verification",
      "data": {
        "userId": "user-660e8400...",
        "currentRoles": ["EMPLOYEE", "TRANSACTION_APPROVER"],
        "requiredRoles": ["COMPLIANCE_OFFICER", "ADMIN_USER"]
      }
    }
    ```
  </Tab>
</Tabs>

---

## Upload Verification Document

<Note>
  Use the **generic verification document endpoint** for both individual and organization verifications.
</Note>

<Tabs>
  <Tab title="Request">
    **Endpoint:** `POST /api/v2.1/verifications/{verificationId}/documents`

    **Content-Type:** `application/json`

    **Headers:**
    ```http
    Authorization: Bearer {jwt-token}
    Content-Type: application/json
    ```

    **Request Body:**
    ```json
    {
      "docId": "550e8400-e29b-41d4-a716-446655440000",
      "documentType": "CERTIFICATE_OF_INCORPORATION",
      "fileName": "certificate_of_incorporation.pdf",
      "fileContent": "JVBERi0xLjQKJeLjz9MKMyAwIG9iaiA8PAovVHlwZSAvUGFnZQovUGFy...",
      "customerId": "org-880e8400-e29b-41d4-a716-446655440110",
      "description": "Certificate of Incorporation - Acme Corp",
      "documentCategory": "VERIFICATION",
      "metadata": {
        "issuer": "Companies House",
        "issueDate": "2010-05-20",
        "documentNumber": "REG123456789",
        "certificateType": "ORIGINAL"
      }
    }
    ```

    **Field Descriptions:**
    - `fileContent`: Base64-encoded file content
    - `documentCategory`: Use `VERIFICATION` for KYB documents
    - `customerId`: Organization ID (from verification initiation)
  </Tab>
  <Tab title="Response">
    **Status:** `201 Created`

    ```json
    {
      "code": 201,
      "message": "Document uploaded successfully",
      "data": {
        "documentId": "doc-0011e8400-e29b-41d4-a716-446655440170",
        "verificationId": "verif-ff0e8400-e29b-41d4-a716-446655440160",
        "customerId": "org-880e8400-e29b-41d4-a716-446655440110",
        "documentType": "CERTIFICATE_OF_INCORPORATION",
        "fileName": "certificate_of_incorporation.pdf",
        "fileSize": 2048576,
        "uploadedAt": "2026-01-13T13:00:00.000Z",
        "status": "UPLOADED",
        "verificationStatus": "IN_PROGRESS"
      }
    }
    ```
  </Tab>
</Tabs>

---

## Get Verification Status

<Tabs>
  <Tab title="Request">
    **Endpoint:** `GET /api/v2.1/customer/organization/{organizationId}/verification`
  </Tab>
  <Tab title="Response">
    **Status:** `200 OK`

    ```json
    {
      "code": 200,
      "message": "Verification status retrieved successfully",
      "data": {
        "organizationId": "org-880e8400-e29b-41d4-a716-446655440110",
        "verificationId": "verif-ff0e8400-e29b-41d4-a716-446655440160",
        "status": "PENDING_REVIEW",
        "type": "IDENTITY_VERIFICATION",
        "level": "TENANT_VERIFIED",
        "startedAt": "2026-01-13T12:00:00.000Z",
        "completedAt": null,
        "expiresAt": "2026-04-13T12:00:00.000Z",
        "submittedDocuments": 5,
        "documentStatus": {
          "CERTIFICATE_OF_INCORPORATION": "SUBMITTED",
          "ARTICLES_OF_ASSOCIATION": "SUBMITTED",
          "PROOF_OF_REGISTERED_ADDRESS": "SUBMITTED",
          "BENEFICIAL_OWNERS_DECLARATION": "SUBMITTED",
          "FINANCIAL_STATEMENTS": "SUBMITTED",
          "DIRECTOR_IDS": "PENDING",
          "BANK_REFERENCE_LETTER": "PENDING"
        },
        "verificationHistory": [
          {
            "status": "IN_PROGRESS",
            "timestamp": "2026-01-13T12:00:00.000Z",
            "actor": "COMPLIANCE_OFFICER"
          },
          {
            "status": "PENDING_REVIEW",
            "timestamp": "2026-01-14T10:00:00.000Z",
            "actor": "system",
            "note": "All required documents submitted"
          }
        ],
        "nextSteps": [
          "Upload remaining director ID documents",
          "Upload bank reference letter",
          "Wait for tenant admin review"
        ]
      }
    }
    ```
  </Tab>
</Tabs>

---

## Verification Status Flow

```mermaid
flowchart LR
    A[INITIATED] --> B[IN_PROGRESS]
    B --> C[PENDING_REVIEW]
    C --> D[UNDER_REVIEW]
    D --> E{Decision}
    E -->|Approved| F[APPROVED]
    E -->|Rejected| G[REJECTED]
    E -->|More Info| H[ADDITIONAL_INFO_REQUIRED]
    H --> B
```

---

## Approve Verification (Admin)

<Tabs>
  <Tab title="Request">
    **Endpoint:** `POST /api/v2.1/verifications/{verificationId}/approve`

    **Headers:**
    ```http
    Authorization: Bearer {admin-jwt-token}
    X-User-ID: admin-user-id
    X-User-Roles: COMPLIANCE_OFFICER
    ```

    **Request Body:**
    ```json
    {
      "adminNotes": "All documents verified. Organization identity confirmed.",
      "approvedBy": "ADMIN_USER",
      "approvalReason": "All documents verified for organization customer"
    }
    ```
  </Tab>
  <Tab title="Response">
    **Status:** `200 OK`

    ```json
    {
      "code": 200,
      "message": "Verification approved successfully",
      "data": {
        "level": "TENANT_VERIFIED",
        "approvedBy": "admin-user",
        "approvedAt": "2026-01-15T10:00:00.000Z",
        "verificationId": "verif-ff0e8400-e29b-41d4-a716-446655440160",
        "status": "APPROVED"
      }
    }
    ```
  </Tab>
</Tabs>

---

## Next Step

After verification is APPROVED, proceed to **Phase 4: Consent Management**.

<Card title="Phase 4: Consent Management" icon="arrow-right" href="/baas/api/integration/flows/organization-customer/consent-management">
  Accept organization-level consents
</Card>


---

# Phase 4: Consent Management

Accept organization-level consents with authorized signatory details


URL: /baas/api/integration/flows/organization-customer/consent-management



# Phase 4: Consent Management

Organization consents are at **organization level** (not per-user) and must be accepted by an authorized signatory (CEO or equivalent).

## Required Consents

| Consent Type | Required | Accepted By |
|--------------|----------|-------------|
| `TERMS_AND_CONDITIONS` | ✅ Yes | CEO/Authorized Signatory |
| `PRIVACY_POLICY` | ✅ Yes | CEO/Authorized Signatory |
| `DATA_PROCESSING` | ✅ Yes | CEO/Authorized Signatory |
| `COMMERCIAL_SERVICES` | Optional | CEO/Authorized Signatory |

<Warning>
  **Key Difference from Individual Consents:** Organization consents require `acceptedBy` object with signatory details.
</Warning>

---

## Accept Terms and Conditions

<Tabs>
  <Tab title="Request">
    **Endpoint:** `POST /api/v2.1/customer/organization/{organizationId}/consents/terms`

    **Headers:**
    ```http
    Authorization: Bearer {ceo-or-admin-jwt-token}
    User-Agent: Mozilla/5.0...
    ```

    **Request Body:**
    ```json
    {
      "accepted": true,
      "version": "1.0",
      "acceptedBy": {
        "name": "Jane Smith",
        "position": "CEO",
        "email": "jane.smith@acme-corp.com",
        "authority": "AUTHORIZED_SIGNATORY"
      },
      "acceptanceTimestamp": "2026-01-15T10:00:00.000Z",
      "digitalSignature": "base64-encoded-signature"
    }
    ```
  </Tab>
  <Tab title="Response">
    **Status:** `200 OK`

    ```json
    {
      "code": 200,
      "message": "terms and conditions accepted successfully",
      "data": {
        "id": "consent-1122e8400-e29b-41d4-a716-446655440180",
        "organizationId": "org-880e8400-e29b-41d4-a716-446655440110",
        "tenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
        "consentType": "TERMS_AND_CONDITIONS",
        "status": "ACCEPTED",
        "version": "1.0",
        "grantedAt": "2026-01-15T10:00:00.000Z",
        "expiresAt": "2027-01-15T10:00:00.000Z",
        "acceptedBy": {
          "name": "Jane Smith",
          "position": "CEO",
          "authority": "AUTHORIZED_SIGNATORY"
        },
        "ipAddress": "192.168.1.100",
        "userAgent": "Mozilla/5.0...",
        "digitalSignature": "base64-encoded-signature",
        "legallyBinding": true,
        "metadata": {
          "documentUrl": "https://finhub.com/terms/business/v1.0",
          "language": "en-GB",
          "jurisdiction": "England and Wales"
        }
      }
    }
    ```
  </Tab>
</Tabs>

---

## Accept Privacy Policy

<Tabs>
  <Tab title="Request">
    **Endpoint:** `POST /api/v2.1/customer/organization/{organizationId}/consents/privacy`

    **Request Body:**
    ```json
    {
      "accepted": true,
      "version": "1.0",
      "acceptedBy": {
        "name": "Jane Smith",
        "position": "CEO",
        "email": "jane.smith@acme-corp.com",
        "authority": "AUTHORIZED_SIGNATORY"
      },
      "acceptanceTimestamp": "2026-01-15T10:05:00.000Z"
    }
    ```
  </Tab>
  <Tab title="Response">
    **Status:** `200 OK`

    ```json
    {
      "code": 200,
      "message": "Privacy policy accepted successfully",
      "data": {
        "id": "consent-1122e8400-e29b-41d4-a716-446655440181",
        "consentType": "PRIVACY_POLICY",
        "status": "ACCEPTED",
        "grantedAt": "2026-01-15T10:05:00.000Z",
        "acceptedBy": {
          "name": "Jane Smith",
          "position": "CEO"
        }
      }
    }
    ```
  </Tab>
</Tabs>

---

## Accept Data Processing Agreement

<Tabs>
  <Tab title="Request">
    **Endpoint:** `POST /api/v2.1/customer/organization/{organizationId}/consents/data-processing`

    **Request Body:**
    ```json
    {
      "accepted": true,
      "version": "1.0",
      "acceptedBy": {
        "name": "Jane Smith",
        "position": "CEO",
        "email": "jane.smith@acme-corp.com",
        "authority": "AUTHORIZED_SIGNATORY"
      },
      "acceptanceTimestamp": "2026-01-15T10:10:00.000Z"
    }
    ```
  </Tab>
  <Tab title="Response">
    **Status:** `200 OK`

    ```json
    {
      "code": 200,
      "message": "Data processing agreement accepted successfully",
      "data": {
        "id": "consent-1122e8400-e29b-41d4-a716-446655440182",
        "consentType": "DATA_PROCESSING",
        "status": "ACCEPTED",
        "grantedAt": "2026-01-15T10:10:00.000Z"
      }
    }
    ```
  </Tab>
</Tabs>

---

## AcceptedBy Object

The `acceptedBy` object captures signatory details for legal compliance:

| Field | Required | Description |
|-------|----------|-------------|
| `name` | ✅ | Full name of signatory |
| `position` | ✅ | Position in organization |
| `email` | ✅ | Email address |
| `authority` | ✅ | Authority type |

### Authority Types

| Authority | Description |
|-----------|-------------|
| `AUTHORIZED_SIGNATORY` | Legally authorized to sign |
| `CEO` | Chief Executive Officer |
| `CFO` | Chief Financial Officer |
| `DIRECTOR` | Board Director |
| `LEGAL_REPRESENTATIVE` | Legal Representative |

---

## B2B vs B2C Consent Comparison

| Field | Individual (B2C) | Organization (B2B) |
|-------|------------------|-------------------|
| `accepted` | ✅ Required | ✅ Required |
| `version` | ✅ Required | ✅ Required |
| `acceptedBy` | ❌ Not required | ✅ Required |
| `digitalSignature` | ❌ Optional | ✅ Recommended |
| `jurisdiction` | ❌ Not captured | ✅ Captured |

---

## Director Consents (Optional)

Each director may need to accept individual `DATA_PROCESSING` consent.

<Info>
  **Note:** Director consents are currently BYPASSED in activation checks for testing purposes.
</Info>

**Endpoint:** `POST /api/v2.1/customer/individual/{directorIndividualId}/consents/data-processing`

---

## Next Step

After all consents are accepted, proceed to **Phase 5: Organization Activation**.

<Card title="Phase 5: Activation" icon="arrow-right" href="/baas/api/integration/flows/organization-customer/activation">
  Validate roles and activate organization
</Card>


---

# Phase 5: Organization Activation

Role validation, activation, and wallet enablement


URL: /baas/api/integration/flows/organization-customer/activation



# Phase 5: Organization Activation

Activation is the final step that enables the organization to perform financial operations. This phase includes role validation, IBAN generation, and wallet activation.

## Prerequisites Checklist

<Warning>
  **ALL prerequisites must be met before activation:**
</Warning>

| # | Prerequisite | Required Status |
|---|--------------|-----------------|
| 1 | User has COMPLIANCE_OFFICER or ADMIN_USER role | ✅ |
| 2 | Organization status | Not already `ACTIVE` |
| 3 | Verification status | `APPROVED` |
| 4 | Director verification | `APPROVED` (bypassed) |
| 5 | Role requirements for business type | Met |
| 6 | Minimum personnel | 1 director, 1 shareholder, 1 employee |
| 7 | Terms & Conditions | `ACCEPTED` |
| 8 | Privacy Policy | `ACCEPTED` |
| 9 | Data Processing | `ACCEPTED` |
| 10 | Director consents | All DATA_PROCESSING (bypassed) |

---

## Activate Organization

<Tabs>
  <Tab title="Request">
    **Endpoint:** `POST /api/v2.1/customer/organization/{organizationId}/activation`

    **Headers:**
    ```http
    X-User-ID: user-660e8400-e29b-41d4-a716-446655440011
    X-User-Roles: ADMIN_USER
    Authorization: Bearer {jwt-token}
    ```

    **Request Body:**
    ```json
    {
      "activationReason": "All prerequisites met - verification approved, all consents accepted, personnel requirements satisfied",
      "activatedBy": "admin-user-id",
      "activationNotes": "Organization ready for live operations"
    }
    ```
  </Tab>
  <Tab title="Success Response">
    **Status:** `200 OK`

    ```json
    {
      "code": 200,
      "message": "Organization activated successfully",
      "data": {
        "activation": {
          "message": "Organization activated successfully",
          "status": "ACTIVE",
          "activatedAt": "2026-01-15T14:00:00.000Z",
          "activatedBy": "admin-user-id",
          "warnings": [
            "Optional consent 'MARKETING_COMMUNICATIONS' not given"
          ]
        },
        "organizationId": "org-880e8400-e29b-41d4-a716-446655440110",
        "iban": "FR7630001007941234567890186",
        "bic": "SOGEFRPP",
        "accountName": "Acme Corporation Limited",
        "wallet": {
          "walletId": "wallet-aa0e8400-e29b-41d4-a716-446655440120",
          "id": "wallet-aa0e8400-e29b-41d4-a716-446655440120",
          "iban": "FR7630001007941234567890186",
          "bic": "SOGEFRPP",
          "currency": "EUR",
          "balance": "0.00",
          "status": "ACTIVE",
          "accountType": "BUSINESS",
          "features": [
            "SEPA_TRANSFERS",
            "SWIFT_TRANSFERS",
            "BULK_PAYMENTS",
            "DIRECT_DEBITS"
          ]
        },
        "limits": {
          "dailyLimit": "200000.00",
          "monthlyLimit": "500000.00",
          "singleTransactionLimit": "100000.00",
          "currency": "EUR"
        },
        "nextSteps": [
          "Add beneficiaries for payments",
          "Create payment consents",
          "Fund wallet via incoming transfer",
          "Begin transaction operations"
        ]
      }
    }
    ```
  </Tab>
  <Tab title="Error - Missing Consents">
    **Status:** `400 Bad Request`

    ```json
    {
      "code": 400,
      "message": "Missing required consents",
      "data": {
        "activationStatus": "CONSENT_REQUIRED",
        "missingConsents": ["DATA_PROCESSING"],
        "consentDetails": {
          "TERMS_AND_CONDITIONS": {
            "status": "ACCEPTED",
            "acceptedAt": "2026-01-15T10:00:00.000Z",
            "acceptedBy": "Jane Smith (CEO)"
          },
          "PRIVACY_POLICY": {
            "status": "ACCEPTED",
            "acceptedAt": "2026-01-15T10:05:00.000Z",
            "acceptedBy": "Jane Smith (CEO)"
          },
          "DATA_PROCESSING": {
            "status": "MISSING",
            "required": true,
            "acceptUrl": "/api/v2.1/customer/organization/{orgId}/consents/data-processing"
          }
        }
      }
    }
    ```
  </Tab>
  <Tab title="Error - Not Verified">
    **Status:** `422 Unprocessable Entity`

    ```json
    {
      "code": 422,
      "message": "Organization not verified",
      "data": {
        "activationStatus": "VERIFICATION_REQUIRED",
        "verificationStatus": "PENDING_REVIEW",
        "verificationId": "verif-ff0e8400-e29b-41d4-a716-446655440160",
        "reason": "Organization verification must be APPROVED before activation",
        "estimatedCompletionTime": "1-2 business days"
      }
    }
    ```
  </Tab>
</Tabs>

---

## Activation Validation Flow

```mermaid
flowchart TD
    A[Activation Request] --> B{Check User Role}
    B -->|Invalid| C[403 Forbidden]
    B -->|Valid| D{Check Org Status}
    D -->|Already Active| E[200 Already Active]
    D -->|Not Active| F{Check Verification}
    F -->|Not Approved| G[422 Not Verified]
    F -->|Approved| H{Check Role Requirements}
    H -->|Missing Roles| I[400 Missing Roles]
    H -->|Met| J{Check Consents}
    J -->|Missing| K[400 Missing Consents]
    J -->|All Present| L[Generate IBAN]
    L --> M[Activate Wallet]
    M --> N[Update Status]
    N --> O[Publish Events]
    O --> P[200 Success]
```

---

## Role Requirements by Business Type

| Business Type | Required Roles |
|---------------|----------------|
| `B2B` | `COMPLIANCE_OFFICER` |
| `B2C` | `CUSTOMER_SERVICE` |

---

## What Happens During Activation

1. **Validate User Permission** - Check COMPLIANCE_OFFICER or ADMIN_USER role
2. **Check Organization Status** - Verify not already ACTIVE
3. **Validate Verification** - Confirm APPROVED status
4. **Validate Role Requirements** - Check minimum roles for business type
5. **Check Minimum Personnel** - At least 1 director, shareholder, employee
6. **Check Organization Consents** - All three mandatory consents
7. **Generate IBAN** - Create unique IBAN for organization
8. **Activate Wallet** - Enable transaction capabilities
9. **Apply Limits** - Category-based transaction limits
10. **Update Status** - Set organization to ACTIVE
11. **Publish Events** - OrganizationActivated, WalletActivated (Kafka)
12. **Send Notifications** - Email confirmation

---

## Business Account Features

| Feature | Description |
|---------|-------------|
| `SEPA_TRANSFERS` | SEPA credit transfers |
| `SWIFT_TRANSFERS` | International wire transfers |
| `BULK_PAYMENTS` | Batch payment processing |
| `DIRECT_DEBITS` | Direct debit collections |

---

## Transaction Limits (Category-Based)

### Medium-Risk Business

| Limit Type | Amount (EUR) |
|------------|--------------|
| Daily | 200,000 |
| Monthly | 500,000 |
| Single Transaction | 100,000 |

### High-Risk Business

| Limit Type | Amount (EUR) |
|------------|--------------|
| Daily | 50,000 |
| Monthly | 200,000 |
| Single Transaction | 25,000 |

---

## Next Step

After activation, proceed to **Phase 6: Beneficiary Management**.

<Card title="Phase 6: Beneficiary Management" icon="arrow-right" href="/baas/api/integration/flows/organization-customer/beneficiary-management">
  Add business beneficiaries
</Card>


---

# Phase 6: Beneficiary Management

Add and manage business beneficiaries with enhanced due diligence


URL: /baas/api/integration/flows/organization-customer/beneficiary-management



# Phase 6: Beneficiary Management

Business beneficiaries require additional information compared to individual beneficiaries, including business relationship details and enhanced due diligence data.

## Prerequisites

| Requirement | Status |
|-------------|--------|
| Organization Status | `ACTIVE` |
| Wallet Status | `ACTIVE` |
| Valid Session | JWT token with appropriate role |

---

## Add Business Beneficiary

<Tabs>
  <Tab title="Request">
    **Endpoint:** `POST /api/v2.1/fintrans/{accountId}/beneficiaries`

    **Headers:**
    ```http
    Authorization: Bearer {jwt-token}
    Content-Type: application/json
    ```

    **Request Body:**
    ```json
    {
      "partyType": "BUSINESS_CUSTOMER",
      "companyName": "Supplier Corporation Ltd",
      "registrationNumber": "REG-SUPP-001",
      "taxId": "TAX-SUPP-001",
      "iban": "GB82WEST12345698765432",
      "currency": "EUR",
      "country": "GB",
      "email": "payments@supplier-corp.com",
      "phoneNumber": "+442071234567",
      "shortName": "Supplier Corp",
      "bicSwiftCode": "WESTGB21",
      "networkName": "SEPA",
      "bankName": "Westminster Bank",
      "bankAddress": "London, UK",
      "correspondentBankBic": null,
      "correspondentBankName": null,
      "purposeCode": "INVOICE_PAYMENT",
      "businessRelationship": {
        "relationshipType": "SUPPLIER",
        "contractReference": "CNT-2024-001",
        "monthlyVolume": "50000",
        "averageTransactionSize": "5000"
      },
      "additionalData": {
        "taxId": "GB123456789",
        "vatNumber": "GB987654321",
        "industryCode": "6201",
        "dueDiligenceCompleted": true,
        "sanctionsCheckDate": "2026-01-10"
      }
    }
    ```
  </Tab>
  <Tab title="Response">
    **Status:** `201 Created`

    ```json
    {
      "code": 201,
      "message": "Beneficiary created successfully",
      "data": {
        "beneficiaryId": "benef-2233e8400-e29b-41d4-a716-446655440190",
        "accountId": "wallet-aa0e8400-e29b-41d4-a716-446655440120",
        "partyType": "BUSINESS_CUSTOMER",
        "beneficiaryName": "Supplier Corporation Ltd",
        "iban": "GB82WEST12345698765432",
        "bic": "WESTGB21",
        "bicType": "external",
        "currency": "EUR",
        "country": "GB",
        "networkName": "SEPA",
        "bankName": "Westminster Bank",
        "purposeCode": "INVOICE_PAYMENT",
        "pepCheckResult": "VERIFIED",
        "sanctionsCheckResult": "CLEAR",
        "status": "active",
        "createdAt": "2026-01-15T15:00:00.000Z",
        "verifiedAt": "2026-01-15T15:00:00.000Z"
      }
    }
    ```
  </Tab>
</Tabs>

---

## Business Relationship Types

| Relationship Type | Description |
|-------------------|-------------|
| `SUPPLIER` | Goods or services supplier |
| `VENDOR` | Vendor relationship |
| `PARTNER` | Business partner |
| `SUBSIDIARY` | Subsidiary company |
| `AFFILIATE` | Affiliated company |
| `CONTRACTOR` | Contract service provider |

---

## Purpose Codes

| Code | Description |
|------|-------------|
| `INVOICE_PAYMENT` | Payment for invoices |
| `SALARY_PAYMENT` | Employee salary payments |
| `TAX_PAYMENT` | Tax payments to authorities |
| `LOAN_REPAYMENT` | Loan repayment |
| `DIVIDEND_PAYMENT` | Dividend distribution |
| `INVESTMENT` | Investment transfers |

---

## Enhanced Due Diligence Fields

| Field | Description |
|-------|-------------|
| `taxId` | Beneficiary's tax identification |
| `vatNumber` | VAT registration number |
| `industryCode` | Industry classification code |
| `dueDiligenceCompleted` | Due diligence status |
| `sanctionsCheckDate` | Date of last sanctions check |

---

## List Beneficiaries

<Tabs>
  <Tab title="Request">
    **Endpoint:** `GET /api/v2.1/fintrans/{accountId}/beneficiaries`

    **Query Parameters:**
    - `status`: Filter by status (active, inactive)
    - `partyType`: Filter by party type
    - `network`: Filter by network (SEPA, SWIFT)
  </Tab>
  <Tab title="Response">
    **Status:** `200 OK`

    ```json
    {
      "code": 200,
      "message": "Beneficiaries retrieved successfully",
      "data": [
        {
          "beneficiaryId": "benef-2233e8400-e29b-41d4-a716-446655440190",
          "beneficiaryName": "Supplier Corporation Ltd",
          "iban": "GB82WEST12345698765432",
          "network": "SEPA",
          "status": "active",
          "lastUsed": "2026-01-15T16:00:00.000Z"
        }
      ]
    }
    ```
  </Tab>
</Tabs>

---

## Beneficiary Verification

All beneficiaries undergo automatic verification:

| Check | Description | Result |
|-------|-------------|--------|
| **PEP Check** | Politically Exposed Person screening | VERIFIED / FLAGGED |
| **Sanctions Check** | Global sanctions list screening | CLEAR / FLAGGED |
| **IBAN Validation** | IBAN format and checksum | VALID / INVALID |

<Warning>
  Beneficiaries with `FLAGGED` status cannot be used for transactions until manually reviewed and approved.
</Warning>

---

## Next Step

After adding beneficiaries, proceed to **Phase 7: Payment Consent Setup**.

<Card title="Phase 7: Payment Consent Setup" icon="arrow-right" href="/baas/api/integration/flows/organization-customer/payment-consent-setup">
  Create payment consents with restrictions
</Card>


---

# Phase 7: Payment Consent Setup

Create payment consents with limits and beneficiary restrictions


URL: /baas/api/integration/flows/organization-customer/payment-consent-setup



# Phase 7: Payment Consent Setup

Payment consents define what transactions the organization can perform, including limits, allowed beneficiaries, and approval requirements.

## Consent Types

| Consent Type | Description |
|--------------|-------------|
| `TRANSFER` | Standard transfers to beneficiaries |
| `RECURRING` | Recurring/scheduled payments |
| `BULK` | Bulk payment processing |
| `INTERNATIONAL` | Cross-border transfers |

---

## Create Payment Consent

<Tabs>
  <Tab title="Request">
    **Endpoint:** `POST /api/v2.1/fintrans/{walletId}/payment-consents/types/transfer`

    **Headers:**
    ```http
    Authorization: Bearer {jwt-token}
    Content-Type: application/json
    ```

    **Request Body:**
    ```json
    {
      "title": "Regular Business Payments Consent",
      "description": "Monthly supplier and vendor payments",
      "validFrom": "2026-01-15T00:00:00.000Z",
      "validTo": "2026-12-31T23:59:59.000Z",
      "maxUsageCount": 500,
      "limits": {
        "perTransaction": {
          "amount": 10000000,
          "currency": "EUR"
        },
        "perDay": {
          "amount": 20000000,
          "currency": "EUR"
        },
        "perMonth": {
          "amount": 50000000,
          "currency": "EUR"
        }
      },
      "beneficiaryRestrictions": {
        "allowedAccounts": [
          "GB82WEST12345698765432",
          "FR7612345678901234567890123",
          "DE89370400440532013000"
        ],
        "allowedTypes": ["INTERNAL", "SEPA", "SWIFT"],
        "allowNewBeneficiaries": false,
        "requireBeneficiaryName": true,
        "requireInvoiceReference": true
      },
      "frequencyLimit": {
        "maxTransactionsPerDay": 50,
        "maxTransactionsPerWeek": 200,
        "maxTransactionsPerMonth": 500
      },
      "approvalRequirements": {
        "requiresApproval": true,
        "approvalThreshold": 5000000,
        "approverRoles": ["TRANSACTION_APPROVER", "ADMIN_USER"],
        "minimumApprovers": 1
      }
    }
    ```
  </Tab>
  <Tab title="Response">
    **Status:** `201 Created`

    ```json
    {
      "code": 201,
      "message": "Payment consent created successfully",
      "data": {
        "id": "consent-3344e8400-e29b-41d4-a716-446655440200",
        "consentType": "PAYMENT_CONSENT",
        "status": "ACCEPTED",
        "title": "Regular Business Payments Consent",
        "validFrom": "2026-01-15T00:00:00.000Z",
        "validTo": "2026-12-31T23:59:59.000Z",
        "maxUsageCount": 500,
        "currentUsageCount": 0,
        "limits": {
          "perTransaction": { "amount": 10000000, "currency": "EUR" },
          "perDay": { "amount": 20000000, "currency": "EUR" },
          "perMonth": { "amount": 50000000, "currency": "EUR" }
        },
        "beneficiaryRestrictions": {
          "allowedAccounts": [...],
          "allowNewBeneficiaries": false
        },
        "frequencyLimit": {
          "maxTransactionsPerDay": 50,
          "maxTransactionsPerWeek": 200,
          "maxTransactionsPerMonth": 500
        },
        "approvalRequirements": {
          "requiresApproval": true,
          "approvalThreshold": 5000000
        },
        "createdAt": "2026-01-15T15:30:00.000Z"
      }
    }
    ```
  </Tab>
</Tabs>

---

## Consent Limits

<Info>
  **Amount Format:** All amounts are in minor units (cents). Example: `10000000` = €100,000.00
</Info>

| Limit Type | Description |
|------------|-------------|
| `perTransaction` | Maximum amount per single transaction |
| `perDay` | Maximum total amount per day |
| `perMonth` | Maximum total amount per month |

---

## Beneficiary Restrictions

| Field | Description |
|-------|-------------|
| `allowedAccounts` | List of allowed beneficiary IBANs |
| `allowedTypes` | Allowed beneficiary types (INTERNAL, SEPA, SWIFT) |
| `allowNewBeneficiaries` | Allow payments to new beneficiaries |
| `requireBeneficiaryName` | Require beneficiary name verification |
| `requireInvoiceReference` | Require invoice reference for payments |

<Warning>
  When `allowNewBeneficiaries` is `false`, transactions to beneficiaries not in `allowedAccounts` will be rejected.
</Warning>

---

## Approval Requirements

| Field | Description |
|-------|-------------|
| `requiresApproval` | Enable approval workflow |
| `approvalThreshold` | Amount threshold for approval (in cents) |
| `approverRoles` | Roles that can approve |
| `minimumApprovers` | Minimum number of approvers required |

### Approval Workflow

```mermaid
flowchart LR
    A[Transaction Initiated] --> B{Amount > Threshold?}
    B -->|No| C[Auto-Approved]
    B -->|Yes| D[Pending Approval]
    D --> E{Approver Action}
    E -->|Approve| F[Executed]
    E -->|Reject| G[Rejected]
```

---

## Frequency Limits

| Limit | Description |
|-------|-------------|
| `maxTransactionsPerDay` | Max transactions in 24 hours |
| `maxTransactionsPerWeek` | Max transactions in 7 days |
| `maxTransactionsPerMonth` | Max transactions in 30 days |

---

## List Payment Consents

<Tabs>
  <Tab title="Request">
    **Endpoint:** `GET /api/v2.1/fintrans/{walletId}/payment-consents`
  </Tab>
  <Tab title="Response">
    ```json
    {
      "code": 200,
      "message": "Payment consents retrieved successfully",
      "data": [
        {
          "id": "consent-3344e8400-e29b-41d4-a716-446655440200",
          "title": "Regular Business Payments Consent",
          "status": "ACCEPTED",
          "validFrom": "2026-01-15T00:00:00.000Z",
          "validTo": "2026-12-31T23:59:59.000Z",
          "currentUsageCount": 5,
          "maxUsageCount": 500
        }
      ]
    }
    ```
  </Tab>
</Tabs>

---

## Next Step

After setting up payment consents, proceed to **Phase 8: Transaction Operations**.

<Card title="Phase 8: Transaction Operations" icon="arrow-right" href="/baas/api/integration/flows/organization-customer/transaction-operations">
  Execute transfers and manage transactions
</Card>


---

# Phase 8: Transaction Operations

Fund wallet, execute transfers, and manage high-value transactions


URL: /baas/api/integration/flows/organization-customer/transaction-operations



# Phase 8: Transaction Operations

The final phase covers transaction operations: funding the wallet, preparing transfers, executing payments, and handling high-value transactions with document requirements.

## Transaction Flow

```mermaid
flowchart LR
    A[Fund Wallet] --> B[Prepare Transfer]
    B --> C{High Value?}
    C -->|Yes| D[Upload Documents]
    C -->|No| E[Execute Transfer]
    D --> E
    E --> F[Monitor Status]
```

---

## Step 1: Fund Wallet (Topup)

<Tabs>
  <Tab title="Prepare Request">
    **Endpoint:** `POST /api/v2.1/fintrans/{accountId}/types/topup/prepare`

    **Request Body:**
    ```json
    {
      "sourceAccount": {
        "iban": "FR7612345678901234567890123",
        "accountHolder": "Acme Corporation Limited",
        "bic": "BNPAFRPP"
      },
      "targetAccount": {
        "walletId": "wallet-aa0e8400-e29b-41d4-a716-446655440120",
        "iban": "FR7630001007941234567890186"
      },
      "amount": {
        "value": "5000000",
        "currency": "EUR"
      },
      "description": "Initial wallet funding",
      "reference": "FUND-2026-001"
    }
    ```
  </Tab>
  <Tab title="Prepare Response">
    **Status:** `200 OK`

    ```json
    {
      "code": 200,
      "message": "Topup order prepared successfully",
      "data": {
        "preparedOrderId": "prep-4455e8400-e29b-41d4-a716-446655440210",
        "operationType": "TOPUP",
        "status": "PREPARED",
        "amount": {
          "value": "5000000",
          "valueFormatted": "50000.00",
          "currency": "EUR"
        },
        "fees": {
          "value": "0",
          "valueFormatted": "0.00",
          "currency": "EUR"
        },
        "totalAmount": {
          "value": "5000000",
          "valueFormatted": "50000.00",
          "currency": "EUR"
        },
        "estimatedExecutionTime": "2026-01-15T17:00:00.000Z",
        "validUntil": "2026-01-15T20:00:00.000Z"
      }
    }
    ```
  </Tab>
  <Tab title="Execute Request">
    **Endpoint:** `POST /api/v2.1/fintrans/{accountId}/types/topup/execute`

    **Request Body:**
    ```json
    {
      "preparedOrderId": "prep-4455e8400-e29b-41d4-a716-446655440210",
      "consentConfirmation": {
        "confirmed": true,
        "confirmationMethod": "EXPLICIT"
      }
    }
    ```
  </Tab>
  <Tab title="Execute Response">
    **Status:** `200 OK`

    ```json
    {
      "code": 200,
      "message": "Topup executed successfully",
      "data": {
        "executionId": "exec-5566e8400-e29b-41d4-a716-446655440220",
        "orderId": "order-6677e8400-e29b-41d4-a716-446655440221",
        "status": "EXECUTING",
        "estimatedCompletionTime": "2026-01-15T17:00:00.000Z"
      }
    }
    ```
  </Tab>
</Tabs>

---

## Step 2: High-Value Transfer with Documents

For transactions ≥ €10,000, supporting documents may be required.

### Upload Payment Document

<Tabs>
  <Tab title="Request">
    **Endpoint:** `POST /api/v2.1/fintrans/{walletId}/payment-documents`

    **Content-Type:** `multipart/form-data`

    **Form Data:**
    ```
    documentType: INVOICE
    file: [invoice_INV-2026-001.pdf]
    transactionReference: INV-2026-001
    amount: 15000.00
    currency: EUR
    beneficiaryName: Supplier Corporation Ltd
    description: Invoice payment for software licenses
    ```
  </Tab>
  <Tab title="Response">
    **Status:** `201 Created`

    ```json
    {
      "code": 201,
      "message": "Payment document uploaded successfully",
      "data": {
        "documentId": "doc-7788e8400-e29b-41d4-a716-446655440230",
        "transactionReference": "INV-2026-001",
        "status": "VERIFIED"
      }
    }
    ```
  </Tab>
</Tabs>

### Payment Document Types

| Document Type | Description |
|---------------|-------------|
| `INVOICE` | Supplier invoice |
| `CONTRACT` | Service contract |
| `PURCHASE_ORDER` | Purchase order |
| `PROFORMA` | Proforma invoice |
| `TAX_DOCUMENT` | Tax-related document |

---

## Step 3: Prepare Business Transfer

<Tabs>
  <Tab title="Request">
    **Endpoint:** `POST /api/v2.1/fintrans/{accountId}/types/transfer/prepare`

    **Request Body:**
    ```json
    {
      "sourceAccount": {
        "walletId": "wallet-aa0e8400-e29b-41d4-a716-446655440120",
        "iban": "FR7630001007941234567890186"
      },
      "targetAccount": {
        "iban": "GB82WEST12345698765432",
        "beneficiaryName": "Supplier Corporation Ltd",
        "bic": "WESTGB21"
      },
      "amount": {
        "value": "1500000",
        "currency": "EUR"
      },
      "description": "Invoice payment #INV-2026-001",
      "reference": "INV-2026-001",
      "paymentConsentId": "consent-3344e8400-e29b-41d4-a716-446655440200",
      "supportingDocuments": [
        "doc-7788e8400-e29b-41d4-a716-446655440230"
      ],
      "metadata": {
        "invoiceNumber": "INV-2026-001",
        "invoiceDate": "2026-01-10",
        "purchaseOrderNumber": "PO-2026-001",
        "contractReference": "CNT-2024-001"
      }
    }
    ```
  </Tab>
  <Tab title="Response">
    **Status:** `200 OK`

    ```json
    {
      "code": 200,
      "message": "Order prepared successfully",
      "data": {
        "preparedOrderId": "prep-8899e8400-e29b-41d4-a716-446655440240",
        "operationType": "TRANSFER",
        "status": "PREPARED",
        "amount": {
          "value": "1500000",
          "valueFormatted": "15000.00",
          "currency": "EUR"
        },
        "fees": {
          "value": "150",
          "valueFormatted": "1.50",
          "currency": "EUR"
        },
        "totalAmount": {
          "value": "1500150",
          "valueFormatted": "15001.50",
          "currency": "EUR"
        },
        "validUntil": "2026-01-15T20:00:00.000Z",
        "warnings": [],
        "requiredApprovals": [
          {
            "reason": "Amount exceeds approval threshold",
            "threshold": "5000000",
            "requiredRoles": ["TRANSACTION_APPROVER", "ADMIN_USER"]
          }
        ]
      }
    }
    ```
  </Tab>
</Tabs>

---

## Step 4: Execute Transfer

<Tabs>
  <Tab title="Request">
    **Endpoint:** `POST /api/v2.1/fintrans/{accountId}/types/transfer/execute`

    **Request Body:**
    ```json
    {
      "preparedOrderId": "prep-8899e8400-e29b-41d4-a716-446655440240",
      "consentConfirmation": {
        "confirmed": true,
        "confirmationMethod": "EXPLICIT",
        "confirmationTimestamp": "2026-01-15T16:00:00.000Z"
      }
    }
    ```
  </Tab>
  <Tab title="Response">
    **Status:** `200 OK`

    ```json
    {
      "code": 200,
      "message": "Order executed successfully",
      "data": {
        "executionId": "exec-9900e8400-e29b-41d4-a716-446655440250",
        "orderId": "order-0011e8400-e29b-41d4-a716-446655440251",
        "preparedOrderId": "prep-8899e8400-e29b-41d4-a716-446655440240",
        "status": "EXECUTING",
        "executionTimestamp": "2026-01-15T16:00:30.000Z",
        "estimatedCompletionTime": "2026-01-15T17:00:00.000Z",
        "transactionReference": "TXN-20260115-001",
        "confirmationNumber": "CNF-20260115-001"
      }
    }
    ```
  </Tab>
</Tabs>

---

## Order Status Flow

```mermaid
flowchart LR
    A[PREPARED] --> B{Approval Required?}
    B -->|No| C[EXECUTING]
    B -->|Yes| D[PENDING_APPROVAL]
    D --> E{Approved?}
    E -->|Yes| C
    E -->|No| F[REJECTED]
    C --> G{Outcome}
    G -->|Success| H[COMPLETED]
    G -->|Failure| I[FAILED]
```

---

## Get Order Status

<Tabs>
  <Tab title="Request">
    **Endpoint:** `GET /api/v2.1/fintrans/{accountId}/orders/{orderId}`
  </Tab>
  <Tab title="Response">
    ```json
    {
      "code": 200,
      "message": "Order retrieved successfully",
      "data": {
        "orderId": "order-0011e8400-e29b-41d4-a716-446655440251",
        "operationType": "TRANSFER",
        "status": "COMPLETED",
        "amount": "1500000",
        "amountFormatted": "15000.00",
        "currency": "EUR",
        "fees": "150",
        "feesFormatted": "1.50",
        "beneficiaryName": "Supplier Corporation Ltd",
        "beneficiaryIban": "GB82WEST12345698765432",
        "reference": "INV-2026-001",
        "transactionReference": "TXN-20260115-001",
        "createdAt": "2026-01-15T16:00:00.000Z",
        "executedAt": "2026-01-15T16:00:30.000Z",
        "completedAt": "2026-01-15T16:05:00.000Z"
      }
    }
    ```
  </Tab>
</Tabs>

---

## Fee Structure

| Transaction Type | Fee |
|------------------|-----|
| SEPA Transfer | €1.50 |
| SWIFT Transfer | €15.00 |
| Topup (Incoming) | Free |
| Internal Transfer | Free |
| Bulk Payment (per item) | €0.50 |

---

## Complete B2B Flow Summary

```
┌─────────────────────────────────────────────────────────────┐
│ ORGANIZATION CUSTOMER COMPLETE LIFECYCLE                     │
└─────────────────────────────────────────────────────────────┘

Phase 1: Registration (10 min)
  └─→ Organization + Default Admin created

Phase 2: Personnel (20 min)
  └─→ Directors, Shareholders, Employees added

Phase 3: Verification (2-5 days)
  └─→ KYB documents submitted and approved

Phase 4: Consents (10 min)
  └─→ Organization consents with authorized signatory

Phase 5: Activation (instant)
  └─→ Role validation, IBAN generated, wallet activated

Phase 6: Beneficiaries (ongoing)
  └─→ Business beneficiaries with due diligence

Phase 7: Payment Consent (5 min)
  └─→ Consent with limits and restrictions

Phase 8: Transactions (ongoing)
  └─→ Topup, transfers, payments with documents
```

---

## Related Resources

<CardGroup cols={2}>
  <Card title="Error Handling" icon="triangle-exclamation" href="/baas/api/integration/flows/common/error-handling">
    Common errors and troubleshooting
  </Card>
  <Card title="Best Practices" icon="lightbulb" href="/baas/api/integration/flows/common/best-practices">
    Implementation best practices
  </Card>
</CardGroup>


---

# Error Handling

Common error scenarios and troubleshooting guide


URL: /baas/api/integration/flows/common/error-handling



# Error Handling

Comprehensive guide to handling errors across the customer lifecycle flows.

## Error Response Format

All API errors follow a consistent format:

```json
{
  "code": 400,
  "message": "Human-readable error message",
  "data": {
    "error": "Error type",
    "details": "Detailed explanation",
    "field": "Affected field (if applicable)",
    "suggestions": ["Suggested fix 1", "Suggested fix 2"]
  }
}
```

---

## HTTP Status Codes

| Code | Description | Common Causes |
|------|-------------|---------------|
| `400` | Bad Request | Validation errors, missing fields |
| `401` | Unauthorized | Invalid/expired token, wrong credentials |
| `403` | Forbidden | Insufficient permissions, role mismatch |
| `404` | Not Found | Resource doesn't exist |
| `409` | Conflict | Duplicate resource, state conflict |
| `422` | Unprocessable Entity | Business rule violation |
| `429` | Too Many Requests | Rate limit exceeded |
| `500` | Internal Server Error | Server-side error |

---

## Registration Errors

### Password Mismatch (400)

```json
{
  "code": 400,
  "message": "Request validation failed",
  "data": {
    "errors": [
      {
        "field": "matchingPassword",
        "message": "Password and matching password must be identical"
      }
    ]
  }
}
```

**Solution:** Ensure `password` and `matchingPassword` fields contain identical values.

---

### Invalid Categorization (400)

```json
{
  "code": 400,
  "message": "Categorization validation failed",
  "data": {
    "error": "Invalid categorization",
    "details": "Feature 'ENHANCED_AML_MONITORING' requires mandatory key 'riskLevel'",
    "missingKeys": ["riskLevel"],
    "invalidValues": {
      "monitoring": "HOURLY is not in allowed values: [WEEKLY, DAILY, REAL_TIME]"
    }
  }
}
```

**Solution:**
1. Call `GET /categorization/hierarchy/{tenantId}` to get available options
2. Check `mandatoryKeys` for the feature
3. Ensure all mandatory keys are provided
4. Validate values against `allowedValues`

---

### Tenant Access Denied (403)

```json
{
  "code": 403,
  "message": "Tenant access denied or categorization not available",
  "data": {
    "error": "Tenant access denied",
    "tenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd"
  }
}
```

**Solution:** Verify the `X-Tenant-ID` header matches your assigned tenant and that categorization is enabled for your tenant.

---

### Organization Already Exists (409)

```json
{
  "code": 409,
  "message": "Organization already exists",
  "data": {
    "error": "Duplicate organization",
    "registrationNumber": "REG123456789",
    "existingOrganizationId": "org-880e8400..."
  }
}
```

**Solution:** Use a unique registration number or retrieve the existing organization.

---

## Authentication Errors

### Invalid Credentials (401)

```json
{
  "code": 401,
  "message": "Authentication failed",
  "data": {
    "success": false,
    "errorType": "AUTHENTICATION",
    "message": "Invalid username or password",
    "attempts": 3,
    "maxAttempts": 5,
    "lockoutTime": null
  }
}
```

**Solution:** Verify username (email) and password are correct.

---

### Account Locked (401)

```json
{
  "code": 401,
  "message": "Account locked",
  "data": {
    "success": false,
    "errorType": "AUTHENTICATION",
    "message": "Account locked due to multiple failed login attempts",
    "attempts": 5,
    "maxAttempts": 5,
    "lockoutTime": "2026-01-13T11:30:00.000Z",
    "lockoutDuration": "30 minutes"
  }
}
```

**Solution:** Wait for lockout period to expire (30 minutes) or contact support.

---

### Token Expired (401)

```json
{
  "code": 401,
  "message": "Token expired",
  "data": {
    "error": "JWT_EXPIRED",
    "expiredAt": "2026-01-13T12:00:00.000Z"
  }
}
```

**Solution:** Obtain a new token via the session creation endpoint.

---

## Verification Errors

### Insufficient Permission (403)

```json
{
  "code": 403,
  "message": "Access denied: Only COMPLIANCE_OFFICER or ADMIN_USER can initiate verification",
  "data": {
    "userId": "user-660e8400...",
    "currentRoles": ["EMPLOYEE", "TRANSACTION_APPROVER"],
    "requiredRoles": ["COMPLIANCE_OFFICER", "ADMIN_USER"]
  }
}
```

**Solution:** Use an account with `COMPLIANCE_OFFICER` or `ADMIN_USER` role.

---

## Activation Errors

### Missing Consents (400)

```json
{
  "code": 400,
  "message": "Missing required consents",
  "data": {
    "activationStatus": "CONSENT_REQUIRED",
    "customerId": "cust-550e8400...",
    "missingConsentTypes": ["PRIVACY_POLICY", "DATA_PROCESSING"],
    "missingConsentDetails": {
      "PRIVACY_POLICY": {
        "consentType": "PRIVACY_POLICY",
        "status": "MISSING",
        "acceptUrl": "/api/v2.1/customer/individual/{customerId}/consents/privacy"
      }
    },
    "totalRequiredConsents": 3,
    "totalMissingConsents": 2,
    "nextSteps": [
      "Accept Privacy Policy",
      "Accept Data Processing Agreement",
      "Retry activation"
    ]
  }
}
```

**Solution:** Accept all missing consents using the provided `acceptUrl` endpoints.

---

### Not Verified (422)

```json
{
  "code": 422,
  "message": "Customer not verified",
  "data": {
    "activationStatus": "VERIFICATION_REQUIRED",
    "verificationStatus": "PENDING_REVIEW",
    "reason": "Customer verification must be APPROVED before activation",
    "estimatedCompletionTime": "1-2 business days"
  }
}
```

**Solution:** Wait for verification to be approved before attempting activation.

---

### Missing ADMIN_USER Role (400)

```json
{
  "code": 400,
  "message": "Missing required role 'ADMIN_USER' for BUSINESS_TYPE_CLIENT_TO_TENANT organization. At least one employee must have this role."
}
```

**Solution:** Ensure the first employee added has the `ADMIN_USER` role.

---

## Transaction Errors

### Insufficient Balance (400)

```json
{
  "code": 400,
  "message": "Insufficient balance",
  "data": {
    "availableBalance": "100000",
    "requestedAmount": "150000",
    "currency": "EUR"
  }
}
```

**Solution:** Top up the wallet or reduce the transaction amount.

---

### Limit Exceeded (400)

```json
{
  "code": 400,
  "message": "Transaction limit exceeded",
  "data": {
    "limitType": "DAILY",
    "limit": "5000",
    "currentUsage": "4500",
    "requestedAmount": "1000",
    "currency": "EUR"
  }
}
```

**Solution:** Wait for limit reset or use a smaller amount.

---

### Beneficiary Not Found (404)

```json
{
  "code": 404,
  "message": "Beneficiary not found",
  "data": {
    "iban": "GB82WEST12345698765432",
    "suggestion": "Add beneficiary before making transfer"
  }
}
```

**Solution:** Add the beneficiary using the beneficiaries endpoint before attempting the transfer.

---

## Troubleshooting Checklist

### Registration Issues

- [ ] Valid email format
- [ ] Password meets requirements (8+ chars, mixed case, numbers, special)
- [ ] `password` matches `matchingPassword`
- [ ] Valid tenant ID in header
- [ ] Categorization values match allowed values

### Authentication Issues

- [ ] Correct username (email)
- [ ] Correct password
- [ ] Valid tenant key and secret
- [ ] Account not locked
- [ ] Token not expired

### Activation Issues

- [ ] Verification status is `APPROVED`
- [ ] All three consents accepted (Terms, Privacy, Data Processing)
- [ ] Customer not already active
- [ ] For B2B: At least one employee with `ADMIN_USER` role

### Transaction Issues

- [ ] Wallet is `ACTIVE`
- [ ] Sufficient balance
- [ ] Within transaction limits
- [ ] Beneficiary exists and is active
- [ ] Valid payment consent in place

---

## Error Handling Best Practices

1. **Parse error responses** - Always check the `data` object for detailed information
2. **Handle retries carefully** - Don't retry on 400/403/422 errors
3. **Log error details** - Store `code`, `message`, and `data` for debugging
4. **Show user-friendly messages** - Map technical errors to user-friendly text
5. **Implement exponential backoff** - For 429 and 500 errors


---

# Best Practices

Implementation best practices for registration, verification, and activation


URL: /baas/api/integration/flows/common/best-practices



# Best Practices

Follow these best practices to ensure smooth integration with the FinHub API.

## Registration Best Practices

### ✅ DO

| Practice | Description |
|----------|-------------|
| **Call categorization hierarchy first** | Always retrieve available categories before registration |
| **Build parametrization correctly** | Match feature requirements exactly |
| **Use strong passwords** | Min 12 chars, mixed case, numbers, symbols |
| **Store IDs securely** | Save customer ID and user ID for future calls |
| **Validate email format** | Check email format before submission |
| **Handle duplicates** | Check for existing customers before creating new ones |

### ❌ DON'T

| Anti-Pattern | Issue |
|--------------|-------|
| Hardcode category IDs | IDs may vary across environments |
| Skip categorization validation | Leads to registration failures |
| Use weak passwords | Will be rejected by validation |
| Expose credentials in logs | Security risk |
| Submit duplicate emails | Will cause conflicts |
| Ignore error responses | Miss important validation feedback |

---

## Session Management Best Practices

### Token Handling

```javascript
// Good: Store token securely and check expiry
const tokenData = {
  token: response.data.token,
  expiresAt: Date.now() + (response.data.expiresIn * 1000),
  refreshToken: response.data.refreshToken
};

function isTokenValid() {
  return Date.now() < tokenData.expiresAt - 60000; // 1 min buffer
}

async function getValidToken() {
  if (!isTokenValid()) {
    await refreshToken();
  }
  return tokenData.token;
}
```

### Session Security

- **Never store tokens in localStorage** for sensitive applications
- **Use httpOnly cookies** when possible
- **Implement token refresh** before expiry
- **Clear tokens on logout** from all storage

---

## Verification Best Practices

### ✅ DO

| Practice | Description |
|----------|-------------|
| **Submit high-quality images** | Clear, well-lit document photos |
| **Check document expiry** | Ensure documents are not expired |
| **Provide all required documents** | Check `requiredDocuments` array |
| **Keep customer informed** | Show verification status updates |
| **Monitor progress** | Poll status endpoint periodically |
| **Handle rejection gracefully** | Allow document resubmission |

### ❌ DON'T

| Anti-Pattern | Issue |
|--------------|-------|
| Submit blurry images | Will be rejected |
| Use expired documents | Verification will fail |
| Skip required document types | Incomplete verification |
| Assume immediate approval | High-risk may take 1-3 days |
| Retry failed verification endlessly | Wait for guidance |

### Document Quality Guidelines

| Requirement | Standard |
|-------------|----------|
| **Resolution** | Min 300 DPI |
| **Format** | JPEG, PNG, or PDF |
| **Size** | Max 5 MB per document |
| **Clarity** | All text must be readable |
| **Completeness** | All corners visible |

---

## Consent Management Best Practices

### ✅ DO

| Practice | Description |
|----------|-------------|
| **Accept all three consents** | Terms, Privacy, Data Processing |
| **Record acceptance metadata** | IP, timestamp, user agent |
| **Store consent versions** | Track which version was accepted |
| **Handle consent expiry** | Re-prompt when consents expire |

### Consent Acceptance Pattern

```javascript
async function acceptAllConsents(customerId) {
  const consents = ['terms', 'privacy', 'data-processing'];
  const results = [];
  
  for (const type of consents) {
    const result = await acceptConsent(customerId, type, {
      accepted: true,
      version: '1.0',
      acceptanceTimestamp: new Date().toISOString()
    });
    results.push(result);
  }
  
  return results;
}
```

---

## Activation Best Practices

### Pre-Activation Checklist

```javascript
async function canActivate(customerId, tenantId) {
  const checks = {
    verification: await checkVerificationStatus(customerId),
    termsConsent: await checkConsent(customerId, 'TERMS_AND_CONDITIONS'),
    privacyConsent: await checkConsent(customerId, 'PRIVACY_POLICY'),
    dataConsent: await checkConsent(customerId, 'DATA_PROCESSING')
  };
  
  const allPassed = 
    checks.verification === 'APPROVED' &&
    checks.termsConsent === 'ACCEPTED' &&
    checks.privacyConsent === 'ACCEPTED' &&
    checks.dataConsent === 'ACCEPTED';
  
  return {
    canActivate: allPassed,
    checks: checks,
    missing: Object.entries(checks)
      .filter(([_, v]) => v !== 'APPROVED' && v !== 'ACCEPTED')
      .map(([k, _]) => k)
  };
}
```

### ✅ DO

| Practice | Description |
|----------|-------------|
| **Verify all prerequisites** | Check before attempting activation |
| **Handle activation errors** | Parse error response for missing items |
| **Inform customer of success** | Send confirmation notification |
| **Store wallet details** | Save IBAN and wallet ID |

### ❌ DON'T

| Anti-Pattern | Issue |
|--------------|-------|
| Attempt activation without verification | Will fail with 422 |
| Skip consent acceptance | Will fail with 400 |
| Retry activation repeatedly | Don't retry without fixing issues |
| Expose sensitive data in errors | Log internally only |

---

## Transaction Best Practices

### Order Lifecycle

```mermaid
flowchart LR
    A[Prepare] --> B{Valid?}
    B -->|Yes| C[Execute]
    B -->|No| D[Fix Issues]
    C --> E[Monitor]
    E --> F{Complete?}
    F -->|Yes| G[Done]
    F -->|No| E
```

### ✅ DO

| Practice | Description |
|----------|-------------|
| **Pre-register beneficiaries** | Add beneficiaries before transfers |
| **Use prepare/execute pattern** | Always prepare before executing |
| **Check limits before transfer** | Verify against daily/monthly limits |
| **Implement idempotency** | Use unique references per transaction |
| **Monitor order status** | Track until COMPLETED or FAILED |

### ❌ DON'T

| Anti-Pattern | Issue |
|--------------|-------|
| Execute without prepare | Missing fee calculation |
| Ignore order expiry | Prepared orders expire after 2-3 hours |
| Retry failed orders blindly | May cause duplicate transactions |
| Skip beneficiary validation | PEP/sanctions check required |

---

## API Integration Patterns

### Retry Strategy

```javascript
async function apiCallWithRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429) {
        // Rate limited - exponential backoff
        await sleep(Math.pow(2, i) * 1000);
        continue;
      }
      if (error.status >= 500) {
        // Server error - retry with backoff
        await sleep(Math.pow(2, i) * 1000);
        continue;
      }
      // Client error (4xx) - don't retry
      throw error;
    }
  }
  throw new Error('Max retries exceeded');
}
```

### Idempotency

```javascript
// Generate unique reference for each transaction
function generateReference(prefix, customerId) {
  const timestamp = Date.now();
  const random = Math.random().toString(36).substring(2, 8);
  return `${prefix}-${customerId.slice(-8)}-${timestamp}-${random}`;
}

// Example: TXN-550e8400-1705315200000-a1b2c3
```

---

## Security Best Practices

| Area | Recommendation |
|------|----------------|
| **API Keys** | Store in environment variables, never in code |
| **Tokens** | Use short-lived access tokens with refresh |
| **Passwords** | Never log or store in plain text |
| **PII Data** | Encrypt at rest and in transit |
| **Error Messages** | Don't expose internal details to users |
| **Audit Logging** | Log all API calls with sanitized data |

---

## Performance Best Practices

| Area | Recommendation |
|------|----------------|
| **Batch Operations** | Use bulk endpoints where available |
| **Caching** | Cache categorization hierarchy |
| **Pagination** | Use pagination for list endpoints |
| **Async Processing** | Don't block on long operations |
| **Connection Pooling** | Reuse HTTP connections |


---

# Categorization Hierarchy

Smart categorization strategy for customer risk classification


URL: /baas/api/integration/flows/common/categorization-hierarchy



# Categorization Hierarchy

Categorization is a feature-based system for classifying customers based on risk level and enabling appropriate monitoring and limits.

## Overview

```mermaid
flowchart TD
    A[Tenant] --> B[Categories]
    B --> C[HIGH_RISK_INDIVIDUAL]
    B --> D[STANDARD_INDIVIDUAL]
    B --> E[MEDIUM_RISK_BUSINESS]
    C --> F[Features]
    D --> F
    E --> F
    F --> G[ENHANCED_AML_MONITORING]
    F --> H[TRANSACTION_LIMITS]
    F --> I[INTERNATIONAL_PAYMENTS]
```

---

## Get Categorization Hierarchy

Before registration, retrieve available categories and features.

<Tabs>
  <Tab title="Request">
    **Endpoint:** `GET /api/v2.1/customer/individual/categorization/hierarchy/{tenantId}`

    **Headers:**
    ```http
    Authorization: Bearer {admin-jwt-token}
    X-Tenant-ID: fh_api_finsei_ltd_7f957f77
    ```
  </Tab>
  <Tab title="Response">
    ```json
    {
      "code": 200,
      "message": "Hierarchy retrieved successfully",
      "data": {
        "tenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
        "tenantName": "Finsei Ltd",
        "complianceLevel": "ENHANCED",
        "categories": {
          "HIGH_RISK_INDIVIDUAL": {
            "databaseId": "550e8400-e29b-41d4-a716-446655440001",
            "categoryId": "HIGH_RISK_INDIVIDUAL",
            "categoryName": "High Risk Individual Customer",
            "description": "High-risk customers requiring enhanced monitoring",
            "availableFeatures": [
              {
                "databaseId": "660e8400-e29b-41d4-a716-446655440002",
                "featureCode": "ENHANCED_AML_MONITORING",
                "featureName": "Enhanced AML Monitoring",
                "mandatoryKeys": [
                  "riskLevel",
                  "riskScore",
                  "pep",
                  "sanctionsCheck",
                  "monitoring",
                  "edd"
                ],
                "allowedValues": {
                  "riskLevel": ["LOW", "MEDIUM", "HIGH", "CRITICAL"],
                  "riskScore": ["0-100"],
                  "pep": ["true", "false"],
                  "pepCategory": ["DOMESTIC_PEP", "FOREIGN_PEP", "RCA", "HIO"],
                  "sanctionsCheck": ["STANDARD", "ENHANCED", "REAL_TIME"],
                  "monitoring": ["WEEKLY", "DAILY", "REAL_TIME"],
                  "edd": ["true", "false"]
                },
                "multiValueKeys": ["pepCategory"]
              }
            ]
          },
          "STANDARD_INDIVIDUAL": {
            "databaseId": "550e8400-e29b-41d4-a716-446655440010",
            "categoryId": "STANDARD_INDIVIDUAL",
            "categoryName": "Standard Individual Customer"
          }
        },
        "features": {
          "ENHANCED_AML_MONITORING": {
            "databaseId": "660e8400-e29b-41d4-a716-446655440002",
            "featureCode": "ENHANCED_AML_MONITORING",
            "featureName": "Enhanced AML Monitoring",
            "description": "Real-time transaction monitoring and enhanced due diligence"
          },
          "TRANSACTION_LIMITS": {
            "databaseId": "770e8400-e29b-41d4-a716-446655440003",
            "featureCode": "TRANSACTION_LIMITS",
            "featureName": "Transaction Limits"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

---

## Category Types

### Individual (B2C) Categories

| Category | Description | Approval Level |
|----------|-------------|----------------|
| `HIGH_RISK_INDIVIDUAL` | PEP, high-risk countries, high volume | POWER_TENANT |
| `STANDARD_INDIVIDUAL` | Standard customers | TENANT |
| `LOW_RISK_INDIVIDUAL` | Low-risk, verified customers | TENANT |

### Organization (B2B) Categories

| Category | Description | Approval Level |
|----------|-------------|----------------|
| `HIGH_RISK_BUSINESS` | PEP involvement, high-risk industry | POWER_TENANT |
| `MEDIUM_RISK_BUSINESS` | Standard business operations | TENANT |
| `LOW_RISK_BUSINESS` | Regulated, low-risk industry | TENANT |

---

## Feature Configuration

### ENHANCED_AML_MONITORING

For high-risk customers requiring enhanced monitoring.

| Key | Required | Allowed Values |
|-----|----------|----------------|
| `riskLevel` | ✅ | LOW, MEDIUM, HIGH, CRITICAL |
| `riskScore` | ✅ | 0-100 (numeric) |
| `pep` | ✅ | true, false |
| `pepCategory` | Conditional | DOMESTIC_PEP, FOREIGN_PEP, RCA, HIO |
| `sanctionsCheck` | ✅ | STANDARD, ENHANCED, REAL_TIME |
| `monitoring` | ✅ | WEEKLY, DAILY, REAL_TIME |
| `edd` | ✅ | true, false |
| `transactionMonitoring` | Optional | BATCH_DAILY, REAL_TIME |

**Example Configuration:**
```json
{
  "feature": {
    "id": "660e8400-e29b-41d4-a716-446655440002",
    "code": "ENHANCED_AML_MONITORING"
  },
  "enabled": true,
  "parametrization": [
    { "name": "riskLevel", "value": "HIGH" },
    { "name": "riskScore", "value": "85" },
    { "name": "pep", "value": "true" },
    { "name": "pepCategory", "value": "DOMESTIC_PEP" },
    { "name": "sanctionsCheck", "value": "ENHANCED" },
    { "name": "monitoring", "value": "DAILY" },
    { "name": "edd", "value": "true" },
    { "name": "transactionMonitoring", "value": "REAL_TIME" }
  ]
}
```

---

### TRANSACTION_LIMITS

Define transaction limits for the customer.

| Key | Required | Description |
|-----|----------|-------------|
| `dailyLimit` | ✅ | Maximum daily transaction amount |
| `monthlyLimit` | ✅ | Maximum monthly transaction amount |
| `singleTransactionLimit` | ✅ | Maximum single transaction amount |

**Example Configuration:**
```json
{
  "feature": {
    "id": "770e8400-e29b-41d4-a716-446655440003",
    "code": "TRANSACTION_LIMITS"
  },
  "enabled": true,
  "parametrization": [
    { "name": "dailyLimit", "value": "5000" },
    { "name": "monthlyLimit", "value": "50000" },
    { "name": "singleTransactionLimit", "value": "2000" }
  ]
}
```

---

### INTERNATIONAL_PAYMENTS (B2B)

Enable international payment capabilities.

| Key | Required | Description |
|-----|----------|-------------|
| `swiftEnabled` | ✅ | Enable SWIFT transfers |
| `sepaEnabled` | ✅ | Enable SEPA transfers |
| `crossBorderLimit` | ✅ | Cross-border transaction limit |

**Example Configuration:**
```json
{
  "feature": {
    "id": "org-feat-770e8400-e29b-41d4-a716-446655440102",
    "code": "INTERNATIONAL_PAYMENTS"
  },
  "enabled": true,
  "parametrization": [
    { "name": "swiftEnabled", "value": "true" },
    { "name": "sepaEnabled", "value": "true" },
    { "name": "crossBorderLimit", "value": "50000" }
  ]
}
```

---

## Smart Categorization Strategy

### High-Risk Customer Criteria

Assign `HIGH_RISK_INDIVIDUAL` or `HIGH_RISK_BUSINESS` when:

- ✅ Customer is a PEP (Politically Exposed Person)
- ✅ High transaction volume expected (>€50k/month)
- ✅ High-risk occupation or industry
- ✅ High-risk country of residence/nationality
- ✅ Sanctions list check required
- ✅ Complex ownership structure (B2B)

### Standard Customer Criteria

Assign `STANDARD_INDIVIDUAL` or `MEDIUM_RISK_BUSINESS` when:

- ✅ No PEP involvement
- ✅ Standard transaction volume
- ✅ Low-risk occupation or industry
- ✅ Low-risk country
- ✅ Simple ownership structure (B2B)

---

## Validation Process

```mermaid
flowchart TD
    A[Registration Request] --> B{Categorization Provided?}
    B -->|No| C[Use Default Category]
    B -->|Yes| D[Validate Category Exists]
    D --> E{Valid Category?}
    E -->|No| F[Return 400 Error]
    E -->|Yes| G[Validate Features]
    G --> H{All Mandatory Keys?}
    H -->|No| F
    H -->|Yes| I{Valid Values?}
    I -->|No| F
    I -->|Yes| J[Store Categorization]
    J --> K[Registration Success]
```

### Validation Rules

1. **Category must exist** in tenant hierarchy
2. **All mandatory keys** must be provided for each feature
3. **Values must match** allowed values
4. **Multi-value keys** can have multiple values (comma-separated)

---

## Common Validation Errors

### Missing Mandatory Key

```json
{
  "code": 400,
  "message": "Categorization validation failed",
  "data": {
    "error": "Missing mandatory key 'riskLevel'",
    "feature": "ENHANCED_AML_MONITORING",
    "missingKeys": ["riskLevel"]
  }
}
```

### Invalid Value

```json
{
  "code": 400,
  "message": "Categorization validation failed",
  "data": {
    "error": "Invalid value for key 'monitoring'",
    "feature": "ENHANCED_AML_MONITORING",
    "invalidValues": {
      "monitoring": "HOURLY is not in allowed values: [WEEKLY, DAILY, REAL_TIME]"
    }
  }
}
```

---

## Best Practices

1. **Always call hierarchy endpoint first** - Get current categories and features
2. **Don't hardcode IDs** - IDs may differ across environments
3. **Validate locally before submission** - Check mandatory keys and values
4. **Use appropriate risk levels** - Match customer profile to category
5. **Document categorization decisions** - Keep audit trail


---

# Testing & Certification

Complete testing and certification before going live


URL: /baas/api/certification



# Testing & Certification

Before transitioning to production, you must complete testing and pass FinHub's certification process.

## Certification Flow

```mermaid
flowchart LR
    A[Security Review] --> B[Performance Testing]
    B --> C[Compliance Validation]
    C --> D[Certification Approval]
```

## Certification Checklist

<Steps>
  <Step title="Pass Security Review">
    Complete security assessment and remediate findings
  </Step>
  <Step title="Performance Testing">
    Validate performance under expected load
  </Step>
  <Step title="Compliance Validation">
    Confirm regulatory compliance requirements
  </Step>
  <Step title="Final Review">
    FinHub team reviews and approves certification
  </Step>
</Steps>

## Requirements

| Area | Requirements |
|------|--------------|
| **Functional** | All integration flows tested |
| **Security** | Auth, encryption, data protection |
| **Performance** | Response times, throughput |
| **Compliance** | KYC/AML, data protection |
| **Operations** | Monitoring, alerting |

## Timeline

| Phase | Duration |
|-------|----------|
| Security Review | 2-3 days |
| Performance Testing | 1-2 days |
| Compliance Validation | 2-3 days |
| Final Review | 1-2 days |
| **Total** | **1-2 weeks** |

## Next Steps

<CardGroup cols={3}>
  <Card title="Security Review" icon="shield" href="/baas/api/certification/security-review">
    Security requirements
  </Card>
  <Card title="Performance" icon="gauge-high" href="/baas/api/certification/performance-testing">
    Performance benchmarks
  </Card>
  <Card title="Compliance" icon="balance-scale" href="/baas/api/certification/compliance-validation">
    Compliance checklist
  </Card>
</CardGroup>


---

# Security Review

Security requirements for certification


URL: /baas/api/certification/security-review



# Security Review

Your integration must meet FinHub's security requirements before production access.

## Security Checklist

### Authentication & Authorization

| Requirement | Description |
|-------------|-------------|
| Token Storage | Tokens stored securely (not in localStorage) |
| Token Refresh | Proper token refresh implementation |
| Session Management | Secure session handling |
| Credential Protection | Client secrets not exposed |

### Data Protection

| Requirement | Description |
|-------------|-------------|
| TLS/HTTPS | All communications over HTTPS |
| Data Encryption | Sensitive data encrypted at rest |
| PII Handling | Personal data handled per GDPR |
| Data Minimization | Only necessary data collected |

### API Security

| Requirement | Description |
|-------------|-------------|
| Input Validation | All inputs validated |
| Rate Limiting | Client-side rate limiting |
| Error Handling | Errors don't expose sensitive info |

## Common Security Issues

1. **Storing tokens in localStorage** - Use secure HTTP-only cookies
2. **Exposing client secrets** - Keep secrets server-side only
3. **Logging sensitive data** - Never log passwords, tokens, or PII
4. **Hardcoding credentials** - Use environment variables

## Security Assessment Process

1. **Self-Assessment** - Complete the security checklist
2. **Submit Documentation** - Provide security architecture docs
3. **FinHub Review** - Security team reviews submission
4. **Remediation** - Address any findings
5. **Approval** - Receive security clearance


---

# Performance Testing

Performance requirements for certification


URL: /baas/api/certification/performance-testing



# Performance Testing

Validate your integration meets performance requirements before production.

## Performance Benchmarks

| Metric | Requirement |
|--------|-------------|
| **Response Time** | < 2 seconds for 95th percentile |
| **Throughput** | Handle expected transaction volume |
| **Error Rate** | < 0.1% under normal load |
| **Availability** | 99.9% uptime capability |

## Testing Scenarios

### Load Testing

- Simulate expected peak traffic
- Verify response times under load
- Check resource utilization

### Stress Testing

- Push beyond normal limits
- Identify breaking points
- Verify graceful degradation

### Endurance Testing

- Sustained load over time
- Check for memory leaks
- Verify consistent performance

## Performance Checklist

- [ ] Response times within SLA
- [ ] Error handling under load
- [ ] Connection pooling configured
- [ ] Retry logic implemented
- [ ] Timeout handling proper

## Recommended Tools

- Apache JMeter
- k6
- Locust
- Artillery

## Submission

Provide performance test results including:
- Test scenarios and scripts
- Results summary
- Load profiles used
- Environment details


---

# Compliance Validation

Regulatory compliance requirements


URL: /baas/api/certification/compliance-validation



# Compliance Validation

Ensure your integration meets regulatory compliance requirements.

## Compliance Areas

### KYC/AML Compliance

| Requirement | Description |
|-------------|-------------|
| Customer Identification | Verify customer identity |
| Due Diligence | Risk-based due diligence |
| Ongoing Monitoring | Transaction monitoring |
| Suspicious Activity | SAR reporting capability |

### Data Protection (GDPR)

| Requirement | Description |
|-------------|-------------|
| Data Minimization | Collect only needed data |
| Purpose Limitation | Use data for stated purposes |
| Storage Limitation | Retention policies |
| Right to Erasure | Deletion capability |

### Financial Regulations

| Requirement | Description |
|-------------|-------------|
| Transaction Limits | Enforce applicable limits |
| Audit Trail | Complete transaction history |
| Regulatory Reporting | Required reports |

## Compliance Checklist

- [ ] KYC/KYB flows implemented
- [ ] AML screening integrated
- [ ] Data protection policies documented
- [ ] Audit logging enabled
- [ ] Consent management implemented
- [ ] Retention policies defined

## Documentation Required

1. **Data Flow Diagram** - How data moves through your system
2. **Privacy Policy** - End-user privacy documentation
3. **Security Policies** - Internal security procedures
4. **Incident Response Plan** - Breach handling procedures

## Validation Process

1. Submit compliance documentation
2. FinHub compliance team review
3. Address any gaps
4. Receive compliance approval


---

# Go-Live Process

A comprehensive guide to transitioning from sandbox to production


URL: /baas/api/production



# Go-Live Process

Moving from sandbox to production involves several important steps to ensure a smooth transition. This guide outlines the process, requirements, and best practices for going live with your FinHub integration.

## Overview

The go-live process is designed to ensure that your integration is secure, compliant, and ready for production use. It involves a series of checks and approvals to verify that your implementation meets our standards and regulatory requirements.

## Prerequisites

Before starting the go-live process, ensure you have:

- Completed all development and testing in the sandbox environment
- Implemented all required features and functionality
- Addressed any issues identified during testing
- Prepared documentation of your integration

## Go-Live Steps

### 1. Integration Completion

Finish all development and testing in the sandbox environment:

- Testing all API endpoints and functionality
- Implementing error handling and recovery mechanisms
- Ensuring your integration works with all required features
- Conducting thorough user acceptance testing

### 2. Compliance Review

Submit your integration for a compliance review:

- Adherence to API usage guidelines
- Implementation of required security measures
- Proper handling of sensitive data
- Compliance with relevant industry standards

### 3. Security Audit

Pass a security assessment of your integration:

- Penetration testing
- Vulnerability assessment
- Authentication and authorization review
- Data encryption verification

### 4. Production Credentials

Once all reviews are passed, receive production credentials:

- Production API keys
- Access to production dashboards
- Production webhook endpoints
- Support contact information

### 5. Gradual Rollout

Implement a phased approach to production deployment:

- Start with a limited user base
- Monitor system performance
- Gradually increase usage
- Establish clear rollback procedures

## Pre-Launch Checklist

| Category | Item | Status |
|----------|------|--------|
| **Certification** | All test scenarios passed | ☐ |
| **Certification** | Security review approved | ☐ |
| **Certification** | Compliance validated | ☐ |
| **Technical** | Production credentials received | ☐ |
| **Technical** | Production endpoints configured | ☐ |
| **Technical** | Monitoring configured | ☐ |
| **Operations** | Support team trained | ☐ |
| **Operations** | Incident response plan ready | ☐ |

## Phased Rollout Strategy

```mermaid
graph TD
    A[Phase 1: Internal Testing] -->|1-2 Weeks| B[Phase 2: Limited Beta]
    B -->|2-4 Weeks| C[Phase 3: Expanded Beta]
    C -->|2-4 Weeks| D[Phase 4: Full Launch]
```

## Regulatory Considerations

<Warning>
Financial services are highly regulated. Depending on your jurisdiction, additional regulatory requirements may apply before going live.
</Warning>

| Region | Key Regulations |
|--------|-----------------|
| **European Union** | GDPR, PSD2, MiFID II |
| **United States** | KYC/AML, state-specific regulations |
| **Asia-Pacific** | Varies by country |
| **Global** | FATF recommendations, sanctions compliance |

## Production Resources

<CardGroup cols={2}>
  <Card title="Production Setup" icon="server" href="/baas/api/production/production-setup">
    Configure production environment
  </Card>
  <Card title="Authentication" icon="key" href="/baas/api/production/production-auth">
    Production authentication
  </Card>
  <Card title="Monitoring" icon="chart-line" href="/baas/api/production/monitoring">
    Set up monitoring
  </Card>
  <Card title="Security" icon="shield" href="/baas/api/production/security-compliance">
    Production security
  </Card>
</CardGroup>

## Support During Go-Live

During the go-live process, you'll have access to dedicated support:

- **Technical Support**: For implementation and integration issues
- **Compliance Support**: For regulatory and compliance questions
- **Account Management**: For coordination and process management

Contact your account manager or [support@finhub.cloud](mailto:support@finhub.cloud) for assistance.


---

# Production Setup

Configure production environment


URL: /baas/api/production/production-setup



# Production Setup

Configure your production environment for live operations.

## Production URLs

| Service | URL |
|---------|-----|
| **API Gateway** | `https://gateway.finhub.cloud` |
| **OAuth** | `https://gateway.finhub.cloud/oauth/token` |
| **Webhooks** | Configure in Admin Panel |

## Configuration Steps

<Steps>
  <Step title="Update Base URLs">
    Change from sandbox to production endpoints
  </Step>
  <Step title="Install Certificates">
    Configure mTLS client certificates
  </Step>
  <Step title="Configure IP Whitelisting">
    Register production server IPs
  </Step>
  <Step title="Update Credentials">
    Use production Client ID and Secret
  </Step>
  <Step title="Configure Webhooks">
    Set production webhook endpoints
  </Step>
</Steps>

## Environment Variables

```bash
# Production Configuration
FINHUB_BASE_URL=https://gateway.finhub.cloud
FINHUB_TENANT_ID=your_production_tenant_id
FINHUB_CLIENT_ID=your_production_client_id
FINHUB_CLIENT_SECRET=your_production_client_secret
```

## Security Requirements

| Requirement | Details |
|-------------|----------|
| **mTLS** | Client certificate required |
| **IP Whitelist** | Only approved IPs |
| **TLS 1.2+** | Minimum TLS version |
| **Request Signing** | HMAC signature on requests


---

# Production Auth

Production authentication setup


URL: /baas/api/production/production-auth



# Production Authentication

Production authentication differs from sandbox with additional security.

## Differences from Sandbox

| Feature | Sandbox | Production |
|---------|---------|------------|
| mTLS | Optional | Required |
| IP Whitelist | Optional | Required |
| Token Lifetime | 10,000s | 3,600s |
| Rate Limits | Relaxed | Strict |

## mTLS Setup

1. Generate CSR (Certificate Signing Request)
2. Submit CSR to FinHub
3. Receive signed certificate
4. Install certificate in your application

## Authentication Request

```bash
curl -X POST "https://gateway.finhub.cloud/oauth/token" \
  --cert client.crt \
  --key client.key \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "YOUR_PROD_CLIENT_ID",
    "client_secret": "YOUR_PROD_CLIENT_SECRET"
  }'
```

## Token Management

- Tokens expire after 1 hour
- Implement proactive refresh (at 80% lifetime)
- Cache tokens appropriately
- Handle 401 errors with re-authentication


---

# Monitoring

Production monitoring and alerting


URL: /baas/api/production/monitoring



# Monitoring

Set up comprehensive monitoring for your production integration.

## Key Metrics

| Metric | Target | Alert Threshold |
|--------|--------|----------------|
| **Response Time** | < 500ms | > 2s |
| **Error Rate** | < 0.1% | > 1% |
| **Availability** | 99.9% | < 99% |
| **Transaction Volume** | Expected | ±50% deviation |

## Recommended Monitoring

### Application Monitoring
- Request/response times
- Error rates by endpoint
- Transaction success rates
- Token refresh failures

### Infrastructure Monitoring
- Server health
- Network connectivity
- Certificate expiration
- Disk and memory usage

## Alerting

Configure alerts for:
- API errors (4xx, 5xx)
- Latency spikes
- Authentication failures
- Webhook delivery failures
- Certificate expiration (30 days)

## Logging

Log all API interactions:
- Request ID
- Timestamp
- Endpoint
- Response code
- Duration

**Do NOT log**: Tokens, secrets, PII

## FinHub Status

Monitor FinHub status at: `https://status.finhub.cloud`


---

# Security & Compliance

Production security requirements


URL: /baas/api/production/security-compliance



# Security & Compliance

Production security and compliance requirements.

## Security Requirements

| Requirement | Description |
|-------------|-------------|
| **mTLS** | Mutual TLS authentication |
| **IP Whitelisting** | Approved IPs only |
| **Encryption** | TLS 1.2+ for all traffic |
| **Data Protection** | Encrypt sensitive data at rest |

## Compliance Requirements

### Data Protection
- GDPR compliance for EU data
- Data minimization
- Right to erasure support
- Consent management

### Financial Regulations
- KYC/AML compliance
- Transaction monitoring
- Suspicious activity reporting
- Audit trail maintenance

## Audit Logging

Maintain logs for:
- All API calls
- Authentication events
- Data access
- Configuration changes

Retention: Minimum 7 years for financial data

## Incident Response

1. **Detection** - Identify security incident
2. **Containment** - Limit impact
3. **Notification** - Inform FinHub within 24 hours
4. **Investigation** - Root cause analysis
5. **Remediation** - Fix vulnerabilities

## Contact

Security issues: support@finhub.cloud


---

# Disaster Recovery

Business continuity and disaster recovery


URL: /baas/api/production/disaster-recovery



# Disaster Recovery

Business continuity and disaster recovery planning.

## FinHub Infrastructure

| Capability | Details |
|------------|----------|
| **Availability** | 99.99% SLA |
| **Data Centers** | Multiple geographic regions |
| **Failover** | Automatic failover |
| **Backup** | Daily encrypted backups |
| **RTO** | < 4 hours |
| **RPO** | < 1 hour |

## Your Responsibilities

### Failover Planning
- Secondary processing paths
- Manual override procedures
- Communication protocols

### Data Backup
- Backup integration data
- Store transaction logs
- Maintain audit trails

### Testing
- Regular DR drills
- Failover testing
- Recovery validation

## Incident Communication

During outages:
1. Check `status.finhub.cloud`
2. Contact production-support@finhub.cloud
3. Use emergency hotline for critical issues

## Recovery Procedures

1. **Identify** - Confirm incident scope
2. **Activate** - Trigger DR procedures
3. **Communicate** - Notify stakeholders
4. **Recover** - Restore operations
5. **Review** - Post-incident analysis


---

# API Operations

Day-to-day operations for API clients


URL: /baas/api/operations



# API Operations

Manage your API integration day-to-day.

## Admin Panel

All API clients have access to the Admin Panel for:

- Customer management
- Transaction monitoring
- Compliance workflows
- Reporting and analytics

<Card title="Admin Panel" icon="gauge" href="/baas/api/operations/admin-panel">
  Learn about the Admin Panel
</Card>

## Operational Tasks

| Task | Tool |
|------|------|
| View customers | Admin Panel |
| Monitor transactions | Admin Panel |
| Handle approvals | Admin Panel |
| Generate reports | Admin Panel |
| Manage webhooks | Developer Portal |

## Monitoring

- Monitor API response times
- Track error rates
- Watch transaction volumes
- Set up alerts

## Support

| Type | Contact |
|------|---------|
| Technical | support@finhub.cloud |
| Sandbox | sandbox-support@finhub.cloud |
| Production | production-support@finhub.cloud |


---

# Admin Panel

API client operations dashboard


URL: /baas/api/operations/admin-panel



# Admin Panel

Manage your API integration through the Admin Panel.

## Features

| Feature | Description |
|---------|-------------|
| **Dashboard** | Overview metrics |
| **Customers** | Customer management |
| **Transactions** | Transaction monitoring |
| **Settings** | Configuration |

## Access

Admin Panel: `https://admin.finhub.cloud`

## Key Functions

- View customer status
- Monitor transactions
- Generate reports
- Manage webhooks
- API key management


---

# API Reference

Complete API reference documentation for FinHub platform services


URL: /baas/api/reference



# API Reference

Welcome to the FinHub API Reference documentation. This comprehensive guide covers all available APIs for building financial services applications.

<CardGroup cols={2}>
  <Card title="Getting Started" icon="rocket" href="/baas/api/getting-started">
    Authentication, environments, and your first API call
  </Card>
  <Card title="Customer APIs" icon="users" href="/baas/api/reference/customer-apis">
    Individual (B2C) and Organization (B2B) customer management
  </Card>
  <Card title="Financial Operations" icon="banknote" href="/baas/api/reference/financial-operations">
    Account operations, transfers, beneficiaries, and payment consents
  </Card>
  <Card title="Verification & Compliance" icon="shield-check" href="/baas/api/reference/verification-compliance">
    Verification processes and document management
  </Card>
  <Card title="Administration" icon="gear" href="/baas/api/reference/administration">
    Session management, user management, and consent templates
  </Card>
  <Card title="Developer Tools" icon="code" href="/baas/api/reference/developer-tools">
    Webhooks and testing utilities
  </Card>
</CardGroup>

## Base URLs

| Environment | Base URL |
|-------------|----------|
| **Sandbox** | `https://sandbox-api.finhub.cloud` |
| **Integration** | `https://api-beta.finhub.cloud` |
| **Production** | `https://api.finhub.cloud` |

## Authentication

All API requests require OAuth 2.0 Bearer token authentication:

```bash
curl -X GET "https://api.finhub.cloud/api/v2.1/..." \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd"
```

## Rate Limits

| Environment | Requests/Second | Requests/Minute |
|-------------|-----------------|-----------------|
| **Sandbox** | 10 | 100 |
| **Production** | 100 | 1000 |

## Getting Support

If you encounter issues or have questions about the API:

- **Technical Support**: [support@finhub.cloud](mailto:support@finhub.cloud)
- **Sandbox Support**: [sandbox-support@finhub.cloud](mailto:sandbox-support@finhub.cloud)
- **Production Support**: [production-support@finhub.cloud](mailto:production-support@finhub.cloud)
- **Compliance Questions**: [compliance@finhub.cloud](mailto:compliance@finhub.cloud)

For urgent production issues, use the emergency contact information provided with your production credentials.


---

# Customer APIs

APIs for individual (B2C) and organization (B2B) customer lifecycle management


URL: /baas/api/reference/customer-apis



# Customer APIs

Unified API surface for managing the complete customer lifecycle — registration, authentication, identity verification, consent collection, and account activation — for both individual and business customers.

<Info>
  **Base URL:** `https://sandbox.finhub.cloud/api/v2.1/customer`
</Info>

---

## Customer Types

<CardGroup cols={2}>
  <Card title="Individual (B2C)" icon="user" href="/baas/api/reference/customer-apis/individual">
    Personal customer onboarding: categorization, registration, sessions, verification, and activation
  </Card>
  <Card title="Organization (B2B)" icon="building" href="/baas/api/reference/customer-apis/organization">
    Business customer onboarding: registration, directors, employees, shareholders, and activation
  </Card>
</CardGroup>

---

## Shared Onboarding Pattern

Both B2C and B2B flows follow the same high-level pattern:

```mermaid
flowchart LR
    A[Register] --> B[Authenticate]
    B --> C[Verify Identity]
    C --> D[Upload Documents]
    D --> E[Accept Consents]
    E --> F[Activate]
```

### Individual (B2C) onboarding flow

```mermaid
flowchart TB
    I1["(1) Categorization"] --> I2["(2) Registration"]
    I2 --> I3["(3) Session creation"]
    I3 --> I4["(4) Verification"]
    I4 --> I5["(5) Document upload"]
    I5 --> I6["(6) Consent acceptance"]
    I6 --> I7["(7) Activation"]
```

### Organization (B2B) onboarding flow

```mermaid
flowchart TB
    O1["(1) Categorization"] --> O2["(2) Organization registration"]
    O2 --> O3["(3) Employee/personnel setup"]
    O3 --> O4["(4) Session creation"]
    O4 --> O5["(5) KYB verification"]
    O5 --> O6["(6) Document upload"]
    O6 --> O7["(7) Consent acceptance"]
    O7 --> O8["(8) Activation"]
```

| Step | Individual (B2C) | Organization (B2B) |
|------|------------------|--------------------|
| **Register** | `POST /individual/registration` | `POST /organization/registration` |
| **Personnel** | — | `POST /{orgId}/employee`, `GET /{orgId}/directors` |
| **Verify** | `POST /{customerId}/verification` | Via Verification & Compliance APIs |
| **Consents** | `POST /{customerId}/consents/{type}` | `POST /{orgId}/consents/{type}` |
| **Activate** | `POST /{customerId}/activation` | `POST /{orgId}/activation` |

<Note>
  Verification, document upload, and consent management are handled through the [Verification & Compliance](/baas/api/reference/verification-compliance) APIs, which are shared across both customer types.
</Note>

---

## Authentication

All Customer API endpoints require the following headers:

| Header | Required | Description |
|--------|----------|-------------|
| `Authorization` | Yes | `Bearer <token>` — OAuth 2.0 access token from an admin or customer session |
| `X-Tenant-ID` | Yes | Your tenant identifier |
| `Content-Type` | Yes | `application/json` for all POST requests |

```bash
curl -X POST "https://sandbox.finhub.cloud/api/v2.1/customer/individual/registration" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{ ... }'
```

---

## Related Resources

<CardGroup cols={2}>
  <Card title="Verification & Compliance" icon="shield-check" href="/baas/api/reference/verification-compliance">
    KYC/KYB verification, document upload, approval, and consent management
  </Card>
  <Card title="Administration" icon="gear" href="/baas/api/reference/administration">
    Admin sessions, roles, audit trails, and platform management
  </Card>
  <Card title="Financial Operations" icon="banknote" href="/baas/api/reference/financial-operations">
    Wallet balances, transfers, beneficiaries, and payment consents
  </Card>
  <Card title="Developer Tools" icon="code" href="/baas/api/reference/developer-tools">
    Webhook subscriptions and testing utilities
  </Card>
</CardGroup>


---

# Individual Customer APIs (B2C)

Complete API reference for individual customer onboarding and lifecycle management


URL: /baas/api/reference/customer-apis/individual



# Individual Customer APIs (B2C)

End-to-end API reference for individual customer lifecycle management — from categorization and registration through identity verification, consent collection, and account activation.

<Info>
  **Base URL:** `https://sandbox.finhub.cloud/api/v2.1/customer/individual`
</Info>

<Note>
  Verification, document upload, and consent acceptance are handled through the [Verification & Compliance](/baas/api/reference/verification-compliance) APIs. This section covers the customer-specific endpoints only.
</Note>

---

## Onboarding Journey

The individual customer onboarding flow follows **5 customer API phases**, plus verification and consent steps handled by the Verification & Compliance APIs:

| Phase | API Section | Endpoint | Description |
|-------|-------------|----------|-------------|
| **1. Categorization** | Customer | `GET /categorization/hierarchy/{tenantId}` | Retrieve available customer categories and risk tiers |
| **2. Registration** | Customer | `POST /registration` | Create a new individual customer with personal details |
| **3. Session** | Customer | `POST /{customerId}/users/{userId}/sessions` | Authenticate and obtain a JWT access token |
| **4. Verification** | Customer | `POST /{customerId}/verification` | Initiate identity verification for the customer |
| **5. KYC Documents** | Verification | `POST /verifications/{verificationId}/documents` | Upload identity and address documents |
| **6. KYC Approval** | Verification | `POST /verifications/{verificationId}/approve` | Admin approves the verification submission |
| **7. Consents** | Verification | `POST /{customerId}/consents/{consentType}` | Accept terms, privacy, and data-processing consents |
| **8. Activation** | Customer | `POST /{customerId}/activation` | Activate the customer account and wallet |

<Tip>
  Steps 5-7 use endpoints from the **Verification & Compliance** section. See the [Verification & Compliance overview](/baas/api/reference/verification-compliance) for details.
</Tip>

---

## API Endpoints

<CardGroup cols={2}>
  <Card title="Categorization" icon="sitemap" href="/baas/api/reference/customer-apis/individual/categorization">
    Retrieve the category hierarchy to determine available customer tiers and features
  </Card>
  <Card title="Registration" icon="user-plus" href="/baas/api/reference/customer-apis/individual/registration">
    Register a new individual customer with personal and contact information
  </Card>
  <Card title="Sessions" icon="key" href="/baas/api/integration/flows/individual-customer/session-management">
    Create authenticated sessions and obtain JWT tokens
  </Card>
  <Card title="Verification" icon="shield-check" href="/baas/api/reference/verification-compliance">
    Initiate identity verification (KYC) for a registered customer
  </Card>
  <Card title="Activation" icon="circle-check" href="/baas/api/reference/customer-apis/individual/activation">
    Activate the customer account once all prerequisites are met
  </Card>
</CardGroup>

---

## Quick Start

### 1. Retrieve Categories

```bash
curl -X GET "https://sandbox.finhub.cloud/api/v2.1/customer/individual/categorization/hierarchy/{tenantId}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID"
```

### 2. Register Customer

```bash
curl -X POST "https://sandbox.finhub.cloud/api/v2.1/customer/individual/registration" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123!",
    "customerCategory": { "id": "fs-cat-b2c-low-001" },
    ...
  }'
```

### 3. Create Session

```bash
curl -X POST "https://sandbox.finhub.cloud/api/v2.1/customer/individual/{customerId}/users/{userId}/sessions" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{ "username": "user@example.com", "password": "SecurePass123!" }'
```

### 4-8. Complete Verification, Consents & Activation

See the [Verification & Compliance](/baas/api/reference/verification-compliance) section for document upload, approval, and consent endpoints, then return to the **Activation** endpoint to complete onboarding.

---

## Prerequisites

- API credentials obtained (Tenant ID, API keys, admin session token)
- Customer categorization selected from the hierarchy
- Customer personal information collected (name, email, date of birth, nationality)
- Identity documents ready (passport or national ID, proof of address)

---

## Customer Lifecycle

```mermaid
stateDiagram-v2
    [*] --> Categorization: Get category hierarchy
    Categorization --> Registration: Select category
    Registration --> Session: Customer created
    Session --> Verification: JWT obtained
    Verification --> Documents: KYC initiated
    Documents --> Approval: Documents uploaded
    Approval --> Consents: KYC approved
    Consents --> Activation: All 3 consents accepted
    Activation --> [*]: Account ACTIVE

    note right of Verification
        Uses Verification &
        Compliance APIs
    end note

    note right of Approval
        Admin review required
        (1-3 business days)
    end note

    note right of Activation
        Requires:
        ✓ KYC approved
        ✓ All consents accepted
    end note
```

---

## Related Resources

<CardGroup cols={2}>
  <Card title="Verification & Compliance" icon="shield-check" href="/baas/api/reference/verification-compliance">
    KYC document upload, approval, and consent management
  </Card>
  <Card title="Organization APIs (B2B)" icon="building" href="/baas/api/reference/customer-apis/organization">
    Business customer onboarding and management
  </Card>
  <Card title="Financial Operations" icon="banknote" href="/baas/api/reference/financial-operations">
    Wallet balances, transfers, and payment operations
  </Card>
  <Card title="Administration" icon="gear" href="/baas/api/reference/administration">
    Admin sessions, roles, and platform management
  </Card>
</CardGroup>


---

# Individual Categorization Hierarchy

Get available B2C/B2B categories and feature metadata for a tenant


URL: /baas/api/reference/customer-apis/individual/categorization



import { RequiredRunnerHeaders } from '../../schemas/required-headers-snippet.mdx';

# Individual Categorization Hierarchy

Returns customer category options used before registration.

## Endpoint

`GET /api/v2.1/customer/individual/categorization/hierarchy/{tenantId}`

## Path Parameters

<ParamField path="tenantId" type="string" required>
  Tenant UUID. Example: `97e7ff29-15f3-49ef-9681-3bbfcce4f6cd`
</ParamField>

## Required Headers

<RequiredRunnerHeaders />

## Example

```bash cURL
curl -X GET "https://sandbox.finhub.cloud/api/v2.1/customer/individual/categorization/hierarchy/97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"
```

## Success Response

```json 200
{
  "code": 200,
  "data": {
    "tenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
    "categories": {
      "INDIVIDUAL_STANDARD": {
        "databaseId": "fs-cat-b2c-low-001",
        "categoryName": "Individual Standard"
      },
      "B2B_SMALL_BUSINESS": {
        "databaseId": "fs-cat-b2b-small-001",
        "categoryName": "Small Business"
      }
    }
  },
  "message": "Success"
}
```

<Note>
  Used by B2C/B2B step runners before registration (Step 2).
</Note>


---

# Individual Registration

Register a new B2C individual customer


URL: /baas/api/reference/customer-apis/individual/registration



import { RequiredRunnerHeaders } from '../../schemas/required-headers-snippet.mdx';

# Individual Registration

Creates an individual customer, linked person, and initial user in `PENDING_ACTIVATION`.

## Endpoint

`POST /api/v2.1/customer/individual/registration`

## Key Defaults (from B2C runner)

- `password` and `matchingPassword`: `SecurePass123!`
- Category example: `fs-cat-b2c-low-001` (`Individual Standard`)
- Role IDs: `ACCOUNT_OWNER`, `USER`

## Required Headers

<RequiredRunnerHeaders />

## Example Request

```json
{
  "firstName": "John",
  "lastName": "Customer",
  "email": "customer.20260331114946-387074@testcorp.com",
  "phone": "+37062767557",
  "password": "SecurePass123!",
  "matchingPassword": "SecurePass123!",
  "dateOfBirth": "1990-05-15",
  "gender": "MALE",
  "nationality": "Lithuania",
  "placeOfBirth": "Vilnius",
  "pincode": "12345",
  "roleIds": ["ACCOUNT_OWNER", "USER"],
  "customerCategory": {
    "id": "fs-cat-b2c-low-001",
    "name": "Individual Standard"
  }
}
```

## cURL

```bash
curl -X POST "https://sandbox.finhub.cloud/api/v2.1/customer/individual/registration" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -d @registration.json
```

## Success Response

```json 200
{
  "code": 200,
  "data": {
    "id": "2dac1793-ab48-420c-b0b5-01292302e188",
    "customerStatus": "CS_REGISTRATION_COMPLETED",
    "user": {
      "id": "0d488f57-57ef-4f9a-88a6-f89121cab838",
      "email": "customer.20260331114946-387074@testcorp.com"
    }
  },
  "message": "B2C individual account created successfully"
}
```

<Note>
  Used in B2C step runner Step 3 and mirrored in `individual-playground.crx.js`.
</Note>


---

# Individual Activation Readiness Check

Check if a B2C customer is ready for activation


URL: /baas/api/reference/customer-apis/individual/activation-readiness-check



import { RequiredRunnerHeaders } from '../../schemas/required-headers-snippet.mdx';

# Individual Activation Readiness Check

Validates KYC and consent prerequisites before activation.

## Endpoint

`GET /api/v2.1/customer/individual/{customerId}/owner/{ownerTenantId}/activation/check`

## Path Parameters

<ParamField path="customerId" type="string" required>Customer UUID</ParamField>
<ParamField path="ownerTenantId" type="string" required>Owner tenant UUID</ParamField>

## Required Headers

<RequiredRunnerHeaders />

## Response Example

```json 200
{
  "code": 200,
  "data": {
    "activationAllowed": true,
    "consentOk": true,
    "verificationOk": true,
    "riskLevel": "LOW",
    "message": "Customer is ready for activation"
  },
  "message": "Customer is ready for activation"
}
```

<Note>
  Used in B2C step runner Step 7.
</Note>


---

# Individual Activation

Activate a B2C customer after KYC and consent completion


URL: /baas/api/reference/customer-apis/individual/activation



import { RequiredRunnerHeaders } from '../../schemas/required-headers-snippet.mdx';

# Individual Activation

Activates an individual customer account.

## Endpoint

`POST /api/v2.1/customer/individual/{customerId}/activation`

## Required Headers

<RequiredRunnerHeaders />

## Request Body (runner-aligned)

```json
{
  "userId": "customer.20260331114946-387074@testcorp.com",
  "code": "ACTIVATION_CODE_20260331114954"
}
```

## cURL

```bash
curl -X POST "https://sandbox.finhub.cloud/api/v2.1/customer/individual/{customerId}/activation" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -d '{
    "userId": "customer.20260331114946-387074@testcorp.com",
    "code": "ACTIVATION_CODE_20260331114954"
  }'
```

## Success Response

```json 200
{
  "code": 200,
  "data": {},
  "message": "Success"
}
```

<Note>
  Used in B2C step runner Step 8 and aligned with `individual-playground.crx.js`.
</Note>


---

# Organization Customer APIs (B2B)

APIs for managing business organization lifecycle


URL: /baas/api/reference/customer-apis/organization



# Organization Customer APIs (B2B)

Complete API reference for business organization lifecycle management, from registration through corporate structure setup, verification, and activation.

<Info>
  **Base URL:** `https://sandbox.finhub.cloud/api/v2.1/customer/organization`
</Info>

<Note>
  For complete details on authentication and headers, refer to the [Standard HTTP Headers](../schemas/standard-headers) reference documentation.
</Note>

<Note>
  **Categorization:** Use `GET /customer/individual/categorization/hierarchy/{tenantId}` to retrieve all available categories. Filter the response for organization-suitable categories (categoryName contains "BUSINESS", "ORGANIZATION", or "B2B").
</Note>

---

## Complete Organization Journey

The organization onboarding flow consists of **8 phases**:

| Phase | Endpoint | Time | Prerequisites | Status After |
|-------|----------|------|---------------|--------------|
| **1. Categorization** | `GET /customer/individual/categorization/hierarchy/{tenantId}` | < 1 min | API credentials | Category selected |
| **2. Registration** | `POST /registration` | < 5 min | Category ID, org details | Organization created |
| **3. Personnel** | `POST /{orgId}/employee`, `/director`, `/shareholders` | 20 min | Organization ID | All roles filled |
| **4. Documents** | `POST /{orgId}/documents` | 10 min | Corporate docs ready | Documents uploaded |
| **5. Verification** | `POST /{orgId}/verification` | 2-5 days | All docs + personnel | KYB submitted |
| **6. Consents** | `POST /{orgId}/consents/*` | 5 min | Legal representative | All 3 consents accepted |
| **7. Activation** | `POST /{orgId}/activation` | Instant | All above complete | Organization ACTIVE, wallet ACTIVE |
| **8. Operations** | Financial APIs | Ongoing | Activated account | Transfers, payments enabled |

**Total Time:** 2-5 business days (mostly KYB verification wait time)

---

## Quick Start Guide

### Step 1: Register Organization
```bash
curl -X POST "https://sandbox.finhub.cloud/api/v2.1/customer/organization/registration" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "Content-Type: application/json" \
  -d '{ "legalName": "Acme Corp", "categoryId": "cat_business_123", ... }'
```

### Step 2: Add Personnel (Order Matters!)
```bash
# 1. Add Employee with ADMIN_USER role (REQUIRED FIRST)
POST /{orgId}/employee { "roles": ["ADMIN_USER"], ... }

# 2. Add Director (minimum 1)
POST /{orgId}/director { ... }

# 3. Add Shareholders (must total 100%)
POST /{orgId}/shareholders [{ "ownershipPercentage": 60 }, { "ownershipPercentage": 40 }]
```

### Step 3-7: Complete Flow
See individual endpoint documentation below.

---

## API Endpoints by Phase

<CardGroup cols={2}>
  <Card title="Registration" icon="building-circle-check" href="/baas/api/reference/customer-apis/organization/registration">
    Register new business organizations
  </Card>
  <Card title="Management" icon="users-round" href="/baas/api/reference/customer-apis/organization/management">
    Add directors, shareholders, and employees (ADMIN_USER required)
  </Card>
  <Card title="Verification" icon="shield-check" href="/baas/api/reference/verification-compliance/verification-management">
    Complete KYB verification
  </Card>
  <Card title="Consents" icon="file-signature" href="/baas/api/reference/verification-compliance/consents-organization">
    Accept required business consents
  </Card>
  <Card title="Activation" icon="circle-check" href="/baas/api/reference/customer-apis/organization/activation">
    Activate organization account
  </Card>
  </CardGroup>

---

## Prerequisites Before Starting

- [ ] API credentials obtained (Tenant ID, API keys)
- [ ] Business categorization selected (risk level)
- [ ] Corporate documents ready:
  - [ ] Certificate of Incorporation
  - [ ] Articles of Association
  - [ ] Shareholder Register
  - [ ] Director IDs
  - [ ] Bank Statements (last 3 months)
- [ ] Personnel information collected:
  - [ ] At least 1 employee (with ADMIN_USER role)
  - [ ] At least 1 director
  - [ ] All shareholders (must total 100% ownership)

---

## Organization Lifecycle Flow

```mermaid
stateDiagram-v2
    [*] --> Categorization: Get business categories
    Categorization --> Registration: Select category
    Registration --> AddEmployee: Create organization
    AddEmployee --> AddDirector: ADMIN_USER added
    AddDirector --> AddShareholders: Min 1 director
    AddShareholders --> Documents: 100% ownership
    Documents --> Verification: Upload corp docs
    Verification --> Consents: Submit KYB
    Consents --> Activation: Accept all 3
    Activation --> [*]: Organization ACTIVE
    
    note right of AddEmployee
        MUST be first!
        Requires ADMIN_USER role
    end note
    
    note right of Verification
        2-5 days wait time
        POWER_TENANT approval
        for high-risk businesses
    end note
    
    note right of Activation
        Prerequisites:
        - All personnel verified
        - All consents accepted
        - KYB approved
        - Documents verified
    end note
```

---

## Key Differences: B2C vs B2B

| Aspect | Individual Customer (B2C) | Organization Customer (B2B) |
|--------|--------------------------|----------------------------|
| **Registration** | Single person | Company + personnel |
| **Verification** | KYC (identity) | KYB (business + UBO) |
| **Personnel** | N/A | Directors, shareholders, employees required |
| **Ownership** | N/A | Must declare 100% ownership |
| **Roles** | User only | ADMIN_USER, COMPLIANCE_OFFICER, etc. |
| **Approval** | TENANT_ADMIN | POWER_TENANT for high-risk |
| **Time** | 1-3 days | 2-5 days |
| **Complexity** | Simple | Complex (multi-step) |

---

## Personnel Management Rules

### Required Roles

| Role | Minimum Required | Purpose | Can Activate Account |
|------|-----------------|---------|---------------------|
| **ADMIN_USER** | 1 | Full organization access | ✅ Yes |
| **COMPLIANCE_OFFICER** | 0 (recommended 1) | Approve verifications | ✅ Yes |
| **Director** | 1 | Corporate governance | No |
| **Shareholder** | 1+ (100% total) | Ownership structure | No |

### Order of Operations

<Warning>
  **IMPORTANT:** Add personnel in this exact order:
  
  1. **Employee** (with ADMIN_USER role) - MUST BE FIRST!
  2. **Director** (minimum 1)
  3. **Shareholders** (must total 100%)
  
  Attempting to activate without an ADMIN_USER will fail with a 400 error.
</Warning>

---

## Related Resources

<CardGroup cols={2}>
  <Card title="Standard Headers" icon="list" href="../schemas/standard-headers">
    Required HTTP headers for all endpoints
  </Card>
  
  <Card title="API Schema Mapping" icon="code" href="../../../../doc/mint/API_SCHEMA_MAPPING">
    Complete OpenAPI specifications
  </Card>
  
  <Card title="Individual APIs" icon="user" href="../individual">
    B2C customer management
  </Card>
  
  <Card title="Financial Operations" icon="banknote" href="../../financial-operations">
    Wallet and payment operations
  </Card>
</CardGroup>

---

## Changelog

| Version | Date | Changes |
|---------|------|---------|
| v1.0 | 2026-01-13 | Enhanced organization customer API overview |


---

# Organization Registration

Register a new B2B organization customer


URL: /baas/api/reference/customer-apis/organization/registration



import { RequiredRunnerHeaders } from '../../schemas/required-headers-snippet.mdx';

# Organization Registration

Creates an organization customer and initial admin user.

## Endpoint

`POST /api/v2.1/customer/organization/registration`

## Key Defaults (from B2B runner)

- Passwords: `SecurePass123!`
- Category example: `fs-cat-b2b-small-001` (`Small Business`)
- Legal form: `LIMITED_LIABILITY_COMPANY`
- Industry: `TECHNOLOGY`

## Required Headers

<RequiredRunnerHeaders />

## Request Example

```json
{
  "email": "admin@acmecorp-20260331115443-27f5ae.com",
  "password": "SecurePass123!",
  "matchingPassword": "SecurePass123!",
  "roleIds": ["ACCOUNT_OWNER", "ADMIN"],
  "customerCategory": {
    "id": "fs-cat-b2b-small-001",
    "name": "Small Business"
  },
  "organizationCustomer": {
    "customerName": "My Company",
    "organization": {
      "legalName": "My Company Ltd.",
      "tradingName": "My Company",
      "registrationNumber": "REG-20260331115443",
      "taxId": "TAX-20260331115443"
    }
  }
}
```

## Response Example

```json 200
{
  "code": 200,
  "data": {
    "organizationId": "f458d016-56bb-43a6-856c-4d0456b2c38c",
    "customerId": "f458d016-56bb-43a6-856c-4d0456b2c38c",
    "email": "admin@acmecorp-20260331115443-27f5ae.com"
  },
  "message": "Organization registered successfully. Default admin will be created automatically."
}
```

<Note>
  Used in B2B step runner Step 3 and mirrored in `organization-playground.crx.js`.
</Note>


---

# Organization Add Employee

Add an employee user to an organization customer


URL: /baas/api/reference/customer-apis/organization/employee



import { RequiredRunnerHeaders } from '../../schemas/required-headers-snippet.mdx';

# Organization Add Employee

Adds an employee profile and creates a user for an existing organization.

## Endpoint

`POST /api/v2.1/customer/organization/{organizationId}/employee`

## Default Role Set (runner-aligned)

`COMPLIANCE_OFFICER`, `TRANSACTION_APPROVER`, `EMPLOYEE`, `ADMIN_USER`

## Required Headers

<RequiredRunnerHeaders />

## Request Example

```json
{
  "person": {
    "firstName": "Jane",
    "lastName": "Compliance",
    "email": "compliance.20260331115443@acmecorp.com",
    "phoneNumber": "+37066051634",
    "dateOfBirth": "1990-03-25",
    "nationality": "Lithuania",
    "gender": "1",
    "fullName": "Jane Compliance"
  },
  "position": "COMPLIANCE_OFFICER",
  "roles": ["COMPLIANCE_OFFICER", "TRANSACTION_APPROVER", "EMPLOYEE", "ADMIN_USER"],
  "department": "Compliance"
}
```

## Success Response

```json 200
{
  "code": 200,
  "data": {
    "individual": {
      "userId": "da9a15d2-1eb9-4804-a812-b58b03f33018",
      "email": "compliance.20260331115443@acmecorp.com"
    }
  },
  "message": "Employee added successfully with role validation"
}
```

<Note>
  Used in B2B step runner Step 4.
</Note>


---

# Organization Management API

Manage directors, shareholders, and employees for organizations


URL: /baas/api/reference/customer-apis/organization/management



# Organization Management API

Manage organization structure by adding directors, shareholders, and employees after initial registration.

<Note>
  For complete details on authentication and headers, refer to the [Standard HTTP Headers](../../schemas/standard-headers) reference documentation.
</Note>

## Personnel Management Overview

After registering an organization, you must add personnel in the correct order:

**Recommended Order:**
1. **Employees** (including at least one ADMIN_USER)
2. **Directors** (minimum 1 required for activation)
3. **Shareholders** (must total 100% ownership)

### Dual Record Creation

When you add personnel, the system automatically creates **two linked records**:

| Record Type | Purpose | Status |
|------------|---------|---------|
| **Organization Record** | Links person to org with role/position | ACTIVE |
| **Individual Customer** | Creates login credentials | ACTIVE |

**Important:** Each person gets auto-generated username and password returned in the response.

<Warning>
  **ADMIN_USER Role Requirement**
  
  Organizations of type `BUSINESS_TYPE_CLIENT_TO_TENANT` **must** have at least one employee with the `ADMIN_USER` role.
  
  If you attempt to add employees without this role first, you will receive a 400 error:
  ```json
  {
    "code": 400,
    "message": "Missing required role 'ADMIN_USER' for BUSINESS_TYPE_CLIENT_TO_TENANT organization. At least one employee must have this role."
  }
  ```
  
  **Solution:** Ensure your first employee has `ADMIN_USER` in their roles array.
</Warning>

---

## Add Director

Add a director to an organization.

### Endpoint

```
POST /api/v2.1/customer/organization/{organizationId}/director
```

### Path Parameters

<ParamField path="organizationId" type="string" required>
  Organization UUID identifier
  
  Example: `2f6ddd86-9ef1-45b6-a16d-058b3ccf29e4`
</ParamField>

### Headers

<ParamField header="X-Tenant-ID" type="string" required>
  Tenant identifier
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`
</ParamField>

### Request Body

<ParamField body="person" type="object" required>
  Director's personal information
  
  See [PersonDto](../../schemas/common-types#persondto) for complete structure
  
  <Expandable title="person properties">
    <ParamField body="firstName" type="string" required>
      Given name
    </ParamField>
    
    <ParamField body="lastName" type="string" required>
      Family name
    </ParamField>
    
    <ParamField body="email" type="string" required>
      Email address
    </ParamField>
    
    <ParamField body="dateOfBirth" type="string" required>
      ISO 8601 date (YYYY-MM-DD)
    </ParamField>
    
    <ParamField body="nationality" type="string" required>
      ISO 3166-1 alpha-2 country code
    </ParamField>
    
    <ParamField body="gender" type="integer" required>
      Gender code: `0` = Male, `1` = Female
    </ParamField>
    
    <ParamField body="placeOfBirth" type="string">
      Birth location
    </ParamField>
    
    <ParamField body="fullName" type="string">
      Complete name for display
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="role" type="string" required>
  Director role type
  
  **Valid Values:**
  - `MANAGING_DIRECTOR`
  - `EXECUTIVE_DIRECTOR`
  - `NON_EXECUTIVE_DIRECTOR`
  - `BOARD_MEMBER`
</ParamField>

<ParamField body="ownershipPercentage" type="number">
  Percentage ownership (0-100)
  
  Default: `0` if not specified
</ParamField>

<ParamField body="isPrimaryContact" type="boolean">
  Whether this director is the primary contact
  
  Default: `false`
</ParamField>

<ParamField body="addresses" type="array" required>
  Array of address objects
  
  See [AddressDto](../../schemas/common-types#addressdto)
</ParamField>

<ParamField body="telephoneNumbers" type="array" required>
  Array of telephone numbers
  
  See [TelephoneNumberDto](../../schemas/common-types#telephonenumberdto)
</ParamField>

### Code Example

<CodeGroup>
```bash cURL
curl -X POST "https://sandbox.finhub.cloud/api/v2.1/customer/organization/2f6ddd86-9ef1-45b6-a16d-058b3ccf29e4/director" \
  -H "Accept: application/json, text/plain, */*" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Forwarded-From: e2e-test" \
  -H "platform: web" \
  -H "deviceId: 356938035643809" \
  -d '{
    "person": {
      "firstName": "John",
      "lastName": "Director",
      "email": "director@acmecorp.com",
      "dateOfBirth": "1980-01-15",
      "nationality": "LT",
      "gender": 0,
      "placeOfBirth": "Vilnius",
      "fullName": "John Director"
    },
    "role": "MANAGING_DIRECTOR",
    "ownershipPercentage": 0,
    "isPrimaryContact": false,
    "addresses": [
      {
        "type": "HOME",
        "street": "123 Director Street",
        "city": "Vilnius",
        "postalCode": "12345",
        "country": "LT",
        "isPrimary": true
      }
    ],
    "telephoneNumbers": [
      {
        "number": "+37060012345",
        "country": "LT",
        "phoneType": 1,
        "operator": "Telia",
        "purpose": "personal",
        "isPrimary": true
      }
    ]
  }'
```

```javascript JavaScript
const addDirector = async (organizationId) => {
  const response = await fetch(
    `https://sandbox.finhub.cloud/api/v2.1/customer/organization/${organizationId}/director`,
    {
      method: 'POST',
      headers: {
        'Accept': 'application/json, text/plain, */*',
        'Content-Type': 'application/json',
        'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
        'Authorization': `Bearer ${token}`,
        'X-Forwarded-From': 'e2e-test',
        'platform': 'web',
        'deviceId': '356938035643809'
      },
      body: JSON.stringify({
        person: {
          firstName: 'John',
          lastName: 'Director',
          email: 'director@acmecorp.com',
          dateOfBirth: '1980-01-15',
          nationality: 'LT',
          gender: 0,
          placeOfBirth: 'Vilnius',
          fullName: 'John Director'
        },
        role: 'MANAGING_DIRECTOR',
        ownershipPercentage: 0,
        isPrimaryContact: false,
        addresses: [{
          type: 'HOME',
          street: '123 Director Street',
          city: 'Vilnius',
          postalCode: '12345',
          country: 'LT',
          isPrimary: true
        }],
        telephoneNumbers: [{
          number: '+37060012345',
          country: 'LT',
          phoneType: 1,
          operator: 'Telia',
          purpose: 'personal',
          isPrimary: true
        }]
      })
    }
  );

  return response.json();
};
```
</CodeGroup>

### Response

<ResponseExample>
```json 200 - Success
{
  "code": 200,
  "message": "Success",
  "data": {
    "individual": {
      "password": "temporaryPassword123!",
      "customerId": "9620561e-a47c-419b-b0f7-ca204f827ef6",
      "tenantId": "d1e2f3a4-b5c6-47d8-9e0f-1a2b3c4d5e6f",
      "userId": "bb9b9fee-205e-474d-8669-fd53e2189403",
      "email": "director@acmecorp.com",
      "username": "director@acmecorp.com"
    },
    "organization": {
      "individual": false,
      "organization": true,
      "adminEmployees": [],
      "organizationId": "ef4a8be6-602b-4b26-b81d-afa7d6d835fd",
      "tenantId": "d1e2f3a4-b5c6-47d8-9e0f-1a2b3c4d5e6f",
      "shareholders": [],
      "employees": [],
      "directors": []
    }
  }
}
```
</ResponseExample>

<Info>
  **Important:** The director is created as an individual customer linked to the organization. Save the temporary password to provide to the director for initial login.
</Info>

---

## Add Shareholders

Add one or more shareholders to an organization.

### Endpoint

```
POST /api/v2.1/customer/organization/{organizationId}/shareholders
```

### Path Parameters

<ParamField path="organizationId" type="string" required>
  Organization UUID identifier
</ParamField>

### Request Body

The request body is an **array** of shareholder objects.

<ParamField body="[n].person" type="object" required>
  Shareholder's personal information (see PersonDto)
</ParamField>

<ParamField body="[n].sharePercentage" type="number" required>
  Ownership percentage (0-100)
  
  <Warning>Total share percentages across all shareholders should sum to 100</Warning>
</ParamField>

<ParamField body="[n].isPrimaryContact" type="boolean" required>
  Whether this shareholder is the primary contact
</ParamField>

<ParamField body="[n].addresses" type="array" required>
  Array of address objects
</ParamField>

<ParamField body="[n].telephoneNumbers" type="array" required>
  Array of telephone numbers
</ParamField>

### Code Example

<CodeGroup>
```bash cURL
curl -X POST "https://sandbox.finhub.cloud/api/v2.1/customer/organization/2f6ddd86-9ef1-45b6-a16d-058b3ccf29e4/shareholders" \
  -H "Accept: application/json, text/plain, */*" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Forwarded-From: e2e-test" \
  -H "platform: web" \
  -H "deviceId: 356938035643809" \
  -d '[
    {
      "person": {
        "firstName": "Alice",
        "lastName": "Shareholder",
        "email": "shareholder1@acmecorp.com",
        "dateOfBirth": "1975-05-20",
        "nationality": "LT",
        "gender": 1,
        "placeOfBirth": "Kaunas",
        "fullName": "Alice Shareholder"
      },
      "sharePercentage": 60,
      "isPrimaryContact": true,
      "addresses": [
        {
          "type": "HOME",
          "street": "456 Shareholder Ave",
          "city": "Kaunas",
          "postalCode": "54321",
          "country": "LT",
          "isPrimary": true
        }
      ],
      "telephoneNumbers": [
        {
          "number": "+37060054321",
          "country": "LT",
          "phoneType": 1,
          "operator": "Tele2",
          "purpose": "personal",
          "isPrimary": true
        }
      ]
    },
    {
      "person": {
        "firstName": "Bob",
        "lastName": "Shareholder",
        "email": "shareholder2@acmecorp.com",
        "dateOfBirth": "1978-08-10",
        "nationality": "LT",
        "gender": 0,
        "placeOfBirth": "Klaipeda",
        "fullName": "Bob Shareholder"
      },
      "sharePercentage": 40,
      "isPrimaryContact": false,
      "addresses": [
        {
          "type": "HOME",
          "street": "789 Owner Street",
          "city": "Klaipeda",
          "postalCode": "98765",
          "country": "LT",
          "isPrimary": true
        }
      ],
      "telephoneNumbers": [
        {
          "number": "+37060098765",
          "country": "LT",
          "phoneType": 1,
          "operator": "Bite",
          "purpose": "personal",
          "isPrimary": true
        }
      ]
    }
  ]'
```

```javascript JavaScript
const addShareholders = async (organizationId, shareholders) => {
  const response = await fetch(
    `https://sandbox.finhub.cloud/api/v2.1/customer/organization/${organizationId}/shareholders`,
    {
      method: 'POST',
      headers: {
        'Accept': 'application/json, text/plain, */*',
        'Content-Type': 'application/json',
        'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
        'Authorization': `Bearer ${token}`,
        'X-Forwarded-From': 'e2e-test',
        'platform': 'web',
        'deviceId': '356938035643809'
      },
      body: JSON.stringify(shareholders)
    }
  );

  return response.json();
};
```
</CodeGroup>

### Response

<ResponseExample>
```json 200 - Success
{
  "code": 200,
  "message": "Success",
  "data": {
    "count": 2
  }
}
```
</ResponseExample>

---

## Add Employee

Add an employee to an organization.

### Endpoint

```
POST /api/v2.1/customer/organization/{organizationId}/employee
```

### Path Parameters

<ParamField path="organizationId" type="string" required>
  Organization UUID identifier
</ParamField>

### Request Body

<ParamField body="person" type="object" required>
  Employee's personal information (see PersonDto)
</ParamField>

<ParamField body="role" type="string" required>
  Primary role identifier
  
  **Valid Roles:**
  - `ADMIN_USER` (Required for at least one employee)
  - `TRANSACTION_APPROVER`
  - `COMPLIANCE_OFFICER`
  - `EMPLOYEE`
</ParamField>

<ParamField body="roles" type="string[]" required>
  Array of role identifiers (can include multiple roles)
  
  Example: `["COMPLIANCE_OFFICER", "TRANSACTION_APPROVER", "EMPLOYEE"]`
</ParamField>

<ParamField body="department" type="string">
  Department name
  
  Examples: `"Finance"`, `"Compliance"`, `"Management"`
</ParamField>

<ParamField body="addresses" type="array" required>
  Array of address objects
</ParamField>

<ParamField body="telephoneNumbers" type="array" required>
  Array of telephone numbers
</ParamField>

### Code Example

<CodeGroup>
```bash cURL
curl -X POST "https://sandbox.finhub.cloud/api/v2.1/customer/organization/2f6ddd86-9ef1-45b6-a16d-058b3ccf29e4/employee" \
  -H "Accept: application/json, text/plain, */*" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Forwarded-From: e2e-test" \
  -H "platform: web" \
  -H "deviceId: 356938035643809" \
  -d '{
    "person": {
      "firstName": "Jane",
      "lastName": "Compliance",
      "email": "compliance@acmecorp.com",
      "dateOfBirth": "1990-03-25",
      "nationality": "LT",
      "gender": 1,
      "placeOfBirth": "Vilnius",
      "fullName": "Jane Compliance"
    },
    "role": "ADMIN_USER",
    "roles": ["ADMIN_USER", "COMPLIANCE_OFFICER", "EMPLOYEE"],
    "department": "Compliance",
    "addresses": [
      {
        "type": "HOME",
        "street": "321 Employee Road",
        "city": "Vilnius",
        "postalCode": "11111",
        "country": "LT",
        "isPrimary": true
      }
    ],
    "telephoneNumbers": [
      {
        "number": "+37060011111",
        "country": "LT",
        "phoneType": 1,
        "operator": "Telia",
        "purpose": "personal",
        "isPrimary": true
      }
    ]
  }'
```
</CodeGroup>

### Response

<ResponseExample>
```json 200 - Success
{
  "code": 200,
  "message": "Success",
  "data": {
    "employeeId": "emp_123456",
    "userId": "user_789012",
    "email": "compliance@acmecorp.com",
    "status": "ACTIVE"
  }
}
```

```json 400 - Missing ADMIN_USER Role
{
  "code": 400,
  "message": "Missing required role 'ADMIN_USER' for BUSINESS_TYPE_CLIENT_TO_TENANT organization. At least one employee must have this role."
}
```
</ResponseExample>

<Info>
  **Adding First Employee**
  
  Your first employee **must** include the `ADMIN_USER` role. After adding an employee with ADMIN_USER, you can add other employees with different roles.
</Info>

---

## Organization Structure Best Practices

### Required Roles

| Role | Minimum Count | Purpose |
|------|---------------|---------|
| `ADMIN_USER` | 1+ | System administration and user management |
| `COMPLIANCE_OFFICER` | 1+ (recommended) | KYC/AML compliance management |
| `TRANSACTION_APPROVER` | 1+ (recommended) | Financial transaction approvals |

### Typical Organization Structure

```
Organization
├── Directors (1-5)
│   └── MANAGING_DIRECTOR (primary)
├── Shareholders (1-10)
│   └── Share percentages sum to 100%
└── Employees (1-50)
    ├── ADMIN_USER (required, 1+)
    ├── COMPLIANCE_OFFICER (recommended)
    ├── TRANSACTION_APPROVER (recommended)
    └── EMPLOYEE (general staff)
```

### Setup Workflow

1. **Register Organization** → Creates basic structure
2. **Add Director(s)** → Legal representatives
3. **Add Shareholder(s)** → Ownership structure
4. **Add Employees** → Must include ADMIN_USER
5. **Verify Organization** → KYB process
6. **Accept Consents** → Legal agreements
7. **Activate Organization** → Enable operations

---

## Common Validation Errors

### Missing ADMIN_USER Role

**Problem:** Cannot complete setup without ADMIN_USER

**Error:**
```json
{
  "code": 400,
  "message": "Missing required role 'ADMIN_USER' for BUSINESS_TYPE_CLIENT_TO_TENANT organization"
}
```

**Solution:** Ensure at least one employee has `ADMIN_USER` in their `roles` array:
```json
{
  "role": "ADMIN_USER",
  "roles": ["ADMIN_USER", "EMPLOYEE"]
}
```

### Duplicate Email

**Problem:** Email already exists in system

**Solution:** Each person (director, shareholder, employee) must have a unique email address within the tenant.

### Invalid Share Percentage

**Problem:** Shareholder percentages don't sum to 100

**Recommendation:** While not strictly enforced, share percentages should typically sum to 100% for accurate ownership representation.

---

## Role Hierarchy and Permissions

### Employee Roles

| Role | Permissions | Required for Activation |
|------|------------|------------------------|
| **ADMIN_USER** | Full organization access, can activate account | ✅ Yes (minimum 1) |
| **COMPLIANCE_OFFICER** | Can approve verifications, activate organization | ✅ Recommended |
| **TRANSACTION_APPROVER** | Can approve high-value transactions | No |
| **EMPLOYEE** | Basic access, transaction operations | No |

### Director Types

| Type | Description | Authority Level |
|------|-------------|----------------|
| **EXECUTIVE** | Executive director with operational control | High |
| **NON_EXECUTIVE** | Advisory role, no day-to-day operations | Medium |
| **INDEPENDENT** | Independent oversight | Medium |

---

## API Schema References

For complete OpenAPI schema specifications:

- [Add Organization Employee](../../../../doc/mint/API_SCHEMA_MAPPING#add-organization-employee)
- [Add Organization Director](../../../../doc/mint/API_SCHEMA_MAPPING#add-organization-director)
- [Add Organization Shareholders](../../../../doc/mint/API_SCHEMA_MAPPING#add-organization-shareholders)

---

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Standard Headers" icon="list" href="../../schemas/standard-headers">
    Complete HTTP headers reference
  </Card>
  
  <Card title="Organization Registration" icon="building" href="./registration">
    Initial organization registration
  </Card>
  
  <Card title="Employees" icon="users" href="./employees">
    Employee management operations
  </Card>
  
  <Card title="Directors" icon="user-tie" href="./directors">
    Director management operations
  </Card>
  
  <Card title="Shareholders" icon="users-viewfinder" href="./shareholders">
    Shareholder management operations
  </Card>
  
  <Card title="Organization Activation" icon="check-circle" href="./activation">
    Activate organization after setup
  </Card>
</CardGroup>

---

## Changelog

| Version | Date | Changes |
|---------|------|---------|
| v2.1 | 2026-01-13 | Initial documentation |



---

# Organization Shareholders API

Manage beneficial owners and shareholders


URL: /baas/api/reference/customer-apis/organization/shareholders



# Organization Shareholders API

APIs for managing beneficial owners and shareholders of business organizations.

<Info>
  **Base URL:** `https://sandbox.finhub.cloud`
</Info>

## Available Operations

<CardGroup cols={3}>
  <Card title="Add Shareholders" icon="user-plus">
    `POST /v2.1/.../shareholders`
  </Card>
  <Card title="List Shareholders" icon="users">
    `GET /v2/organizations/{id}/shareholders`
  </Card>
  <Card title="Remove Shareholder" icon="user-minus">
    `DELETE /v2/organizations/{id}/shareholders/{shareholderId}`
  </Card>
</CardGroup>

<Warning>
  **Note:** List and Remove operations use the `/api/v2/` endpoint path, while Add uses `/api/v2.1/`.
</Warning>

---

## Add Shareholders (v2.1)

<Note>Adds one or more shareholders to the specified organization.</Note>

<Note>
  For complete details on authentication and headers, refer to the [Standard HTTP Headers](../../schemas/standard-headers) reference documentation.
</Note>

### Before You Start

**Prerequisites:**
- Organization must be registered
- You must have ADMIN_USER role
- Total ownership across all shareholders must equal 100%

**Important Validation Rules:**
- Individual vs Corporate shareholders have different required fields
- Beneficial owners (≥25% ownership) require enhanced due diligence
- Ownership percentages must sum to exactly 100%

### Endpoint

`POST /api/v2.1/customer/organization/{organizationId}/shareholders`

### Request

<ParamField path="organizationId" type="string" required>
  Organization identifier
</ParamField>

<ParamField body="type" type="string" required>
  Shareholder type: `INDIVIDUAL` or `CORPORATE`
</ParamField>

<ParamField body="ownershipPercentage" type="number" required>
  Ownership percentage (0-100)
</ParamField>

<ParamField body="firstName" type="string">
  First name (required for INDIVIDUAL)
</ParamField>

<ParamField body="lastName" type="string">
  Last name (required for INDIVIDUAL)
</ParamField>

<ParamField body="companyName" type="string">
  Company name (required for CORPORATE)
</ParamField>

<ParamField body="isBeneficialOwner" type="boolean">
  Whether this is a beneficial owner (25%+ ownership)
</ParamField>

<ParamField body="isPEP" type="boolean">
  Politically Exposed Person status
</ParamField>

### Code Examples

<CodeGroup>
```bash cURL
curl -X POST "https://sandbox.finhub.cloud/api/v2.1/customer/organization/org_12345/shareholders" \
  -H "Accept: application/json, text/plain, */*" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "X-Forwarded-From: e2e-test" \
  -H "platform: web" \
  -H "deviceId: 356938035643809" \
  -d '{
    "type": "INDIVIDUAL",
    "firstName": "Sarah",
    "lastName": "Investor",
    "dateOfBirth": "1980-05-10",
    "nationality": "FR",
    "ownershipPercentage": 25.0,
    "isBeneficialOwner": true,
    "isPEP": false,
    "address": {
      "street": "789 Investor Blvd",
      "city": "Paris",
      "postalCode": "75001",
      "country": "FR"
    }
  }'
```

```javascript JavaScript
const response = await fetch(
  'https://sandbox.finhub.cloud/api/v2.1/customer/organization/org_12345/shareholders',
  {
    method: 'POST',
    headers: {
      'Accept': 'application/json, text/plain, */*',
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${accessToken}`,
      'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
      'X-Forwarded-From': 'e2e-test',
      'platform': 'web',
      'deviceId': '356938035643809'
    },
    body: JSON.stringify({
      type: 'INDIVIDUAL',
      firstName: 'Sarah',
      lastName: 'Investor',
      nationality: 'FR',
      ownershipPercentage: 25.0,
      isBeneficialOwner: true,
      isPEP: false
    })
  }
);

const { data } = await response.json();
console.log('Shareholder ID:', data.shareholderId);
```
</CodeGroup>

<ResponseExample>
```json 201 - Success
{
  "success": true,
  "data": {
    "shareholderId": "sh_11111",
    "status": "PENDING_VERIFICATION",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}
```
</ResponseExample>

---

## List Shareholders (v2)

<Note>Retrieves all shareholders for an organization with ownership percentages.</Note>

### Endpoint

`GET /api/v2/organizations/{organizationId}/shareholders`

### Code Examples

<CodeGroup>
```bash cURL
curl -X GET "https://sandbox.finhub.cloud/api/v2/organizations/org_12345/shareholders" \
  -H "Accept: application/json, text/plain, */*" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "X-Organization-ID: org_12345" \
  -H "X-Forwarded-From: e2e-test" \
  -H "platform: web" \
  -H "deviceId: 356938035643809"
```

```javascript JavaScript
const response = await fetch(
  'https://sandbox.finhub.cloud/api/v2/organizations/org_12345/shareholders',
  {
    headers: {
      'Accept': 'application/json, text/plain, */*',
      'Authorization': `Bearer ${accessToken}`,
      'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
      'X-Organization-ID': 'org_12345',
      'X-Forwarded-From': 'e2e-test',
      'platform': 'web',
      'deviceId': '356938035643809'
    }
  }
);

const { data } = await response.json();
data.shareholders.forEach(s => {
  const name = s.type === 'INDIVIDUAL' ? `${s.firstName} ${s.lastName}` : s.companyName;
  console.log(`${name}: ${s.ownershipPercentage}%`);
});
```
</CodeGroup>

<ResponseExample>
```json 200 - Success
{
  "success": true,
  "data": {
    "shareholders": [
      {
        "shareholderId": "sh_12345",
        "type": "INDIVIDUAL",
        "firstName": "Max",
        "lastName": "Owner",
        "ownershipPercentage": 51.0,
        "isBeneficialOwner": true,
        "status": "VERIFIED"
      }
    ]
  }
}
```
</ResponseExample>

---

## Remove Shareholder (v2)

<Note>Removes a shareholder from the organization (requires ADMIN_USER role).</Note>

### Endpoint

`DELETE /api/v2/organizations/{organizationId}/shareholders/{shareholderId}`

### Code Examples

<CodeGroup>
```bash cURL
curl -X DELETE "https://sandbox.finhub.cloud/api/v2/organizations/org_12345/shareholders/sh_12345" \
  -H "Accept: application/json, text/plain, */*" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "X-Organization-ID: org_12345" \
  -H "X-User-Roles: ADMIN_USER" \
  -H "X-Forwarded-From: e2e-test" \
  -H "platform: web" \
  -H "deviceId: 356938035643809"
```
</CodeGroup>

<ResponseExample>
```json 204 - Success
{
  "success": true
}
```
</ResponseExample>

---

## Beneficial Ownership Rules

- Individuals owning **25% or more** must be declared as beneficial owners
- Corporate shareholders must disclose their own beneficial owners
- PEP (Politically Exposed Person) status must be declared

---

## Shareholder Types Comparison

| Field | Individual Shareholder | Corporate Shareholder |
|-------|----------------------|----------------------|
| **Required** | firstName, lastName, dateOfBirth, nationality | companyName, registrationNumber, country |
| **Ownership** | ownershipPercentage, numberOfShares | ownershipPercentage, numberOfShares |
| **Identity** | Passport/ID number | Tax ID, incorporation docs |
| **Contact** | Personal email, phone | Contact person details |
| **Due Diligence** | PEP check if ≥25% | UBO disclosure required |

---

## Ownership Validation (100% Rule)

When adding shareholders, the system validates that total ownership equals 100%:

```javascript
// Example: Adding multiple shareholders
const shareholders = [
  { name: "Founder A", ownershipPercentage: 60.0 },
  { name: "Founder B", ownershipPercentage: 30.0 },
  { name: "Investor C", ownershipPercentage: 10.0 }
];
// Total: 100% ✅ Valid

// This would fail:
const invalidShareholders = [
  { name: "Founder A", ownershipPercentage: 60.0 },
  { name: "Founder B", ownershipPercentage: 30.0 }
];
// Total: 90% ❌ Invalid - missing 10%
```

---

## Share Classes

| Share Class | Description | Voting Rights |
|------------|-------------|---------------|
| **ORDINARY** | Standard common shares | Yes |
| **PREFERENCE** | Preference shares with priority dividends | Usually limited |
| **REDEEMABLE** | Can be bought back by company | Yes or No |

---

## Response Codes

| Code | Description |
|------|-------------|
| `200` | Shareholders retrieved/updated successfully |
| `201` | Shareholder added successfully |
| `204` | Shareholder removed successfully |
| `400` | Invalid request data or ownership validation failed |
| `409` | Ownership total does not equal 100% |
| `404` | Organization or shareholder not found |
| `500` | Internal server error |

---

## Common Validation Errors

### Error: Ownership Total Mismatch
**Problem:** Total ownership across all shareholders ≠ 100%

**Solution:**
```json
{
  "error": "Ownership validation failed",
  "currentTotal": 95.0,
  "required": 100.0,
  "missing": 5.0
}
```
Review all shareholder percentages and ensure they sum to exactly 100%.

### Error: Beneficial Owner Not Declared
**Problem:** Shareholder with ≥25% ownership not marked as beneficial owner

**Solution:**
Set `isBeneficialOwner: true` for any shareholder with 25% or more ownership.

### Error: Missing Required Fields
**Problem:** Individual shareholder missing personal details

**Solution:**
Ensure all required fields are provided:
- Individual: firstName, lastName, dateOfBirth, nationality
- Corporate: companyName, registrationNumber, taxId, country

---

## API Schema Reference

For the complete OpenAPI schema specification, see the [API Schema Mapping](../../../../doc/mint/API_SCHEMA_MAPPING#add-organization-shareholders) document.

---

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Standard Headers" icon="list" href="../../schemas/standard-headers">
    Complete HTTP headers reference
  </Card>
  
  <Card title="Organization Registration" icon="building" href="./registration">
    Register new organizations
  </Card>
  
  <Card title="Directors" icon="user-tie" href="./directors">
    Manage organization directors
  </Card>
  
  <Card title="Employees" icon="users" href="./employees">
    Manage organization employees
  </Card>
</CardGroup>


---

# Organization Verify (KYB Initiation)

Initiate KYB verification for an organization


URL: /baas/api/reference/customer-apis/organization/verify



import { RequiredRunnerHeadersWithUserContext } from '../../schemas/required-headers-snippet.mdx';

# Organization Verify (KYB Initiation)

Starts a business verification flow using `BUSINESS_VERIFICATION` and `TENANT_VERIFIED`.

## Endpoint

`POST /api/v2.1/customer/organization/{organizationId}/verify`

## Required Headers

<RequiredRunnerHeadersWithUserContext />

## Request Example

```json
{
  "customerId": "f458d016-56bb-43a6-856c-4d0456b2c38c",
  "type": "BUSINESS_VERIFICATION",
  "requestedLevel": "TENANT_VERIFIED",
  "requestedByUserId": "da9a15d2-1eb9-4804-a812-b58b03f33018",
  "requestedByTenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
  "notes": "Business Verification"
}
```

## Success Response

```json 200
{
  "code": 200,
  "data": {
    "verificationId": "ac0d408e-06b8-420c-9876-745db4ea4c98",
    "status": "PENDING",
    "verificationType": "KYB"
  },
  "message": "Success"
}
```

<Note>
  Used in B2B flow Step 6 (with fallback to `POST /api/v2.1/verifications`).
</Note>


---

# Organization Verification (KYB)

Know Your Business (KYB) verification process for organizations


URL: /baas/api/reference/customer-apis/organization/verification



# Organization Verification (KYB)

Complete Know Your Business (KYB) verification process for business organizations, including document verification, personnel checks, and beneficial owner identification.

<Info>
  **Base URL:** `https://sandbox.finhub.cloud`
</Info>

<Note>
  For complete details on authentication and headers, refer to the [Standard HTTP Headers](../../schemas/standard-headers) reference documentation.
</Note>

---

## Verification Levels

| Level | Description | Approval Required | Typical Use Case |
|-------|-------------|-------------------|------------------|
| **TENANT_VERIFIED** | Basic business verification | TENANT_ADMIN | Standard businesses, low-risk sectors |
| **POWER_TENANT_VERIFIED** | Enhanced due diligence | POWER_TENANT (Super Admin) | High-risk businesses, large transactions, PEPs |

<Warning>
  **High-Risk Organizations** require POWER_TENANT_VERIFIED level:
  - Money service businesses
  - Cryptocurrency exchanges
  - Gambling/gaming businesses
  - Organizations with PEP directors or beneficial owners
  - Organizations from high-risk jurisdictions
</Warning>

---

## Complete KYB Verification Flow

### Step 1: Initiate Verification

Check what verification is required for the organization.

**Endpoint:** `GET /api/v2.1/customer/organization/{organizationId}/verification/requirements`

<CodeGroup>
```bash cURL
curl -X GET "https://sandbox.finhub.cloud/api/v2.1/customer/organization/org_12345/verification/requirements" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "X-Forwarded-From: e2e-test" \
  -H "User-Agent: YourApp/1.0" \
  -H "platform: web" \
  -H "deviceId: 356938035643809"
```

```javascript JavaScript
const response = await fetch(
  'https://sandbox.finhub.cloud/api/v2.1/customer/organization/org_12345/verification/requirements',
  {
    headers: {
      'Accept': 'application/json, text/plain, */*',
      'Authorization': `Bearer ${accessToken}`,
      'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
      'X-Forwarded-From': 'e2e-test',
      'User-Agent': 'YourApp/1.0',
      'platform': 'web',
      'deviceId': '356938035643809'
    }
  }
);

const { data } = await response.json();
console.log('Required documents:', data.requiredDocuments);
console.log('Verification level:', data.verificationLevel);
```

```python Python
import requests

response = requests.get(
    'https://sandbox.finhub.cloud/api/v2.1/customer/organization/org_12345/verification/requirements',
    headers={
        'Accept': 'application/json, text/plain, */*',
        'Authorization': f'Bearer {access_token}',
        'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
        'X-Forwarded-From': 'e2e-test',
        'User-Agent': 'YourApp/1.0',
        'platform': 'web',
        'deviceId': '356938035643809'
    }
)

data = response.json()['data']
print(f"Required documents: {data['requiredDocuments']}")
print(f"Verification level: {data['verificationLevel']}")
```
</CodeGroup>

**Response:**

```json
{
  "success": true,
  "data": {
    "organizationId": "org_12345",
    "verificationLevel": "TENANT_VERIFIED",
    "requiredDocuments": [
      "CERTIFICATE_OF_INCORPORATION",
      "ARTICLES_OF_ASSOCIATION",
      "SHAREHOLDER_REGISTER",
      "DIRECTOR_ID",
      "BENEFICIAL_OWNER_DECLARATION",
      "BANK_STATEMENT"
    ],
    "requiredPersonnelVerification": {
      "directors": {
        "minimum": 1,
        "requireIdVerification": true,
        "requirePepCheck": true
      },
      "beneficialOwners": {
        "minimum": 1,
        "ownershipThreshold": 25.0,
        "requireIdVerification": true,
        "requirePepCheck": true
      }
    },
    "estimatedReviewTime": "2-5 business days"
  }
}
```

---

### Step 2: Submit Verification Documents

Upload required documents to the verification process.

**Endpoint:** `POST /api/v2.1/verifications/{verificationId}/documents`

<Note>
  Use the verification ID returned from Step 1. Documents are uploaded as JSON with base64-encoded content.
</Note>

<CodeGroup>
```bash cURL
curl -X POST "https://sandbox.finhub.cloud/api/v2.1/verifications/ver_12345/documents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "X-Forwarded-From: e2e-test" \
  -H "User-Agent: YourApp/1.0" \
  -H "platform: web" \
  -H "deviceId: 356938035643809" \
  -d '{
    "docId": "550e8400-e29b-41d4-a716-446655440000",
    "documentType": "CERTIFICATE_OF_INCORPORATION",
    "fileName": "incorporation_cert.pdf",
    "fileContent": "JVBERi0xLjQKJeLjz9MKNyAwIG9iaiA8PAovVHlwZSAvQ2F0YWxvZy...",
    "customerId": "org_12345",
    "description": "Company registration certificate"
  }'
```

```javascript JavaScript
const { v4: uuidv4 } = require('uuid');
const fs = require('fs');

// Read file and convert to base64
const fileBuffer = fs.readFileSync('/path/to/incorporation_cert.pdf');
const base64Content = fileBuffer.toString('base64');

const response = await fetch(
  'https://sandbox.finhub.cloud/api/v2.1/verifications/ver_12345/documents',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${accessToken}`,
      'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
      'X-Forwarded-From': 'e2e-test',
      'User-Agent': 'YourApp/1.0',
      'platform': 'web',
      'deviceId': '356938035643809'
    },
    body: JSON.stringify({
      docId: uuidv4(),
      documentType: 'CERTIFICATE_OF_INCORPORATION',
      fileName: 'incorporation_cert.pdf',
      fileContent: base64Content,
      customerId: organizationId,
      description: 'Company registration certificate'
    })
  }
);

const { data } = await response.json();
console.log('Document uploaded:', data.documentId);
```

```python Python
import requests
import base64
from uuid import uuid4

# Read and encode file
with open('/path/to/incorporation_cert.pdf', 'rb') as f:
    base64_content = base64.b64encode(f.read()).decode('utf-8')

response = requests.post(
    'https://sandbox.finhub.cloud/api/v2.1/verifications/ver_12345/documents',
    headers={
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {access_token}',
        'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
        'X-Forwarded-From': 'e2e-test',
        'User-Agent': 'YourApp/1.0',
        'platform': 'web',
        'deviceId': '356938035643809'
    },
    json={
        'docId': str(uuid4()),
        'documentType': 'CERTIFICATE_OF_INCORPORATION',
        'fileName': 'incorporation_cert.pdf',
        'fileContent': base64_content,
        'customerId': 'org_12345',
        'description': 'Company registration certificate'
    }
)

data = response.json()['data']
print(f"Document uploaded: {data['documentId']}")
```
</CodeGroup>

**Request Body:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `docId` | string (UUID) | Yes | Unique document identifier (generate using UUID v4) |
| `documentType` | string | Yes | Document type from the table below |
| `fileName` | string | Yes | Original file name with extension (.pdf, .jpg, .png) |
| `fileContent` | string | Yes | Base64-encoded file content |
| `customerId` | string | Yes | Organization ID from registration |
| `description` | string | No | Document purpose or description |

**Response:**

```json
{
  "success": true,
  "data": {
    "documentId": "doc_67890",
    "verificationId": "ver_12345",
    "status": "UPLOADED",
    "uploadedAt": "2026-01-13T10:30:00Z"
  }
}
```

**Required Documents:**

| Document Type | Value for `documentType` | Required For | Description |
|--------------|--------------------------|--------------|-------------|
| **Certificate of Incorporation** | `CERTIFICATE_OF_INCORPORATION` | All | Proof of company registration |
| **Articles of Association** | `ARTICLES_OF_ASSOCIATION` | All | Company bylaws/constitution |
| **Proof of Registered Address** | `PROOF_OF_REGISTERED_ADDRESS` | All | Registered office address proof |
| **Beneficial Owners Declaration** | `BENEFICIAL_OWNERS_DECLARATION` | All | UBO form (25%+ ownership) |
| **Bank Statement** | `BANK_STATEMENT` | All | Last 3 months business statements |
| **Director IDs** | `DIRECTOR_ID` | All | Passport/ID for each director |
| **Financial Statements** | `FINANCIAL_STATEMENTS` | Large businesses | Audited accounts (revenue > €1M) |
| **Business License** | `BUSINESS_LICENSE` | Regulated sectors | Industry-specific licenses |

<Tip>
  **File Requirements:**
  - Formats: PDF, JPG, PNG
  - Maximum size: 10MB per file
  - Base64 encoding required for JSON upload
  - Use UTF-8 encoding for file names
</Tip>

---

### Step 3: Personnel Verification Check

Ensure all required personnel are added and verified:

**Endpoint:** `GET /api/v2.1/customer/organization/{organizationId}/verification/personnel-status`

```bash cURL
curl -X GET "https://sandbox.finhub.cloud/api/v2.1/customer/organization/org_12345/verification/personnel-status" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "X-Forwarded-From: e2e-test" \
  -H "User-Agent: YourApp/1.0" \
  -H "platform: web" \
  -H "deviceId: 356938035643809"
```

**Response:**

```json
{
  "success": true,
  "data": {
    "directors": {
      "total": 2,
      "verified": 2,
      "pending": 0,
      "status": "COMPLETE"
    },
    "beneficialOwners": {
      "total": 2,
      "verified": 2,
      "totalOwnership": 100.0,
      "status": "COMPLETE"
    },
    "employees": {
      "total": 5,
      "withAdminRole": 1,
      "status": "COMPLETE"
    },
    "overallStatus": "READY_FOR_VERIFICATION"
  }
}
```

---

### Step 4: Submit Verification Request

Once all documents and personnel are in place, submit for verification.

**Endpoint:** `POST /api/v2.1/customer/organization/{organizationId}/verification`

**Request Body:**

```json
{
  "verificationType": "KYB",
  "verificationLevel": "TENANT_VERIFIED",
  "priority": "NORMAL",
  "verificationData": {
    "businessPurpose": "Import/export of electronic goods",
    "expectedAnnualRevenue": "€500,000 - €1,000,000",
    "expectedTransactionVolume": "50-100 transactions/month",
    "sourceOfFunds": "Business revenue and investor capital",
    "primaryJurisdictions": ["DE", "FR", "NL"]
  }
}
```

<CodeGroup>
```bash cURL
curl -X POST "https://sandbox.finhub.cloud/api/v2.1/customer/organization/org_12345/verification" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "X-Forwarded-From: e2e-test" \
  -H "User-Agent: YourApp/1.0" \
  -H "platform: web" \
  -H "deviceId: 356938035643809" \
  -d '{
    "verificationType": "KYB",
    "verificationLevel": "TENANT_VERIFIED",
    "priority": "NORMAL",
    "verificationData": {
      "businessPurpose": "Import/export of electronic goods",
      "expectedAnnualRevenue": "€500,000 - €1,000,000"
    }
  }'
```

```javascript JavaScript
const response = await fetch(
  'https://sandbox.finhub.cloud/api/v2.1/customer/organization/org_12345/verification',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${accessToken}`,
      'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
      'X-Forwarded-From': 'e2e-test',
      'User-Agent': 'YourApp/1.0',
      'platform': 'web',
      'deviceId': '356938035643809'
    },
    body: JSON.stringify({
      verificationType: 'KYB',
      verificationLevel: 'TENANT_VERIFIED',
      priority: 'NORMAL',
      verificationData: {
        businessPurpose: 'Import/export of electronic goods',
        expectedAnnualRevenue: '€500,000 - €1,000,000'
      }
    })
  }
);

const { data } = await response.json();
console.log('Verification ID:', data.verificationId);
console.log('Status:', data.status);
```

```python Python
import requests

response = requests.post(
    'https://sandbox.finhub.cloud/api/v2.1/customer/organization/org_12345/verification',
    headers={
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {access_token}',
        'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
        'X-Forwarded-From': 'e2e-test',
        'User-Agent': 'YourApp/1.0',
        'platform': 'web',
        'deviceId': '356938035643809'
    },
    json={
        'verificationType': 'KYB',
        'verificationLevel': 'TENANT_VERIFIED',
        'priority': 'NORMAL',
        'verificationData': {
            'businessPurpose': 'Import/export of electronic goods',
            'expectedAnnualRevenue': '€500,000 - €1,000,000'
        }
    }
)

data = response.json()['data']
print(f"Verification ID: {data['verificationId']}")
print(f"Status: {data['status']}")
```
</CodeGroup>

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "verificationId": "ver_org_67890",
    "organizationId": "org_12345",
    "status": "PENDING_REVIEW",
    "type": "KYB",
    "level": "TENANT_VERIFIED",
    "submittedAt": "2024-01-15T10:30:00Z",
    "estimatedCompletionTime": "2-5 business days",
    "requiredDocuments": [
      {
        "documentType": "CERTIFICATE_OF_INCORPORATION",
        "status": "SUBMITTED",
        "submittedAt": "2024-01-15T09:00:00Z"
      },
      {
        "documentType": "ARTICLES_OF_ASSOCIATION",
        "status": "SUBMITTED",
        "submittedAt": "2024-01-15T09:15:00Z"
      }
    ],
    "personnelChecks": {
      "directors": "COMPLETE",
      "beneficialOwners": "COMPLETE",
      "pepScreening": "IN_PROGRESS"
    },
    "nextSteps": [
      "Wait for compliance review",
      "PEP and sanctions screening in progress",
      "You will be notified via email when verification is complete"
    ]
  }
}
```

---

### Step 5: Check Verification Status

Poll for verification status updates.

**Endpoint:** `GET /api/v2.1/customer/organization/{organizationId}/verification/status`

<CodeGroup>
```bash cURL
curl -X GET "https://sandbox.finhub.cloud/api/v2.1/customer/organization/org_12345/verification/status" \
  -H "Accept: application/json, text/plain, */*" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "X-Forwarded-From: e2e-test" \
  -H "platform: web" \
  -H "deviceId: 356938035643809"
```

```javascript JavaScript
const response = await fetch(
  'https://sandbox.finhub.cloud/api/v2.1/customer/organization/org_12345/verification/status',
  {
    headers: {
      'Accept': 'application/json, text/plain, */*',
      'Authorization': `Bearer ${accessToken}`,
      'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
      'X-Forwarded-From': 'e2e-test',
      'platform': 'web',
      'deviceId': '356938035643809'
    }
  }
);

const { data } = await response.json();
console.log('Status:', data.status);
if (data.status === 'APPROVED') {
  console.log('✅ Verification approved! Ready for activation.');
}
```

```python Python
import requests

response = requests.get(
    'https://sandbox.finhub.cloud/api/v2.1/customer/organization/org_12345/verification/status',
    headers={
        'Accept': 'application/json, text/plain, */*',
        'Authorization': f'Bearer {access_token}',
        'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
        'X-Forwarded-From': 'e2e-test',
        'platform': 'web',
        'deviceId': '356938035643809'
    }
)

data = response.json()['data']
print(f"Status: {data['status']}")
if data['status'] == 'APPROVED':
    print("✅ Verification approved! Ready for activation.")
```
</CodeGroup>

**Response (Approved):**

```json
{
  "success": true,
  "data": {
    "verificationId": "ver_org_67890",
    "organizationId": "org_12345",
    "status": "APPROVED",
    "type": "KYB",
    "level": "TENANT_VERIFIED",
    "submittedAt": "2024-01-15T10:30:00Z",
    "reviewedAt": "2024-01-17T14:20:00Z",
    "approvedAt": "2024-01-17T14:20:00Z",
    "reviewedBy": "compliance_officer_01",
    "approvalRequired": "TENANT_ADMIN",
    "verificationChecks": {
      "documentsVerified": true,
      "directorsVerified": true,
      "beneficialOwnersVerified": true,
      "pepScreening": "CLEAR",
      "sanctionsScreening": "CLEAR",
      "adverseMediaScreening": "CLEAR"
    },
    "reviewNotes": "All documents verified. Business purpose and structure validated. No adverse findings.",
    "nextSteps": [
      "Proceed to consent acceptance",
      "Then activate organization"
    ]
  }
}
```

---

## Verification Status Flow

```mermaid
stateDiagram-v2
    [*] --> NOT_STARTED: Organization registered
    NOT_STARTED --> PREPARING: Add documents & personnel
    PREPARING --> PENDING_REVIEW: Submit verification
    PENDING_REVIEW --> UNDER_REVIEW: Compliance starts review
    UNDER_REVIEW --> APPROVED: All checks pass
    UNDER_REVIEW --> ADDITIONAL_INFO_REQUIRED: Need more info
    UNDER_REVIEW --> REJECTED: Failed checks
    ADDITIONAL_INFO_REQUIRED --> UNDER_REVIEW: Info provided
    REJECTED --> PREPARING: Fix issues and resubmit
    APPROVED --> [*]: Ready for activation
```

### Status Descriptions

| Status | Description | Next Action |
|--------|-------------|-------------|
| **NOT_STARTED** | Documents/personnel not yet submitted | Upload documents, add personnel |
| **PREPARING** | Documents being uploaded | Complete all uploads, then submit |
| **PENDING_REVIEW** | Submitted, queued for review | Wait for compliance officer |
| **UNDER_REVIEW** | Being reviewed by compliance | Wait for decision (2-5 days) |
| **ADDITIONAL_INFO_REQUIRED** | More information needed | Provide requested information |
| **APPROVED** | Verification successful | Proceed to consent & activation |
| **REJECTED** | Verification failed | Review reasons, fix issues, resubmit |

---

## Step 6: Verification Approval (Admin)

For organizations requiring **TENANT_ADMIN** or **POWER_TENANT** approval.

**Endpoint:** `POST /api/v2.1/customer/organization/{organizationId}/verification/approve`

**Required Role:** `COMPLIANCE_OFFICER` or `ADMIN_USER`

**Request:**

```json
{
  "verificationId": "ver_org_67890",
  "approved": true,
  "approvalNotes": "All KYB checks completed successfully. Documents verified. PEP and sanctions screening clear.",
  "conditions": []
}
```

**Response:**

```json
{
  "success": true,
  "data": {
    "verificationId": "ver_org_67890",
    "status": "APPROVED",
    "approvedAt": "2024-01-17T14:20:00Z",
    "approvedBy": "compliance_officer_01",
    "nextSteps": [
      "Organization is now verified",
      "Proceed to consent acceptance",
      "Then activate organization"
    ]
  }
}
```

---

## UBO (Ultimate Beneficial Owner) Requirements

Organizations must declare all UBOs (individuals owning ≥25% of the company).

### UBO Verification Checklist

- [ ] All shareholders with ≥25% ownership declared
- [ ] Each UBO has submitted ID verification
- [ ] PEP screening completed for all UBOs
- [ ] Sanctions screening completed for all UBOs
- [ ] Source of wealth documented for UBOs
- [ ] Control structure diagram uploaded (if complex)

### Complex Ownership Structures

For organizations with multi-tier ownership (e.g., Company A owns Company B):

1. Upload ownership structure diagram
2. Declare all natural persons with ≥25% indirect ownership
3. Provide incorporation documents for parent companies
4. Complete enhanced due diligence for all layers

---

## Response Codes

| Code | Description |
|------|-------------|
| `200` | Verification status retrieved successfully |
| `201` | Verification submitted successfully |
| `400` | Missing required documents or personnel |
| `403` | Insufficient permissions |
| `404` | Organization not found |
| `422` | Verification prerequisites not met |
| `500` | Internal server error |

---

## Common Verification Errors

### Error: Missing Required Documents
**Problem:** Not all required documents uploaded

**Solution:**
Check verification requirements and upload all documents:
```bash
GET /api/v2.1/customer/organization/{orgId}/verification/requirements
```

### Error: Ownership Validation Failed
**Problem:** Shareholder ownership doesn't total 100%

**Solution:**
Ensure all shareholders are declared and ownership percentages sum to exactly 100%.

### Error: Missing Admin User
**Problem:** No employee with ADMIN_USER role

**Solution:**
Add at least one employee with ADMIN_USER role before submitting verification.

### Error: Director Not Verified
**Problem:** One or more directors missing ID verification

**Solution:**
Ensure all directors have submitted valid identification documents.

---

## API Schema Reference

For the complete OpenAPI schema specification, see the API Schema Mapping documentation (Organization Verification operation - to be added).

---

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Standard Headers" icon="list" href="../../schemas/standard-headers">
    Complete HTTP headers reference
  </Card>
  
  <Card title="Documents" icon="folder" href="./documents">
    Upload verification documents
  </Card>
  
  <Card title="Management" icon="users" href="./management">
    Add directors, employees, shareholders
  </Card>
  
  <Card title="Consents" icon="file-signature" href="./consents">
    Accept organization consents
  </Card>
  
  <Card title="Activation" icon="check-circle" href="./activation">
    Activate verified organization
  </Card>
  
  <Card title="Individual Verification" icon="user-check" href="/baas/api/reference/verification-compliance">
    Individual KYC verification
  </Card>
</CardGroup>

---

## Changelog

| Version | Date | Changes |
|---------|------|---------|
| v1.0 | 2026-01-13 | Initial organization verification documentation |



---

# Organization Activation API

Activate verified organization accounts


URL: /baas/api/reference/customer-apis/organization/activation



import { RequiredRunnerHeadersWithUserContext } from '../../schemas/required-headers-snippet.mdx';

# Organization Activation API

Activate a verified organization account to enable wallet operations and financial transactions.

<Note>
  For complete details on authentication and headers, refer to the [Standard HTTP Headers](../../schemas/standard-headers) reference documentation.
</Note>

<Warning>
  **Role Requirement:** Only users with **COMPLIANCE_OFFICER** or **ADMIN_USER** roles can activate an organization.
</Warning>

---

## Prerequisites Checklist (14-Step Validation)

Before attempting activation, the system validates **14 prerequisites**:

### 1. Organization Structure (4 checks)
- [ ] Organization registered and status = `PENDING_ACTIVATION`
- [ ] At least 1 director added
- [ ] At least 1 employee with **ADMIN_USER** role
- [ ] Total shareholder ownership = **100%** exactly

### 2. Verification (3 checks)
- [ ] KYB verification completed
- [ ] Verification status = **APPROVED**
- [ ] All personnel (directors, UBOs) verified

### 3. Consents (3 checks)
- [ ] Terms and Conditions accepted
- [ ] Privacy Policy accepted
- [ ] Data Processing Agreement accepted

### 4. Documents (2 checks)
- [ ] All required corporate documents uploaded
- [ ] All documents status = **VERIFIED**

### 5. Authorization (2 checks)
- [ ] User has **COMPLIANCE_OFFICER** or **ADMIN_USER** role
- [ ] User is linked to the organization

<Info>
  **Check Activation Readiness:** Use `GET /{organizationId}/activation/readiness` to validate all prerequisites before attempting activation.
</Info>

---

## Endpoint

```
POST /api/v2.1/customer/organization/{organizationId}/activation
```

---

## Headers

<RequiredRunnerHeadersWithUserContext />

<ParamField header="X-Tenant-ID" type="string" required>
  Tenant identifier
  
  Example: `97e7ff29-15f3-49ef-9681-3bbfcce4f6cd`
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication (admin privileges required)
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`
</ParamField>

<ParamField header="Accept" type="string">
  Response format (optional — defaults to `application/json`)
  
  Example: `application/json, text/plain, */*`
</ParamField>

<ParamField header="X-User-ID" type="string" required>
  User ID of the admin performing activation
  
  Example: `e2f3a4b5-c6d7-48e9-0f1a-2b3c4d5e6f7a`
</ParamField>

<ParamField header="X-User-Roles" type="string" required>
  Comma-separated list of user roles
  
  Example: `ADMIN_USER,COMPLIANCE_OFFICER`
</ParamField>

<ParamField header="X-Forwarded-From" type="string" required>
  Source identifier for request origin tracking
  
  Example: `e2e-test`
</ParamField>

<ParamField header="User-Agent" type="string" required>
  Client application identifier — required by the global request filter
  
  Example: `YourApp/1.0` or `Mozilla/5.0 (Windows NT 10.0; Win64; x64)`
</ParamField>

<ParamField header="platform" type="string" required>
  Client platform identifier. Also accepted as `sec-ch-ua-platform`
  
  Example: `web`
</ParamField>

<ParamField header="deviceId" type="string" required>
  Unique device identifier for session tracking. Also accepted as `X-Device-Id` or `device-id`
  
  Example: `356938035643809`
</ParamField>

---

## Path Parameters

<ParamField path="organizationId" type="string" required>
  Organization UUID identifier
  
  Example: `ef4a8be6-602b-4b26-b81d-afa7d6d835fd`
</ParamField>

---

## Request Body

<ParamField body="activationReason" type="string" required>
  Reason for activation
  
  Example: `"Organization account activation after KYB completion"`
</ParamField>

<ParamField body="additionalInfo" type="object">
  Optional metadata about the activation
  
  <Expandable title="additionalInfo properties">
    <ParamField body="userId" type="string">
      User ID performing the activation
      
      Example: `"87b3af37-4ac1-402b-a0ea-53cfdc695e02"`
    </ParamField>
    
    <ParamField body="activationCode" type="string">
      Activation code for verification
      
      Example: `"E2E_TEST"`
    </ParamField>
  </Expandable>
</ParamField>

---

## Code Examples

<CodeGroup>
```bash cURL
curl -X POST "https://sandbox.finhub.cloud/api/v2.1/customer/organization/ef4a8be6-602b-4b26-b81d-afa7d6d835fd/activation" \
  -H "Accept: application/json, text/plain, */*" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-User-ID: e2f3a4b5-c6d7-48e9-0f1a-2b3c4d5e6f7a" \
  -H "X-User-Roles: ADMIN_USER,COMPLIANCE_OFFICER" \
  -H "X-Forwarded-From: e2e-test" \
  -H "platform: web" \
  -H "deviceId: 356938035643809" \
  -d '{
    "activationReason": "E2E Test Activation",
    "additionalInfo": {
      "userId": "87b3af37-4ac1-402b-a0ea-53cfdc695e02",
      "activationCode": "E2E_TEST"
    }
  }'
```

```javascript JavaScript
const activateOrganization = async (organizationId, userId, userRoles) => {
  const response = await fetch(
    `https://sandbox.finhub.cloud/api/v2.1/customer/organization/${organizationId}/activation`,
    {
      method: 'POST',
      headers: {
        'Accept': 'application/json, text/plain, */*',
        'Content-Type': 'application/json',
        'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
        'Authorization': `Bearer ${accessToken}`,
        'X-User-ID': userId,
        'X-User-Roles': userRoles,
        'X-Forwarded-From': 'e2e-test',
        'platform': 'web',
        'deviceId': '356938035643809'
      },
      body: JSON.stringify({
        activationReason: 'E2E Test Activation',
        additionalInfo: {
          userId: userId,
          activationCode: 'E2E_TEST'
        }
      })
    }
  );

  return response.json();
};
```

```python Python
import requests

def activate_organization(organization_id, user_id, user_roles):
    url = f'https://sandbox.finhub.cloud/api/v2.1/customer/organization/{organization_id}/activation'
    
    headers = {
        'Accept': 'application/json, text/plain, */*',
        'Content-Type': 'application/json',
        'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
        'Authorization': f'Bearer {access_token}',
        'X-User-ID': user_id,
        'X-User-Roles': user_roles,
        'X-Forwarded-From': 'e2e-test',
        'platform': 'web',
        'deviceId': '356938035643809'
    }
    
    payload = {
        'activationReason': 'Organization account activation after KYB completion',
        'additionalInfo': {
            'testRun': False,
            'activatedBy': 'Admin User'
        }
    }
    
    response = requests.post(url, headers=headers, json=payload)
    return response.json()
```
</CodeGroup>

---

## Response

<ResponseExample>
```json 200 - Success
{
  "code": 200,
  "message": "Organization activated successfully",
  "data": {
    "wallet": {
      "walletId": "49a2fe3a-a9df-48dc-9da3-e9dff8eb4968",
      "balance": "0.00",
      "currency": "EUR",
      "id": "49a2fe3a-a9df-48dc-9da3-e9dff8eb4968",
      "status": "ACTIVE"
    },
    "iban": "LT963500070344952515",
    "activation": {
      "message": "Organization activated successfully",
      "status": "ACTIVE",
      "activatedAt": "2026-01-13T10:04:12.830711352",
      "warnings": [
        "No employees found - consider adding employees with required roles"
      ]
    }
  }
}
```

```json 400 - Missing Prerequisites
{
  "code": 400,
  "message": "Organization verification not completed"
}
```

```json 400 - Missing Consents
{
  "code": 400,
  "message": "Required consents not accepted. Please accept Terms, Privacy, and Data Processing consents."
}
```
</ResponseExample>

---

## Response Fields

<ResponseField name="code" type="integer">
  HTTP status code
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable status message
</ResponseField>

<ResponseField name="data" type="object">
  Activation result data
  
  <Expandable title="data properties">
    <ResponseField name="wallet" type="object">
      Created wallet information
      
      <Expandable title="wallet properties">
        <ResponseField name="walletId" type="string">
          Unique wallet identifier
        </ResponseField>
        
        <ResponseField name="balance" type="string">
          Initial balance (formatted)
        </ResponseField>
        
        <ResponseField name="currency" type="string">
          Wallet currency (typically EUR)
        </ResponseField>
        
        <ResponseField name="status" type="string">
          Wallet status: `ACTIVE`
        </ResponseField>
      </Expandable>
    </ResponseField>
    
    <ResponseField name="iban" type="string">
      Generated IBAN for the organization
      
      Example: `LT963500070344952515`
    </ResponseField>
    
    <ResponseField name="activation" type="object">
      Activation details
      
      <Expandable title="activation properties">
        <ResponseField name="status" type="string">
          Activation status: `ACTIVE`
        </ResponseField>
        
        <ResponseField name="activatedAt" type="string">
          ISO 8601 timestamp of activation
        </ResponseField>
        
        <ResponseField name="message" type="string">
          Activation message
        </ResponseField>
        
        <ResponseField name="warnings" type="array">
          Array of warning messages (if any)
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

---

## Common Activation Warnings

The API may return warnings in the activation response. These warnings do not prevent activation but indicate configuration issues that should be addressed:

| Warning | Meaning | Action Required |
|---------|---------|----------------|
| `No employees found - consider adding employees with required roles` | Organization has no employees | Add employees for production use |
| `Missing ADMIN_USER role employee` | No employee with ADMIN_USER role | Add employee with ADMIN_USER role immediately |
| `No directors found` | Organization has no directors | Add at least one director |
| `Shareholder ownership does not sum to 100%` | Incomplete ownership structure | Review shareholder percentages |

<Warning>
  **Production Readiness**
  
  While warnings do not prevent activation, organizations should address all warnings before production use to ensure proper governance and compliance.
</Warning>

---

## Organization vs Individual Activation

Key differences between organization and individual activation:

| Aspect | Individual | Organization |
|--------|-----------|--------------|
| Request Body | `code`, `userId` | `activationReason`, `additionalInfo` |
| Verification Method | Email verification code | Admin-initiated after KYB |
| Response Warnings | No warnings | May include structural warnings |
| Required Headers | Standard auth | `X-User-ID`, `X-User-Roles` required |
| Prerequisites | KYC, Consents | KYB, Consents, Team Structure |

---

## Post-Activation Operations

After successful activation, the organization can:

1. **Check Balance**
   ```
   GET /api/v2.1/fintrans/{walletId}/balance
   ```

2. **Add Beneficiaries**
   ```
   POST /api/v2.1/fintrans/{walletId}/beneficiaries
   ```

3. **Prepare Transactions**
   ```
   POST /api/v2.1/fintrans/{walletId}/types/topup/prepare
   POST /api/v2.1/transfers/{walletId}/prepare
   ```

4. **Execute Transactions**
   ```
   POST /api/v2.1/fintrans/{walletId}/types/topup/execute
   ```

See [Financial Operations](/baas/api/reference/financial-operations) for complete transaction workflows.

---

## Troubleshooting

### Verification Not Completed

**Error:**
```json
{
  "code": 400,
  "message": "Organization verification not completed"
}
```

**Solution:** Ensure KYB verification is completed and approved before activation.

### Missing Consents

**Error:**
```json
{
  "code": 400,
  "message": "Required consents not accepted"
}
```

**Solution:** Accept all three required consents:
- Terms and Conditions: `POST /consents/terms`
- Privacy Policy: `POST /consents/privacy`
- Data Processing: `POST /consents/data-processing`

### Missing ADMIN_USER Role

**Error:**
```json
{
  "code": 400,
  "message": "Organization must have at least one employee with ADMIN_USER role"
}
```

**Solution:** Add an employee with `ADMIN_USER` role before activation.

---

## What Happens During Activation

When activation is successful, the system performs these **6 automatic actions**:

| Step | Action | Details |
|------|--------|---------|
| 1 | **Status Update** | Organization status changes from `PENDING_ACTIVATION` → `ACTIVE` |
| 2 | **Wallet Activation** | Default EUR wallet created and activated |
| 3 | **IBAN/BIC Assignment** | Unique IBAN and BIC assigned to organization account |
| 4 | **Category Limits Applied** | Transaction limits based on categorization (daily, monthly, per-txn) |
| 5 | **Features Enabled** | Category features activated (transfers, payments, topups) |
| 6 | **Audit Trail** | Complete activation log created with timestamps and user info |

---

## What Happens After Activation

Once activated, the organization can:

✅ **Financial Operations:**
- Check wallet balance
- Add beneficiaries
- Create payment consents
- Execute transfers (SEPA, SWIFT)
- Top up wallet

✅ **Account Management:**
- Add more employees/directors
- Update organization details
- Upload additional documents

---

## Wallet Information

After activation, the organization receives a **default EUR wallet**:

| Attribute | Value | Description |
|-----------|-------|-------------|
| **Currency** | EUR | Default currency |
| **Status** | ACTIVE | Ready for transactions |
| **Balance** | 0.00 | Initial balance |
| **IBAN** | DE89370400440532013000 | Unique account number |
| **BIC** | COBADEFFXXX | Bank identifier code |
| **Account Type** | BUSINESS | Business account |

---

## API Schema Reference

For the complete OpenAPI schema specification, see the [API Schema Mapping](../../../../doc/mint/API_SCHEMA_MAPPING#organization-activation) document.

---

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Standard Headers" icon="list" href="../../schemas/standard-headers">
    Complete HTTP headers reference
  </Card>
  
  <Card title="Organization Registration" icon="building" href="./registration">
    Register new organizations
  </Card>
  
  <Card title="Personnel Management" icon="users-round" href="./management">
    Manage directors, shareholders, employees
  </Card>
  
  <Card title="Verification" icon="shield-check" href="./verification">
    Complete KYB verification
  </Card>
  
  <Card title="Consents" icon="clipboard-check" href="./consents">
    Accept required consents
  </Card>
  
  <Card title="Wallet Operations" icon="wallet" href="../../financial-operations/wallet">
    Post-activation financial operations
  </Card>
</CardGroup>

---

## Changelog

| Version | Date | Changes |
|---------|------|---------|
| v1.0 | 2026-01-13 | Comprehensive organization activation documentation |


---

# Verification & Compliance

APIs for identity verification, document management, and consent collection


URL: /baas/api/reference/verification-compliance



# Verification & Compliance

Shared API surface for managing verification processes, uploading compliance documents, approving submissions, and collecting customer consents. These endpoints are used by both **Individual (B2C)** and **Organization (B2B)** onboarding flows.

<Info>
  **Base URL:** `https://sandbox.finhub.cloud/api/v2.1`
</Info>

---

## API Endpoints

### Core Verification

Three endpoints handle the full verification lifecycle — from initiation through document upload to admin approval:

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/verifications` | `POST` | Initiate a new verification (KYC for individuals, KYB for organizations) |
| `/verifications/{verificationId}/documents` | `POST` | Upload supporting documents for a verification |
| `/verifications/{verificationId}/approve` | `POST` | Admin approval after document review |

### Consent Collection

Consent endpoints are scoped per customer type. Three consent types must be accepted before activation: **terms**, **privacy**, and **data-processing**.

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/customer/individual/{customerId}/consents/{consentType}` | `POST` | Accept a consent for an individual customer |
| `/customer/organization/{organizationId}/consents/{consentType}` | `POST` | Accept a consent for an organization customer |

<Note>
  Valid values for `consentType`: `terms`, `privacy`, `data-processing`
</Note>

---

## Verification Flow

```mermaid
flowchart LR
    A[Initiate Verification] --> B[Upload Documents]
    B --> C[Pending Review]
    C --> D{Admin Decision}
    D -->|Approve| E[Approved]
    D -->|Reject| F[Rejected]
    E --> G[Collect Consents]
    G --> H[Ready for Activation]
```

### Individual (B2C) verification flow

```mermaid
flowchart TB
    V1["(1) POST /verifications (IDENTITY_VERIFICATION)"] --> V2["(2) Upload identity document"]
    V2 --> V3["(3) Upload proof-of-address document"]
    V3 --> V4["(4) Approve verification"]
    V4 --> V5["(5) Accept terms consent"]
    V5 --> V6["(6) Accept privacy consent"]
    V6 --> V7["(7) Accept data-processing consent"]
```

### Organization (B2B) verification flow

```mermaid
flowchart TB
    B1["(1) POST /verifications (BUSINESS_VERIFICATION)"] --> B2["(2) Upload certificate of incorporation"]
    B2 --> B3["(3) Upload proof of registered address"]
    B3 --> B4["(4) Approve verification"]
    B4 --> B5["(5) Accept terms consent"]
    B5 --> B6["(6) Accept privacy consent"]
    B6 --> B7["(7) Accept data-processing consent"]
```

---

## Individual KYC Flow

Step-by-step identity verification for individual (B2C) customers:

| Step | Endpoint | Payload Highlights |
|------|----------|--------------------|
| **1. Initiate** | `POST /verifications` | `type: "IDENTITY_VERIFICATION"`, `customerId` |
| **2. Upload ID** | `POST /verifications/{id}/documents` | `documentType: "PASSPORT"` or `"NATIONAL_ID"` |
| **3. Upload Address** | `POST /verifications/{id}/documents` | `documentType: "PROOF_OF_ADDRESS"` |
| **4. Approve** | `POST /verifications/{id}/approve` | Admin reviews and approves |
| **5. Terms** | `POST /customer/individual/{id}/consents/terms` | `accepted: true` |
| **6. Privacy** | `POST /customer/individual/{id}/consents/privacy` | `accepted: true` |
| **7. Data Processing** | `POST /customer/individual/{id}/consents/data-processing` | `accepted: true` |

---

## Organization KYB Flow

Step-by-step business verification for organization (B2B) customers:

| Step | Endpoint | Payload Highlights |
|------|----------|--------------------|
| **1. Initiate** | `POST /verifications` | `type: "BUSINESS_VERIFICATION"`, `customerId` |
| **2. Upload Cert** | `POST /verifications/{id}/documents` | `documentType: "CERTIFICATE_OF_INCORPORATION"` |
| **3. Upload Address** | `POST /verifications/{id}/documents` | `documentType: "PROOF_OF_REGISTERED_ADDRESS"` |
| **4. Approve** | `POST /verifications/{id}/approve` | Admin reviews and approves |
| **5. Terms** | `POST /customer/organization/{id}/consents/terms` | `accepted: true` |
| **6. Privacy** | `POST /customer/organization/{id}/consents/privacy` | `accepted: true` |
| **7. Data Processing** | `POST /customer/organization/{id}/consents/data-processing` | `accepted: true` |

---

## Verification Types

| Type | Use Case | Customer Type |
|------|----------|---------------|
| `IDENTITY_VERIFICATION` | KYC — passport or national ID verification | Individual (B2C) |
| `DOCUMENT_VERIFICATION` | Proof of address or supplementary documents | Individual (B2C) |
| `BUSINESS_VERIFICATION` | KYB — corporate entity and UBO verification | Organization (B2B) |

---

## Related Resources

<CardGroup cols={2}>
  <Card title="Individual APIs (B2C)" icon="user" href="/baas/api/reference/customer-apis/individual">
    Customer registration, sessions, and activation
  </Card>
  <Card title="Organization APIs (B2B)" icon="building" href="/baas/api/reference/customer-apis/organization">
    Business registration, personnel, and activation
  </Card>
  <Card title="Administration" icon="gear" href="/baas/api/reference/administration">
    Admin sessions, audit trails, and role management
  </Card>
  <Card title="Financial Operations" icon="banknote" href="/baas/api/reference/financial-operations">
    Wallet balances, transfers, and payment operations
  </Card>
</CardGroup>


---

# Create Verification

Initiate KYC/KYB verification requests


URL: /baas/api/reference/verification-compliance/create-verification



import { RequiredRunnerHeaders } from '../schemas/required-headers-snippet.mdx';

# Create Verification

Creates a verification request for individual or organization onboarding.

## Endpoint

`POST /api/v2.1/verifications`

## Common Defaults

- `requestedLevel`: `TENANT_VERIFIED`
- B2C `type`: `IDENTITY_VERIFICATION`
- B2B `type`: `BUSINESS_VERIFICATION`

## Required Headers

<RequiredRunnerHeaders />

## B2C Example

```json
{
  "customerId": "2dac1793-ab48-420c-b0b5-01292302e188",
  "type": "IDENTITY_VERIFICATION",
  "requestedLevel": "TENANT_VERIFIED",
  "requestedByUserId": "0d488f57-57ef-4f9a-88a6-f89121cab838",
  "requestedByTenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
  "notes": "Identity Verification"
}
```

## B2B Example

```json
{
  "customerId": "f458d016-56bb-43a6-856c-4d0456b2c38c",
  "type": "BUSINESS_VERIFICATION",
  "requestedLevel": "TENANT_VERIFIED",
  "requestedByUserId": "da9a15d2-1eb9-4804-a812-b58b03f33018",
  "requestedByTenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
  "notes": "Business Verification"
}
```

## Response Example

```json 200
{
  "code": 200,
  "data": {
    "verificationId": "825f84a5-a709-4e58-a80f-b51871d94cfb",
    "status": "PENDING",
    "verificationType": "KYC"
  },
  "message": "Success"
}
```


---

# Upload Verification Document

Upload KYC/KYB documents to an existing verification


URL: /baas/api/reference/verification-compliance/upload-verification-document



import { RequiredRunnerHeaders } from '../schemas/required-headers-snippet.mdx';

# Upload Verification Document

Uploads a base64 encoded document file to a verification case.

## Endpoint

`POST /api/v2.1/verifications/{verificationId}/documents`

## Required Headers

<RequiredRunnerHeaders />

## Request Example (B2C)

```json
{
  "verificationId": "825f84a5-a709-4e58-a80f-b51871d94cfb",
  "documentType": "PASSPORT",
  "mimeType": "application/pdf",
  "fileName": "passport.pdf",
  "fileContent": "<base64>",
  "customerId": "2dac1793-ab48-420c-b0b5-01292302e188"
}
```

## Request Example (B2B)

```json
{
  "verificationId": "ac0d408e-06b8-420c-9876-745db4ea4c98",
  "documentType": "CERTIFICATE_OF_INCORPORATION",
  "mimeType": "application/pdf",
  "fileName": "certificate_of_incorporation.pdf",
  "fileContent": "<base64>",
  "organizationId": "f458d016-56bb-43a6-856c-4d0456b2c38c"
}
```

## Success Response

```json 200
{
  "code": 200,
  "data": {
    "documentId": "80cfa65a-713e-4802-a550-090adef9bcfd",
    "documentType": "DT_PASSPORT",
    "fileName": "passport.pdf"
  },
  "message": "Success"
}
```

<Note>
  Used in B2C step runner Step 5 and B2B step runner Step 6.
</Note>


---

# Approve Verification

Approve KYC/KYB verification after review


URL: /baas/api/reference/verification-compliance/approve-verification



import { RequiredRunnerHeaders } from '../schemas/required-headers-snippet.mdx';

# Approve Verification

Marks a verification as approved once checks are complete.

## Endpoint

`POST /api/v2.1/verifications/{verificationId}/approve`

## Required Headers

<RequiredRunnerHeaders />

## B2C Example

```json
{
  "comment": "Approved",
  "customerId": "2dac1793-ab48-420c-b0b5-01292302e188",
  "verificationId": "825f84a5-a709-4e58-a80f-b51871d94cfb",
  "status": "APPROVED",
  "verificationType": "IDENTITY_VERIFICATION",
  "userId": "E2E_ADMIN"
}
```

## B2B Example

```json
{
  "comment": "Approved",
  "customerId": "f458d016-56bb-43a6-856c-4d0456b2c38c",
  "organizationId": "f458d016-56bb-43a6-856c-4d0456b2c38c",
  "verificationId": "ac0d408e-06b8-420c-9876-745db4ea4c98",
  "status": "APPROVED",
  "verificationType": "BUSINESS_VERIFICATION",
  "userId": "E2E_ADMIN"
}
```

## Success Response

```json 200
{
  "code": 200,
  "data": {
    "verificationId": "825f84a5-a709-4e58-a80f-b51871d94cfb",
    "status": "APPROVED"
  },
  "message": "Success"
}
```


---

# Verification Document Management API

Upload and manage verification documents


URL: /baas/api/reference/verification-compliance/document-management



# Verification Document Management API

APIs for uploading and managing documents associated with verification processes.

<Info>
  **Base URL:** `https://sandbox.finhub.cloud`
</Info>

## Available Operations

<CardGroup cols={2}>
  <Card title="Get Documents" icon="folder-open">
    `GET /verifications/{id}/documents`
  </Card>
  <Card title="Upload Document" icon="upload">
    `POST /verifications/{id}/documents`
  </Card>
</CardGroup>

---

## Get Verification Documents

<Note>Retrieves all documents for a specific verification process.</Note>

### Request

<ParamField path="verificationId" type="string" required>
  Verification identifier
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication
</ParamField>

<ParamField header="X-Tenant-ID" type="string" required>
  Tenant identifier
</ParamField>

<ParamField header="X-Forwarded-From" type="string" required>
  Source identifier for request origin tracking
</ParamField>

<ParamField header="User-Agent" type="string" required>
  Client application identifier — required by the global request filter
</ParamField>

<ParamField header="platform" type="string" required>
  Client platform identifier. Also accepted as `sec-ch-ua-platform`
</ParamField>

<ParamField header="deviceId" type="string" required>
  Unique device identifier for session tracking. Also accepted as `X-Device-Id` or `device-id`
</ParamField>

### Code Examples

<CodeGroup>
```bash cURL
curl -X GET "https://sandbox.finhub.cloud/api/v2.1/verifications/ver_12345/documents" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "X-Forwarded-From: e2e-test" \
  -H "User-Agent: YourApp/1.0" \
  -H "platform: web" \
  -H "deviceId: 356938035643809"
```

```javascript JavaScript
const response = await fetch(
  'https://sandbox.finhub.cloud/api/v2.1/verifications/ver_12345/documents',
  {
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
      'X-Forwarded-From': 'e2e-test',
      'User-Agent': 'YourApp/1.0',
      'platform': 'web',
      'deviceId': '356938035643809'
    }
  }
);

const { data } = await response.json();
data.documents.forEach(doc => {
  console.log(`${doc.documentType}: ${doc.status}`);
});
```

```python Python
import requests

response = requests.get(
    'https://sandbox.finhub.cloud/api/v2.1/verifications/ver_12345/documents',
    headers={
        'Authorization': f'Bearer {access_token}',
        'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
        'X-Forwarded-From': 'e2e-test',
        'User-Agent': 'YourApp/1.0',
        'platform': 'web',
        'deviceId': '356938035643809'
    }
)

data = response.json()['data']
for doc in data['documents']:
    print(f"{doc['documentType']}: {doc['status']}")
```
</CodeGroup>

<ResponseExample>
```json 200 - Success
{
  "success": true,
  "data": {
    "documents": [
      {
        "documentId": "doc_12345",
        "documentType": "GOVERNMENT_ID",
        "status": "VERIFIED",
        "uploadedAt": "2024-01-15T10:30:00Z"
      },
      {
        "documentId": "doc_67890",
        "documentType": "PROOF_OF_ADDRESS",
        "status": "PENDING_REVIEW",
        "uploadedAt": "2024-01-15T10:35:00Z"
      }
    ]
  }
}
```
</ResponseExample>

---

## Upload Verification Document

<Note>Uploads a document for a specific verification process.</Note>

### Request

<ParamField path="verificationId" type="string" required>
  Verification identifier
</ParamField>

<ParamField query="documentType" type="string" required>
  Type of document: `GOVERNMENT_ID`, `PROOF_OF_ADDRESS`, `SELFIE`, etc.
</ParamField>

<ParamField query="documentId" type="string">
  Optional document ID (for re-uploads)
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication
</ParamField>

<ParamField header="X-Tenant-ID" type="string" required>
  Tenant identifier
</ParamField>

<ParamField header="X-User-Id" type="string">
  Uploading user ID
</ParamField>

<ParamField body="file" type="file" required>
  Document file (multipart/form-data)
</ParamField>

<ParamField body="category" type="string">
  Document category
</ParamField>

### Code Examples

<CodeGroup>
```bash cURL
curl -X POST "https://sandbox.finhub.cloud/api/v2.1/verifications/ver_12345/documents?documentType=GOVERNMENT_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "X-Forwarded-From: e2e-test" \
  -H "User-Agent: YourApp/1.0" \
  -H "platform: web" \
  -H "deviceId: 356938035643809" \
  -F "file=@/path/to/passport.pdf"
```

```javascript JavaScript
const formData = new FormData();
formData.append('file', documentFile);

const response = await fetch(
  'https://sandbox.finhub.cloud/api/v2.1/verifications/ver_12345/documents?documentType=GOVERNMENT_ID',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
      'X-Forwarded-From': 'e2e-test',
      'User-Agent': 'YourApp/1.0',
      'platform': 'web',
      'deviceId': '356938035643809'
    },
    body: formData
  }
);

const { data } = await response.json();
console.log('Document ID:', data.documentId);
console.log('Status:', data.status);
```

```python Python
import requests

with open('/path/to/passport.pdf', 'rb') as f:
    response = requests.post(
        'https://sandbox.finhub.cloud/api/v2.1/verifications/ver_12345/documents',
        params={'documentType': 'GOVERNMENT_ID'},
        headers={
            'Authorization': f'Bearer {access_token}',
            'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
                'X-Forwarded-From': 'e2e-test',
            'User-Agent': 'YourApp/1.0',
            'platform': 'web',
            'deviceId': '356938035643809'
        },
        files={'file': f}
    )

data = response.json()['data']
print(f"Document ID: {data['documentId']}")
```
</CodeGroup>

<ResponseExample>
```json 201 - Success
{
  "success": true,
  "data": {
    "documentId": "doc_11111",
    "verificationId": "ver_12345",
    "documentType": "GOVERNMENT_ID",
    "status": "UPLOADED",
    "uploadedAt": "2024-01-15T10:30:00Z"
  }
}
```

```json 400 - Invalid File
{
  "success": false,
  "error": {
    "code": "INVALID_FILE",
    "message": "File type not supported. Allowed: PDF, JPG, PNG"
  }
}
```
</ResponseExample>

---

## Document Types

| Type | Description |
|------|-------------|
| `GOVERNMENT_ID` | Passport, national ID, driver's license |
| `PROOF_OF_ADDRESS` | Utility bill, bank statement (< 3 months) |
| `SOURCE_OF_FUNDS` | Income proof, tax returns |
| `SELFIE` | Customer selfie for liveness check |
| `CERTIFICATE_OF_INCORPORATION` | Company registration |
| `BENEFICIAL_OWNER_DECLARATION` | UBO declaration |

## Document Statuses

| Status | Description |
|--------|-------------|
| `UPLOADED` | Document uploaded |
| `PENDING_REVIEW` | Awaiting review |
| `VERIFIED` | Document verified |
| `REJECTED` | Document rejected |

## Response Codes

| Code | Description |
|------|-------------|
| `200` | Documents retrieved successfully |
| `201` | Document uploaded successfully |
| `400` | Invalid request data |
| `404` | Verification not found |
| `500` | Internal server error |


---

# Verification Management API

KYC/KYB verification workflows, document uploads, and approvals


URL: /baas/api/reference/verification-compliance/verification-management



# Verification Management API

Complete verification workflows for KYC (Know Your Customer) and KYB (Know Your Business) compliance.

<Info>
  **Base URL:** `https://sandbox.finhub.cloud/api/v2.1/verifications`
  
  **Supported Verification Types:**
  - Individual KYC (4 types available)
  - Organization KYB
</Info>

---

## Verification Workflow

<Steps>
  <Step title="Create Verification">
    Initiate verification request with type and level
  </Step>
  <Step title="Upload Documents">
    Submit required verification documents
  </Step>
  <Step title="Review Process">
    Admin reviews submissions and documents
  </Step>
  <Step title="Approve/Reject">
    Admin makes final decision
  </Step>
  <Step title="Update Customer Status">
    System updates customer verification level
  </Step>
</Steps>

---

## Create Verification Request

Initiate a new verification process for a customer.

### Endpoint

```
POST /api/v2.1/verifications
```

### Headers

<ParamField header="X-Tenant-ID" type="string" required>
  Tenant identifier
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`
</ParamField>

### Request Body

<ParamField body="customerId" type="string">
  Customer UUID identifier to verify (included when verifying a specific customer)
  
  Example: `5887c98c-b5b1-4234-b819-a4987f54aa77`
</ParamField>

<ParamField body="requestedByTenantId" type="string" required>
  Tenant ID requesting the verification
  
  Example: `d1e2f3a4-b5c6-47d8-9e0f-1a2b3c4d5e6f`
</ParamField>

<ParamField body="type" type="string" required>
  Verification type
  
  **Valid Values:**
  - `IDENTITY_VERIFICATION` - Basic identity check
  - `DOCUMENT_VERIFICATION` - Document authenticity verification
  - `ENHANCED_DUE_DILIGENCE` - Enhanced KYC/KYB checks
  - `SANCTIONS_CHECK` - Sanctions and PEP screening
  - `CUSTOMER_DUE_DILIGENCE` - Standard CDD process
  - `BUSINESS_VERIFICATION` - Organization/business verification
</ParamField>

<ParamField body="requestedLevel" type="string" required>
  Target verification level
  
  **Valid Values:**
  - `TENANT_VERIFIED` - Tenant-level verification
  - `FINHUB_VERIFIED` - Platform-level verification
</ParamField>

<ParamField body="requestedByUserId" type="string" required>
  User ID initiating the verification
  
  Example: `admin-user`
</ParamField>

<ParamField body="additionalData" type="object">
  Optional metadata for the verification
  
  <Expandable title="additionalData properties">
    <ParamField body="description" type="string">
      Description of the verification request
    </ParamField>
    
    <ParamField body="priority" type="string">
      Priority level: `NORMAL`, `HIGH`, or `URGENT`
    </ParamField>
  </Expandable>
</ParamField>

### Headers

<ParamField header="X-Tenant-ID" type="string" required>
  Tenant identifier
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`
</ParamField>

<ParamField header="X-Forwarded-From" type="string" required>
  Source identifier for request origin tracking
</ParamField>

<ParamField header="User-Agent" type="string" required>
  Client application identifier — required by the global request filter
</ParamField>

<ParamField header="platform" type="string" required>
  Client platform identifier (e.g., `web`). Also accepted as `sec-ch-ua-platform`
</ParamField>

<ParamField header="deviceId" type="string" required>
  Unique device identifier for session tracking. Also accepted as `X-Device-Id` or `device-id`
</ParamField>

<ParamField header="X-User-ID" type="string">
  User ID initiating the verification (used in B2B flows)
</ParamField>

<ParamField header="X-User-Roles" type="string">
  Comma-separated list of user roles (used in B2B flows)
</ParamField>

### Code Examples

<CodeGroup>
```bash cURL - Identity Verification
curl -X POST "https://sandbox.finhub.cloud/api/v2.1/verifications" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Forwarded-From: e2e-test" \
  -H "User-Agent: YourApp/1.0" \
  -H "platform: web" \
  -H "deviceId: 356938035643809" \
  -d '{
    "customerId": "5887c98c-b5b1-4234-b819-a4987f54aa77",
    "requestedByTenantId": "d1e2f3a4-b5c6-47d8-9e0f-1a2b3c4d5e6f",
    "type": "IDENTITY_VERIFICATION",
    "requestedLevel": "TENANT_VERIFIED",
    "requestedByUserId": "admin-user",
    "additionalData": {
      "description": "New customer onboarding",
      "priority": "NORMAL"
    }
  }'
```

```bash cURL - Business Verification
curl -X POST "https://sandbox.finhub.cloud/api/v2.1/verifications" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Forwarded-From: e2e-test" \
  -H "User-Agent: YourApp/1.0" \
  -H "platform: web" \
  -H "deviceId: 356938035643809" \
  -d '{
    "customerId": "2f6ddd86-9ef1-45b6-a16d-058b3ccf29e4",
    "requestedByTenantId": "d1e2f3a4-b5c6-47d8-9e0f-1a2b3c4d5e6f",
    "type": "BUSINESS_VERIFICATION",
    "requestedLevel": "TENANT_VERIFIED",
    "requestedByUserId": "admin-user",
    "additionalData": {
      "description": "KYB compliance check",
      "priority": "HIGH"
    }
  }'
```

```javascript JavaScript
const createVerification = async (customerId, type) => {
  const response = await fetch(
    'https://sandbox.finhub.cloud/api/v2.1/verifications',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
        'Authorization': `Bearer ${token}`,
        'X-Forwarded-From': 'e2e-test',
        'User-Agent': 'YourApp/1.0',
        'platform': 'web',
        'deviceId': '356938035643809'
      },
      body: JSON.stringify({
        customerId,
        requestedByTenantId: 'd1e2f3a4-b5c6-47d8-9e0f-1a2b3c4d5e6f',
        type,
        requestedLevel: 'TENANT_VERIFIED',
        requestedByUserId: 'admin-user',
        additionalData: {
          description: `${type} check`,
          priority: 'NORMAL'
        }
      })
    }
  );

  return response.json();
};
```

```python Python
def create_verification(customer_id, verification_type):
    url = 'https://sandbox.finhub.cloud/api/v2.1/verifications'
    
    payload = {
        'customerId': customer_id,
        'requestedByTenantId': 'd1e2f3a4-b5c6-47d8-9e0f-1a2b3c4d5e6f',
        'type': verification_type,
        'requestedLevel': 'TENANT_VERIFIED',
        'requestedByUserId': 'admin-user',
        'additionalData': {
            'description': f'{verification_type} compliance check',
            'priority': 'NORMAL'
        }
    }
    
    response = requests.post(
        url,
        headers={
            'Content-Type': 'application/json',
            'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
            'Authorization': f'Bearer {token}',
                'X-Forwarded-From': 'e2e-test',
            'User-Agent': 'YourApp/1.0',
            'platform': 'web',
            'deviceId': '356938035643809'
        },
        json=payload
    )
    
    return response.json()
```
</CodeGroup>

### Response

<ResponseExample>
```json 201 - Created
{
  "success": true,
  "code": 200,
  "timestamp": "2026-01-12T19:22:00.469602400Z",
  "message": "Verification process started",
  "data": {
    "id": "42cf474d-0914-47f1-895f-54147443d203",
    "customerId": "5887c98c-b5b1-4234-b819-a4987f54aa77",
    "type": "IDENTITY_VERIFICATION",
    "status": "IN_PROGRESS",
    "performedBy": "TENANT",
    "performedById": "d1e2f3a4-b5c6-47d8-9e0f-1a2b3c4d5e6f",
    "verificationLevel": "TENANT_VERIFIED",
    "appliesToSubtenants": false,
    "requiredDocuments": [
      "GOVERNMENT_ID"
    ],
    "startedAt": "2026-01-12T19:22:00.436424200Z",
    "initiatedBy": "admin-user",
    "additionalData": {
      "description": "New customer onboarding",
      "priority": "NORMAL"
    },
    "verified": false
  }
}
```
</ResponseExample>

---

## Upload Verification Document

Upload a document for an active verification process.

### Endpoint

```
POST /api/v2.1/verifications/{verificationId}/documents
```

### Path Parameters

<ParamField path="verificationId" type="string" required>
  Verification UUID from the create verification response
  
  Example: `42cf474d-0914-47f1-895f-54147443d203`
</ParamField>

### Request Body

<ParamField body="documentType" type="string" required>
  Type of document being uploaded
  
  **Valid Document Types:**
  - `PASSPORT` - Passport document
  - `NATIONAL_ID` - National ID card
  - `DRIVERS_LICENSE` - Driver's license
  - `PROOF_OF_ADDRESS` - Address verification
  - `BANK_STATEMENT` - Bank statement
  - `SOURCE_OF_FUNDS` - Source of funds declaration
  - `BENEFICIAL_OWNERSHIP` - Beneficial ownership declaration
  - `PEP_DECLARATION` - PEP status declaration
  - `PROOF_OF_FUNDS` - Proof of funds
  - `INVOICE` - Invoice or business document
  - `CERTIFICATE_OF_INCORPORATION` - Company registration
  - `SHAREHOLDER_REGISTER` - Shareholder registry
  - `DIRECTOR_ID` - Director identification
</ParamField>

<ParamField body="fileName" type="string" required>
  Original filename with extension
  
  Example: `passport.pdf`
</ParamField>

<ParamField body="fileContent" type="string" required>
  Base64-encoded file content
  
  **Supported Formats:** PDF, JPEG, PNG
  **Max Size:** 10MB
</ParamField>

<ParamField body="mimeType" type="string" required>
  MIME type of the file
  
  Examples: `application/pdf`, `image/jpeg`, `image/png`
</ParamField>

<ParamField body="description" type="string">
  Optional description or notes about the document
</ParamField>

<ParamField body="customerId" type="string">
  Customer ID (for payment verification documents)
</ParamField>

<ParamField body="accountId" type="string">
  Account ID (for payment verification documents)
</ParamField>

<ParamField body="transactionAmount" type="number">
  Transaction amount (for payment verification)
</ParamField>

<ParamField body="currency" type="string">
  Currency code (for payment verification)
</ParamField>

<ParamField body="purpose" type="string">
  Purpose of the document upload
</ParamField>

### Code Example

<CodeGroup>
```bash cURL
curl -X POST "https://sandbox.finhub.cloud/api/v2.1/verifications/42cf474d-0914-47f1-895f-54147443d203/documents" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Forwarded-From: e2e-test" \
  -H "User-Agent: YourApp/1.0" \
  -H "platform: web" \
  -H "deviceId: 356938035643809" \
  -d '{
    "documentType": "PASSPORT",
    "fileName": "passport.pdf",
    "fileContent": "JVBERi0xLjQKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwo+PgplbmRvYmoKeHJlZgowIDAKdHJhaWxlcgo8PAovUm9vdCAxIDAgUgo+PgolJUVPRgo=",
    "mimeType": "application/pdf",
    "description": "Customer passport for identity verification"
  }'
```

```javascript JavaScript
const uploadDocument = async (verificationId, file) => {
  // Convert file to base64
  const base64Content = await fileToBase64(file);
  
  const response = await fetch(
    `https://sandbox.finhub.cloud/api/v2.1/verifications/${verificationId}/documents`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
        'Authorization': `Bearer ${token}`,
        'X-Forwarded-From': 'e2e-test',
        'User-Agent': 'YourApp/1.0',
        'platform': 'web',
        'deviceId': '356938035643809'
      },
      body: JSON.stringify({
        documentType: 'PASSPORT',
        fileName: file.name,
        fileContent: base64Content,
        mimeType: file.type,
        description: 'Customer passport for identity verification'
      })
    }
  );

  return response.json();
};

// Helper function
const fileToBase64 = (file) => {
  return new Promise((resolve, reject) => {
    const reader = new FileReader();
    reader.readAsDataURL(file);
    reader.onload = () => resolve(reader.result.split(',')[1]);
    reader.onerror = error => reject(error);
  });
};
```
</CodeGroup>

### Response

<ResponseExample>
```json 201 - Created
{
  "code": 200,
  "message": "Verification document uploaded successfully",
  "data": "Document uploaded for verification 42cf474d-0914-47f1-895f-54147443d203: {\"id\":\"d7379b5e-f983-4a27-b074-9a5a58cdc9da\",\"tenantId\":\"d1e2f3a4-b5c6-47d8-9e0f-1a2b3c4d5e6f\",\"customerId\":\"5887c98c-b5b1-4234-b819-a4987f54aa77\",\"fileName\":\"628dd82a-a698-4d8c-bcb2-a97e78d33397_passport.pdf\",\"fileType\":\"PASSPORT\",\"status\":\"UPLOADED\",\"contentType\":\"application/pdf\",\"contentUrl\":\".\\\\data\\\\documents\\\\d1e2f3a4-b5c6-47d8-9e0f-1a2b3c4d5e6f\\\\2026\\\\01\\\\12\\\\5887c98c-b5b1-4234-b819-a4987f54aa77\\\\628dd82a-a698-4d8c-bcb2-a97e78d33397_passport.pdf\",\"uploadDate\":1768245720542,\"uploadedBy\":\"system\",\"description\":\"Customer passport for identity verification\",\"verified\":false}"
}
```
</ResponseExample>

---

## Approve Verification

Approve a verification request after review.

### Endpoint

```
POST /api/v2.1/verifications/{verificationId}/approve
```

### Path Parameters

<ParamField path="verificationId" type="string" required>
  Verification UUID to approve
</ParamField>

### Request Body

<ParamField body="notes" type="string">
  Admin notes about the approval decision (used in implementation)
</ParamField>

<ParamField body="approvedBy" type="string" required>
  User ID or name of the approver
  
  Example: `E2E_TEST_ADMIN` or admin user ID
</ParamField>

<ParamField body="adminNotes" type="string">
  Alternative field for admin notes (legacy support)
</ParamField>

<ParamField body="approvalReason" type="string">
  Reason for approval
</ParamField>

### Code Example

<CodeGroup>
```bash cURL
curl -X POST "https://sandbox.finhub.cloud/api/v2.1/verifications/42cf474d-0914-47f1-895f-54147443d203/approve" \
  -H "Accept: application/json, text/plain, */*" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Forwarded-From: e2e-test" \
  -H "platform: web" \
  -H "deviceId: 356938035643809" \
  -d '{
    "adminNotes": "All documents verified and authentic",
    "approvedBy": "admin_user_123",
    "approvalReason": "All verification criteria met"
  }'
```

```javascript JavaScript
const approveVerification = async (verificationId) => {
  const response = await fetch(
    `https://sandbox.finhub.cloud/api/v2.1/verifications/${verificationId}/approve`,
    {
      method: 'POST',
      headers: {
        'Accept': 'application/json, text/plain, */*',
        'Content-Type': 'application/json',
        'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
        'Authorization': `Bearer ${token}`,
        'X-Forwarded-From': 'e2e-test',
        'platform': 'web',
        'deviceId': '356938035643809'
      },
      body: JSON.stringify({
        adminNotes: 'All documents verified and authentic',
        approvedBy: 'admin_user_123',
        approvalReason: 'All verification criteria met'
      })
    }
  );

  return response.json();
};
```
</CodeGroup>

### Response

<ResponseExample>
```json 200 - Success
{
  "code": 200,
  "message": "Verification approved successfully",
  "data": {
    "level": "TENANT_VERIFIED",
    "approvedBy": "admin-user",
    "approvedAt": "2026-01-12T19:22:00.658560500Z",
    "verificationId": "42cf474d-0914-47f1-895f-54147443d203",
    "status": "APPROVED"
  }
}
```
</ResponseExample>

---

## Get Verification Status

Retrieve the current status of a verification request.

### Endpoint

```
GET /api/v2.1/verifications/{verificationId}
```

### Path Parameters

<ParamField path="verificationId" type="string" required>
  Verification UUID
</ParamField>

### Response

<ResponseExample>
```json 200 - Success
{
  "code": 200,
  "message": "Verification status retrieved successfully",
  "data": {
    "submittedDocuments": 0,
    "completedAt": "2026-01-12T19:22:04.780839500Z",
    "level": "FINHUB_VERIFIED",
    "startedAt": "2026-01-12T19:22:02.894983800Z",
    "type": "SANCTIONS_CHECK",
    "verificationId": "90fb384c-6404-453d-9001-d15c4e0966e5",
    "status": "APPROVED"
  }
}
```
</ResponseExample>

---

## Verification Types Reference

| Type | Purpose | Required Documents | Typical Use Case |
|------|---------|-------------------|------------------|
| `IDENTITY_VERIFICATION` | Basic identity check | Government ID | Individual onboarding |
| `DOCUMENT_VERIFICATION` | Document authenticity | Proof of address, ID | Address verification |
| `ENHANCED_DUE_DILIGENCE` | Enhanced KYC | Source of funds, beneficial ownership, PEP | High-risk customers |
| `SANCTIONS_CHECK` | PEP & sanctions screening | PEP declaration, proof of address | Compliance requirements |
| `CUSTOMER_DUE_DILIGENCE` | Standard CDD | Basic identification | Standard KYC |
| `BUSINESS_VERIFICATION` | KYB for organizations | Incorporation docs, shareholder register | Organization onboarding |

---

## Document Type Requirements

### Individual Customers

**IDENTITY_VERIFICATION:**
- `PASSPORT` or `NATIONAL_ID` or `DRIVERS_LICENSE`

**ENHANCED_DUE_DILIGENCE:**
- `SOURCE_OF_FUNDS`
- `BENEFICIAL_OWNERSHIP` (if applicable)
- `PEP_DECLARATION`
- `PROOF_OF_ADDRESS`

**SANCTIONS_CHECK:**
- `PROOF_OF_ADDRESS`
- `SOURCE_OF_FUNDS`
- `BENEFICIAL_OWNERSHIP`
- `PEP_DECLARATION`

### Organization Customers

**BUSINESS_VERIFICATION:**
- `CERTIFICATE_OF_INCORPORATION`
- `PROOF_OF_ADDRESS`
- `DIRECTOR_ID`
- `SHAREHOLDER_REGISTER`

---

## Verification Levels

| Level | Description | Verification By |
|-------|-------------|-----------------|
| `TENANT_VERIFIED` | Verified by tenant | Tenant admin |
| `FINHUB_VERIFIED` | Verified by platform | FinHub compliance team |

---

## Common Workflows

### Individual KYC Workflow

```
1. Create IDENTITY_VERIFICATION
   ↓
2. Upload PASSPORT document
   ↓
3. Admin reviews and approves
   ↓
4. Create DOCUMENT_VERIFICATION
   ↓
5. Upload PROOF_OF_ADDRESS
   ↓
6. Admin approves
   ↓
7. (Optional) Create ENHANCED_DUE_DILIGENCE for high-risk
   ↓
8. Customer status updated to VERIFIED
```

### Organization KYB Workflow

```
1. Create BUSINESS_VERIFICATION
   ↓
2. Upload required documents:
   - CERTIFICATE_OF_INCORPORATION
   - DIRECTOR_ID
   - SHAREHOLDER_REGISTER
   - PROOF_OF_ADDRESS
   ↓
3. Admin reviews all documents
   ↓
4. Admin approves verification
   ↓
5. Organization status updated to VERIFIED
```

---

## Best Practices

<Note>
  **Verification Checklist:**
  
  1. ✅ Create verification request first
  2. ✅ Upload all required documents
  3. ✅ Wait for admin review (don't auto-approve)
  4. ✅ Check verification status before allowing operations
  5. ✅ Re-verify periodically (annual review recommended)
</Note>

### Document Quality Guidelines

- **Resolution:** Minimum 300 DPI for scanned documents
- **Format:** PDF preferred, JPEG/PNG acceptable
- **Size:** Maximum 10MB per file
- **Clarity:** All text must be clearly readable
- **Completeness:** Full document visible, no cropping

---

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Customer Activation" icon="check-circle" href="../customer-apis/individual/activation">
    Activate customer after verification
  </Card>
  
  <Card title="Organization Management" icon="users-round" href="../customer-apis/organization/management">
    Add directors/shareholders for KYB
  </Card>
  
  <Card title="Consent Management" icon="file-text" href="../customer-apis/individual/activation">
    Required consents for verified customers
  </Card>
  
  <Card title="Common Types" icon="book" href="../schemas/common-types">
    Standard data structures
  </Card>
</CardGroup>

---

## Changelog

| Version | Date | Changes |
|---------|------|---------|
| v2.1 | 2026-01-13 | Initial release |


---

# Consent Verification API

Verify consents via email, magic links, and tokens


URL: /baas/api/reference/verification-compliance/consent-verification



# Consent Verification API

APIs for verifying customer consents through various methods including email resend, magic links, and token verification.

<Info>
  **Base URL:** `https://sandbox.finhub.cloud/api/v2.1/consent/verification`
</Info>

## Available Operations

<CardGroup cols={2}>
  <Card title="Resend Verification" icon="paper-plane">
    `POST /resend`
  </Card>
  <Card title="Send Magic Link" icon="wand-magic-sparkles">
    `POST /send-magic-link`
  </Card>
  <Card title="Verify Token" icon="check-circle">
    `GET /verify/{token}`
  </Card>
  <Card title="Accept Consent" icon="file-text">
    `POST /consents/{type}`
  </Card>
</CardGroup>

---

## Accept Consent

<Note>Directly accept a consent on behalf of a customer (used in onboarding flows).</Note>

### Endpoints

- `POST /api/v2.1/customer/individual/{customerId}/consents/terms`
- `POST /api/v2.1/customer/individual/{customerId}/consents/privacy`  
- `POST /api/v2.1/customer/individual/{customerId}/consents/data-processing`
- `POST /api/v2.1/customer/organization/{organizationId}/consents/terms`
- `POST /api/v2.1/customer/organization/{organizationId}/consents/privacy`
- `POST /api/v2.1/customer/organization/{organizationId}/consents/data-processing`

### Request Body

<ParamField body="accepted" type="boolean" required>
  Whether the consent is accepted
  
  Example: `true`
</ParamField>

<ParamField body="version" type="string" required>
  Consent version
  
  Example: `"1.0"`
</ParamField>

### Headers

<ParamField header="X-Tenant-ID" type="string" required>
  Tenant identifier
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`
</ParamField>

<ParamField header="X-Forwarded-From" type="string" required>
  Source identifier for request origin tracking
</ParamField>

<ParamField header="User-Agent" type="string" required>
  Client application identifier — required by the global request filter
</ParamField>

<ParamField header="platform" type="string" required>
  Client platform identifier. Also accepted as `sec-ch-ua-platform`
</ParamField>

<ParamField header="deviceId" type="string" required>
  Unique device identifier for session tracking. Also accepted as `X-Device-Id` or `device-id`
</ParamField>

### Code Example

```bash cURL - Terms Consent
curl -X POST "https://sandbox.finhub.cloud/api/v2.1/customer/individual/de645b7b-219a-4fdf-bd59-a7bf454a0586/consents/terms" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "X-Forwarded-From: e2e-test" \
  -H "User-Agent: YourApp/1.0" \
  -H "platform: web" \
  -H "deviceId: e2e-test-device" \
  -d '{
    "accepted": true,
    "version": "1.0"
  }'
```

### Response

<ResponseExample>
```json 200 - Success
{
  "code": 200,
  "data": {
    "verificationId": "f778e9d2-9097-4328-9b76-8f225d48c9aa",
    "status": "PENDING",
    "verificationType": "CONSENT",
    "updatedAt": "2026-03-10T07:10:04.068Z",
    "updatedBy": "7e14ae4c-1e6c-4792-83f0-2263f2d13bce"
  },
  "message": "Success"
}
```
</ResponseExample>

---

---

## Resend Verification

<Note>Resends the consent verification email to the customer.</Note>

### Request

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication
</ParamField>

<ParamField header="X-Tenant-ID" type="string" required>
  Tenant identifier
</ParamField>

<ParamField body="customerId" type="string" required>
  Customer identifier
</ParamField>

<ParamField body="consentId" type="string" required>
  Consent identifier to verify
</ParamField>

<ParamField body="channel" type="string">
  Delivery channel: `EMAIL`, `SMS` (default: `EMAIL`)
</ParamField>

### Code Examples

<CodeGroup>
```bash cURL
curl -X POST "https://sandbox.finhub.cloud/api/v2.1/consent/verification/resend" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "X-Forwarded-From: e2e-test" \
  -H "User-Agent: YourApp/1.0" \
  -H "platform: web" \
  -H "deviceId: 356938035643809" \
  -d '{
    "customerId": "cust_12345",
    "consentId": "cons_67890",
    "channel": "EMAIL"
  }'
```

```javascript JavaScript
const response = await fetch(
  'https://sandbox.finhub.cloud/api/v2.1/consent/verification/resend',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${accessToken}`,
      'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
      'X-Forwarded-From': 'e2e-test',
      'User-Agent': 'YourApp/1.0',
      'platform': 'web',
      'deviceId': '356938035643809'
    },
    body: JSON.stringify({
      customerId: 'cust_12345',
      consentId: 'cons_67890',
      channel: 'EMAIL'
    })
  }
);

const { data } = await response.json();
console.log('Verification sent:', data.sentAt);
```

```python Python
import requests

response = requests.post(
    'https://sandbox.finhub.cloud/api/v2.1/consent/verification/resend',
    headers={
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {access_token}',
        'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
        'X-Forwarded-From': 'e2e-test',
        'User-Agent': 'YourApp/1.0',
        'platform': 'web',
        'deviceId': '356938035643809'
    },
    json={
        'customerId': 'cust_12345',
        'consentId': 'cons_67890',
        'channel': 'EMAIL'
    }
)

data = response.json()['data']
print(f"Verification sent at: {data['sentAt']}")
```
</CodeGroup>

<ResponseExample>
```json 200 - Success
{
  "success": true,
  "data": {
    "customerId": "cust_12345",
    "consentId": "cons_67890",
    "channel": "EMAIL",
    "sentAt": "2024-01-15T10:30:00Z",
    "expiresAt": "2024-01-15T11:30:00Z"
  }
}
```

```json 429 - Too Many Requests
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many verification requests. Please wait before trying again.",
    "retryAfter": 300
  }
}
```
</ResponseExample>

---

## Send Magic Link

<Note>Sends a magic link for one-click consent verification.</Note>

### Request

<ParamField body="customerId" type="string" required>
  Customer identifier
</ParamField>

<ParamField body="consentId" type="string" required>
  Consent identifier to verify
</ParamField>

<ParamField body="redirectUrl" type="string">
  URL to redirect after verification (must be whitelisted)
</ParamField>

<ParamField body="expiresInMinutes" type="integer">
  Link expiration time in minutes (default: 60, max: 1440)
</ParamField>

### Code Examples

<CodeGroup>
```bash cURL
curl -X POST "https://sandbox.finhub.cloud/api/v2.1/consent/verification/send-magic-link" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "X-Forwarded-From: e2e-test" \
  -H "User-Agent: YourApp/1.0" \
  -H "platform: web" \
  -H "deviceId: 356938035643809" \
  -d '{
    "customerId": "cust_12345",
    "consentId": "cons_67890",
    "redirectUrl": "https://your-app.com/consent-confirmed",
    "expiresInMinutes": 60
  }'
```

```javascript JavaScript
const response = await fetch(
  'https://sandbox.finhub.cloud/api/v2.1/consent/verification/send-magic-link',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${accessToken}`,
      'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
      'X-Forwarded-From': 'e2e-test',
      'User-Agent': 'YourApp/1.0',
      'platform': 'web',
      'deviceId': '356938035643809'
    },
    body: JSON.stringify({
      customerId: 'cust_12345',
      consentId: 'cons_67890',
      redirectUrl: 'https://your-app.com/consent-confirmed',
      expiresInMinutes: 60
    })
  }
);

const { data } = await response.json();
console.log('Magic link sent, expires:', data.expiresAt);
```

```python Python
import requests

response = requests.post(
    'https://sandbox.finhub.cloud/api/v2.1/consent/verification/send-magic-link',
    headers={
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {access_token}',
        'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
        'X-Forwarded-From': 'e2e-test',
        'User-Agent': 'YourApp/1.0',
        'platform': 'web',
        'deviceId': '356938035643809'
    },
    json={
        'customerId': 'cust_12345',
        'consentId': 'cons_67890',
        'redirectUrl': 'https://your-app.com/consent-confirmed',
        'expiresInMinutes': 60
    }
)

data = response.json()['data']
print(f"Magic link expires: {data['expiresAt']}")
```
</CodeGroup>

<ResponseExample>
```json 200 - Success
{
  "success": true,
  "data": {
    "customerId": "cust_12345",
    "consentId": "cons_67890",
    "sentTo": "j***@example.com",
    "sentAt": "2024-01-15T10:30:00Z",
    "expiresAt": "2024-01-15T11:30:00Z"
  }
}
```

```json 400 - Invalid Redirect URL
{
  "success": false,
  "error": {
    "code": "INVALID_REDIRECT_URL",
    "message": "Redirect URL is not whitelisted for this tenant"
  }
}
```
</ResponseExample>

---

## Verify Token

<Note>Verifies a consent using the token from the verification email or magic link.</Note>

### Request

<ParamField path="token" type="string" required>
  Verification token from email or magic link
</ParamField>

<ParamField header="X-Tenant-ID" type="string" required>
  Tenant identifier
</ParamField>

### Code Examples

<CodeGroup>
```bash cURL
curl -X GET "https://sandbox.finhub.cloud/api/v2.1/consent/verification/verify/eyJhbGciOiJIUzI1NiIs..." \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "X-Forwarded-From: e2e-test" \
  -H "User-Agent: YourApp/1.0" \
  -H "platform: web" \
  -H "deviceId: 356938035643809"
```

```javascript JavaScript
const token = 'eyJhbGciOiJIUzI1NiIs...';

const response = await fetch(
  `https://sandbox.finhub.cloud/api/v2.1/consent/verification/verify/${token}`,
  {
    headers: {
      'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
      'X-Forwarded-From': 'e2e-test',
      'User-Agent': 'YourApp/1.0',
      'platform': 'web',
      'deviceId': '356938035643809'
    }
  }
);

const { data } = await response.json();
if (data.verified) {
  console.log('Consent verified successfully!');
  console.log('Redirect to:', data.redirectUrl);
}
```

```python Python
import requests

token = 'eyJhbGciOiJIUzI1NiIs...'

response = requests.get(
    f'https://sandbox.finhub.cloud/api/v2.1/consent/verification/verify/{token}',
    headers={
        'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
        'X-Forwarded-From': 'e2e-test',
        'User-Agent': 'YourApp/1.0',
        'platform': 'web',
        'deviceId': '356938035643809'
    }
)

data = response.json()['data']
if data['verified']:
    print('Consent verified successfully!')
    print(f"Redirect to: {data['redirectUrl']}")
```
</CodeGroup>

<ResponseExample>
```json 200 - Success
{
  "success": true,
  "data": {
    "verified": true,
    "customerId": "cust_12345",
    "consentId": "cons_67890",
    "consentType": "TERMS",
    "verifiedAt": "2024-01-15T10:35:00Z",
    "redirectUrl": "https://your-app.com/consent-confirmed"
  }
}
```

```json 400 - Invalid Token
{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "Verification token is invalid or malformed"
  }
}
```

```json 410 - Token Expired
{
  "success": false,
  "error": {
    "code": "TOKEN_EXPIRED",
    "message": "Verification token has expired"
  }
}
```
</ResponseExample>

---

## Verification Flow

<Steps>
  <Step title="Request Verification">
    Call `/resend` or `/send-magic-link` to send verification to customer
  </Step>
  <Step title="Customer Clicks Link">
    Customer receives email and clicks the verification link
  </Step>
  <Step title="Token Validation">
    System validates the token via `/verify/{token}`
  </Step>
  <Step title="Consent Confirmed">
    Consent status updated to `ACCEPTED` and customer redirected
  </Step>
</Steps>

## Delivery Channels

| Channel | Description |
|---------|-------------|
| `EMAIL` | Verification sent via email |
| `SMS` | Verification sent via SMS (if enabled) |

## Response Codes

| Code | Description |
|------|-------------|
| `200` | Operation successful |
| `400` | Invalid request data or token |
| `401` | Not Authorized |
| `403` | Not Allowed |
| `404` | Consent or customer not found |
| `410` | Token expired |
| `429` | Rate limit exceeded |
| `500` | Internal server error |


---

# Accept Individual Consent

Accept terms/privacy/data-processing consent for a B2C customer


URL: /baas/api/reference/verification-compliance/consents-individual



import { RequiredRunnerHeaders } from '../schemas/required-headers-snippet.mdx';

# Accept Individual Consent

Accepts mandatory consent types before activation.

## Endpoint

`POST /api/v2.1/customer/individual/{customerId}/consents/{consentType}`

## Required Headers

<RequiredRunnerHeaders />

## Path Parameters

<ParamField path="customerId" type="string" required>Customer UUID</ParamField>
<ParamField path="consentType" type="string" required>`terms`, `privacy`, `data-processing`</ParamField>

## Request Body

```json
{
  "accepted": true,
  "version": "1.0"
}
```

## Success Response

```json 200
{
  "code": 200,
  "data": {
    "status": "PENDING"
  },
  "message": "Success"
}
```


---

# Accept Organization Consent

Accept terms/privacy/data-processing consent for a B2B organization


URL: /baas/api/reference/verification-compliance/consents-organization



import { RequiredRunnerHeaders } from '../schemas/required-headers-snippet.mdx';

# Accept Organization Consent

Accepts mandatory organization consent types required for activation.

## Endpoint

`POST /api/v2.1/customer/organization/{organizationId}/consents/{consentType}`

## Required Headers

<RequiredRunnerHeaders />

## Path Parameters

<ParamField path="organizationId" type="string" required>Organization UUID</ParamField>
<ParamField path="consentType" type="string" required>`terms`, `privacy`, `data-processing`</ParamField>

## Request Body

```json
{
  "accepted": true,
  "version": "1.0"
}
```

## Success Response

```json 200
{
  "code": 200,
  "message": "Success"
}
```


---

# Financial Operations

Post-activation APIs for balances, beneficiaries, consents, and transfers


URL: /baas/api/reference/financial-operations


---
title: 'Financial Operations'
description: 'Post-activation APIs for balances, beneficiaries, consents, and transfers'
---

# Financial Operations

Complete API reference for post-activation financial operations including wallet management, beneficiaries, transfers, and payments.

<Info>
  **Base URL:** `https://sandbox.finhub.cloud/api/v2.1/fintrans`
</Info>

<Note>
  For complete details on authentication and headers, refer to the [Standard HTTP Headers](../schemas/standard-headers) reference documentation.
</Note>

---

## Prerequisites

Before accessing financial operations:
- [ ] Customer account **ACTIVATED** (individual or organization)
- [ ] Wallet status = **ACTIVE**
- [ ] Valid JWT token from session
- [ ] Sufficient wallet balance (for outgoing transfers)

<Warning>
  **Activation Required:** All financial operations require account activation. Attempting to access before activation returns 404 or 422 errors.
</Warning>

---

## Core journey (happy path)

| Step | API | Purpose |
|------|-----|---------|
| 1 | `GET /fintrans/{accountId}/balance` | Confirm available funds |
| 2 | `POST /fintrans/{accountId}/beneficiaries` | Register a recipient |
| 3 | `POST /fintrans/{accountId}/payment-consents/types/{operationType}` | Create authorization (if required) |
| 4 | `POST /fintrans/{accountId}/types/{operationType}/prepare` | Validate and reserve funds |
| 5 | `POST /fintrans/{accountId}/types/{operationType}/execute` | Execute the prepared operation |
| 6 | `GET /fintrans/{accountId}/orders/{orderId}` | Monitor status |

---

## Endpoints

### Beneficiaries

<CardGroup cols={2}>
  <Card title="Add beneficiary (account)" href="/baas/api/reference/financial-operations/create-beneficiary">
    `POST /api/v2.1/fintrans/{accountId}/beneficiaries`
  </Card>
  <Card title="Get beneficiaries for wallet" href="/baas/api/reference/financial-operations/get-beneficiaries-for-wallet">
    `POST /api/v2.1/wallets/{walletId}/beneficiaries`
  </Card>
</CardGroup>

### Account information

<CardGroup cols={2}>
  <Card title="Get wallets by customer" href="/baas/api/reference/financial-operations/get-wallets-by-customer">
    `GET /api/v2.1/wallets/customer/{customerId}`
  </Card>
</CardGroup>

### Payment consents

<CardGroup cols={2}>
  <Card title="Create payment consent" href="/baas/api/reference/financial-operations/create-payment-consent">
    `POST /api/v2.1/fintrans/{accountId}/payment-consents/types/{operationType}`
  </Card>
</CardGroup>

### Prepare / execute

<CardGroup cols={2}>
  <Card title="Prepare financial operation" href="/baas/api/reference/financial-operations/prepare-financial-operation">
    `POST /api/v2.1/fintrans/{accountId}/types/{operationType}/prepare`
  </Card>
  <Card title="Execute prepared operation" href="/baas/api/reference/financial-operations/execute-prepared-operation">
    `POST /api/v2.1/fintrans/{accountId}/types/{operationType}/execute`
  </Card>
  <Card title="Approve verification" href="/baas/api/reference/verification-compliance/approve-verification">
    `POST /api/v2.1/verifications/{verificationId}/approve`
  </Card>
</CardGroup>


---

# Get wallets by customer

Retrieve a customer’s wallets and IBANs to use in financial operations.


URL: /baas/api/reference/financial-operations/get-wallets-by-customer



## Endpoint

`GET /api/v2.1/wallets/customer/{customerId}`

<Note>
  This endpoint requires `X-Forwarded-From` and a device header. The backend accepts any of:
  `deviceId`, `X-Device-Id`, `device-id`.
</Note>

## Sample cURL

```bash
curl --request GET \
  --url 'https://sandbox.finhub.cloud/api/v2.1/wallets/customer/{customerId}?customerType=B2C' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'X-Tenant-Id: <TENANT_ID>' \
  --header 'Accept: application/json' \
  --header 'X-Forwarded-From: <FORWARDED_FROM>' \
  --header 'deviceId: <DEVICE_ID>'
```

```bash
curl --request GET \
  --url 'https://sandbox.finhub.cloud/api/v2.1/wallets/customer/{customerId}?customerType=B2B' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'X-Tenant-Id: <TENANT_ID>' \
  --header 'Accept: application/json' \
  --header 'X-Forwarded-From: <FORWARDED_FROM>' \
  --header 'deviceId: <DEVICE_ID>'
```

## Response Example

```json
{
  "code": 200,
  "data": [
    {
      "id": "558ad9af-0482-471f-9385-5a943b80f6d2",
      "walletId": "558ad9af-0482-471f-9385-5a943b80f6d2",
      "customerId": "2dac1793-ab48-420c-b0b5-01292302e188",
      "name": "B2C Product General Purpose Wallet",
      "walletType": "b2c_product_general_purpose_wallet",
      "status": "ACTIVE",
      "currency": "EUR",
      "balance": "0.00",
      "availableBalance": "0.00",
      "iban": "LT213320011000055860"
    },
    {
      "id": "f9f66497-ef59-446b-9b32-34391b27c928",
      "walletId": "f9f66497-ef59-446b-9b32-34391b27c928",
      "customerId": "2dac1793-ab48-420c-b0b5-01292302e188",
      "name": "B2C Master General Purpose Wallet",
      "walletType": "b2c_master_general_purpose_wallet",
      "status": "ACTIVE",
      "currency": "EUR",
      "balance": "0.00",
      "availableBalance": "0.00"
    }
  ],
  "message": "Success"
}
```

<Note>
  After customer activation, poll this endpoint until wallets with IBAN appear. The IBAN is typically assigned to the Product General Purpose Wallet.
</Note>

## Missing Headers Error Example

```json
{
  "code": 500,
  "data": {
    "deviceId_accepted": [
      "deviceId",
      "X-Device-Id",
      "device-id"
    ],
    "missingHeaders": [
      "X-Forwarded-From",
      "deviceId"
    ]
  },
  "message": "Missing required header(s)"
}
```


---

# Account information

Balance and allowed operations


URL: /baas/api/reference/financial-operations/account-information


---
title: 'Account information'
description: 'Balance and allowed operations'
---

# Account information

<CardGroup cols={2}>
  <Card title="Allowed operations" href="/baas/api/reference/financial-operations/account-information/allowed-operations">
    `GET /api/v2.1/fintrans/{accountId}/allowed-operations`
  </Card>
  <Card title="Balance" href="/baas/api/reference/financial-operations/account-information/balance">
    `GET /api/v2.1/fintrans/{accountId}/balance`
  </Card>
  <Card title="Get wallets by customer" href="/baas/api/reference/financial-operations/get-wallets-by-customer">
    `GET /api/v2.1/wallets/customer/{customerId}?customerType=B2B/B2C`
  </Card>
  <Card title="Get beneficiaries for wallet" href="/baas/api/reference/financial-operations/get-beneficiaries-for-wallet">
    Allowed operations response includes beneficiaries when requested
  </Card>
</CardGroup>


---

# Get wallet balance (FinTrans)


URL: /baas/api/reference/financial-operations/account-information/balance



## Sample cURL

```bash
curl --request GET \
  --url 'https://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/balance' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'X-Tenant-Id: <TENANT_ID>' \
  --header 'Accept: application/json' \
  --header 'X-Forwarded-From: <FORWARDED_FROM>' \
  --header 'deviceId: <DEVICE_ID>'
```


---

# Allowed operations

Get allowed financial operations for an account, optionally including beneficiaries and consents.


URL: /baas/api/reference/financial-operations/account-information/allowed-operations



<Note>
  This endpoint requires `X-Forwarded-From` and a device header. The backend accepts any of:
  `deviceId`, `X-Device-Id`, `device-id`.
</Note>

## Sample cURL

```bash
curl --location 'https://sandbox.finhub.cloud/api/v2.1/fintrans/28e09085-2167-4284-ad1a-239122af836f/allowed-operations?includeBeneficiaries=true&includeConsents=true' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'X-Tenant-ID: <TENANT_ID>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'User-Agent: <USER_AGENT>' \
  --header 'X-Forwarded-From: <FORWARDED_FROM>' \
  --header 'X-Forwarded-For: <FORWARDED_FOR>' \
  --header 'platform: Web' \
  --header 'deviceId: <DEVICE_ID>' \
```

## Missing Headers Error Example

```json
{
  "code": 500,
  "data": {
    "deviceId_accepted": [
      "deviceId",
      "X-Device-Id",
      "device-id"
    ],
    "missingHeaders": [
      "X-Forwarded-From",
      "deviceId"
    ]
  },
  "message": "Missing required header(s)"
}
```

## Response Example

```json
{
  "code": 200,
  "data": {
    "sessionId": "e76cfef8-1897-45a3-b9c1-3e90ffb3fae0",
    "tenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
    "time": "2026-04-01T13:10:16.455800933",
    "accounts": [
      {
        "id": "28e09085-2167-4284-ad1a-239122af836f",
        "type": "CONSUMER_WALLET",
        "iban": "LT803320011000055865",
        "currency": "EUR",
        "balance": 0,
        "flags": {},
        "ownerId": "7d1d49db-bf39-4123-94d8-c03a1e6b4d4a",
        "assetId": "aeee88d3-bc7b-4f47-8850-8183bd9eb9b0",
        "assetSubUnitId": "dd35508b-7529-49b8-ae56-fafd523f953f"
      }
    ],
    "beneficiaries": [
      {
        "id": "03337653-7f7e-49af-a9fa-9ea444132510",
        "assetId": "03337653-7f7e-49af-a9fa-9ea444132510",
        "assetSubUnitId": "dd35508b-7529-49b8-ae56-fafd523f953f",
        "kind": "EXTERNAL",
        "walletId": "28e09085-2167-4284-ad1a-239122af836f",
        "currencyHints": [
          "EUR"
        ],
        "allowedOperationTypes": [],
        "beneficiaryId": "ba77dbdb-a1f4-48d0-bb50-a44123ffc9b2",
        "iban": "LT203320011000000006",
        "currency": "EUR",
        "partyType": "INDIVIDUAL_CUSTOMER",
        "status": "",
        "name": "",
        "assetSubUnitName": "European Monetary Unit"
      }
    ],
    "operations": [
      {
        "fromAccountId": "28e09085-2167-4284-ad1a-239122af836f",
        "fromAssetId": "aeee88d3-bc7b-4f47-8850-8183bd9eb9b0",
        "fromAssetSubUnitId": "dd35508b-7529-49b8-ae56-fafd523f953f",
        "toRefId": "03337653-7f7e-49af-a9fa-9ea444132510",
        "toAssetSubUnitId": "dd35508b-7529-49b8-ae56-fafd523f953f",
        "beneficiaryId": "ba77dbdb-a1f4-48d0-bb50-a44123ffc9b2",
        "opType": "PURCHASE",
        "currencies": [
          "EUR"
        ],
        "perTxnLimit": 50000,
        "requiresConsent": true
      }
    ],
    "limits": {
      "perTxn": {
        "EUR": 50000
      },
      "daily": {
        "EUR": 200000
      },
      "monthly": {
        "EUR": 1000000
      }
    },
    "fees": {
      "model": "SEPARATE_FEE_TRANSFER",
      "rules": {},
      "flags": {
        "feeChannel": "SEPARATE"
      }
    },
    "consentModel": {
      "requireConsent": true,
      "expiryMinutes": 30,
      "scope": "PAYMENT"
    },
    "snapshotId": "e76cfef8-1897-45a3-b9c1-3e90ffb3fae0",
    "hasBeneficiaries": true,
    "beneficiaryCount": 8
  },
  "message": "Success"
}
```


---

# Add beneficiary (account)

Create a beneficiary to be referenced when preparing and executing transfers.


URL: /baas/api/reference/financial-operations/create-beneficiary



## Endpoint

`POST /api/v2.1/fintrans/{accountId}/beneficiaries`

<Note>
  This endpoint requires `X-Forwarded-From` and a device header. The backend accepts any of:
  `deviceId`, `X-Device-Id`, `device-id`.
</Note>

## Sample cURL

```bash
curl --request POST \
  --url 'https://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/beneficiaries' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'X-Tenant-Id: <TENANT_ID>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'User-Agent: <USER_AGENT>' \
  --header 'X-Forwarded-From: <FORWARDED_FROM>' \
  --header 'platform: Web' \
  --header 'deviceId: <DEVICE_ID>' \
  --data '{
    "purposeCode": "SUPP",
    "postalCode": "LT-01103",
    "shortName": "",
    "bicSwiftCode": "SONCLT21",
    "lastName": "Customer",
    "city": "Vilnius",
    "email": "customer.20260331114946-387074@testcorp.com",
    "bankName": "UAB Sonect Europe",
    "currency": "EUR",
    "country": "LT",
    "networkName": "SEPA",
    "firstName": "John",
    "bankAddress": "Gedimino pr. 20, Vilnius, Lithuania",
    "customerId": "2dac1793-ab48-420c-b0b5-01292302e188",
    "addressLine1": "1 Test Street",
    "partyType": "INDIVIDUAL_CUSTOMER",
    "iban": "LT213320011000055860",
    "companyName": ""
  }'
```

## Response Example

```json
{
  "code": 200,
  "data": {
    "id": "3114774a-aa94-4648-9e57-5ff226ef02dd",
    "name": "",
    "iban": "LT213320011000055860",
    "type": "INDIVIDUAL_CUSTOMER",
    "status": "ACTIVE",
    "currency": "EUR",
    "country": "",
    "email": "",
    "phoneNumber": "",
    "shortName": "",
    "networkName": "SEPA",
    "bankName": "",
    "purposeCode": "",
    "assetId": "eba40e17-e539-430e-a6cc-2b0f01e4c86e"
  },
  "message": "Success"
}
```

<Note>
  Use the returned `assetId` as the `beneficiaryId` when preparing a financial operation.
</Note>

## Missing Headers Error Example

```json
{
  "code": 500,
  "data": {
    "deviceId_accepted": [
      "deviceId",
      "X-Device-Id",
      "device-id"
    ],
    "missingHeaders": [
      "X-Forwarded-From",
      "deviceId"
    ]
  },
  "message": "Missing required header(s)"
}
```


---

# Get beneficiaries for wallet

Retrieve allowed operations for an account, optionally including beneficiaries and consents.


URL: /baas/api/reference/financial-operations/get-beneficiaries-for-wallet



<Note>
  This endpoint requires `X-Forwarded-From` and a device header. The backend accepts any of:
  `deviceId`, `X-Device-Id`, `device-id`.
</Note>

## Sample cURL

```bash
curl --location 'https://sandbox.finhub.cloud/api/v2.1/fintrans/28e09085-2167-4284-ad1a-239122af836f/allowed-operations?includeBeneficiaries=true&includeConsents=true' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'X-Tenant-ID: <TENANT_ID>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'User-Agent: <USER_AGENT>' \
  --header 'X-Forwarded-From: <FORWARDED_FROM>' \
  --header 'X-Forwarded-For: <FORWARDED_FOR>' \
  --header 'platform: Web' \
  --header 'deviceId: <DEVICE_ID>' \
```

## Missing Headers Error Example

```json
{
  "code": 500,
  "data": {
    "deviceId_accepted": [
      "deviceId",
      "X-Device-Id",
      "device-id"
    ],
    "missingHeaders": [
      "X-Forwarded-From",
      "deviceId"
    ]
  },
  "message": "Missing required header(s)"
}
```

## Response Example

```json
{
  "code": 200,
  "data": {
    "sessionId": "e76cfef8-1897-45a3-b9c1-3e90ffb3fae0",
    "tenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
    "time": "2026-04-01T13:10:16.455800933",
    "accounts": [
      {
        "id": "28e09085-2167-4284-ad1a-239122af836f",
        "type": "CONSUMER_WALLET",
        "iban": "LT803320011000055865",
        "currency": "EUR",
        "balance": 0,
        "flags": {},
        "ownerId": "7d1d49db-bf39-4123-94d8-c03a1e6b4d4a",
        "assetId": "aeee88d3-bc7b-4f47-8850-8183bd9eb9b0",
        "assetSubUnitId": "dd35508b-7529-49b8-ae56-fafd523f953f"
      }
    ],
    "beneficiaries": [
      {
        "id": "03337653-7f7e-49af-a9fa-9ea444132510",
        "assetId": "03337653-7f7e-49af-a9fa-9ea444132510",
        "assetSubUnitId": "dd35508b-7529-49b8-ae56-fafd523f953f",
        "kind": "EXTERNAL",
        "walletId": "28e09085-2167-4284-ad1a-239122af836f",
        "currencyHints": [
          "EUR"
        ],
        "allowedOperationTypes": [],
        "beneficiaryId": "ba77dbdb-a1f4-48d0-bb50-a44123ffc9b2",
        "iban": "LT203320011000000006",
        "currency": "EUR",
        "partyType": "INDIVIDUAL_CUSTOMER",
        "status": "",
        "name": "",
        "assetSubUnitName": "European Monetary Unit"
      }
    ],
    "operations": [
      {
        "fromAccountId": "28e09085-2167-4284-ad1a-239122af836f",
        "fromAssetId": "aeee88d3-bc7b-4f47-8850-8183bd9eb9b0",
        "fromAssetSubUnitId": "dd35508b-7529-49b8-ae56-fafd523f953f",
        "toRefId": "03337653-7f7e-49af-a9fa-9ea444132510",
        "toAssetSubUnitId": "dd35508b-7529-49b8-ae56-fafd523f953f",
        "beneficiaryId": "ba77dbdb-a1f4-48d0-bb50-a44123ffc9b2",
        "opType": "PURCHASE",
        "currencies": [
          "EUR"
        ],
        "perTxnLimit": 50000,
        "requiresConsent": true
      }
    ],
    "limits": {
      "perTxn": {
        "EUR": 50000
      },
      "daily": {
        "EUR": 200000
      },
      "monthly": {
        "EUR": 1000000
      }
    },
    "fees": {
      "model": "SEPARATE_FEE_TRANSFER",
      "rules": {},
      "flags": {
        "feeChannel": "SEPARATE"
      }
    },
    "consentModel": {
      "requireConsent": true,
      "expiryMinutes": 30,
      "scope": "PAYMENT"
    },
    "snapshotId": "e76cfef8-1897-45a3-b9c1-3e90ffb3fae0",
    "hasBeneficiaries": true,
    "beneficiaryCount": 8
  },
  "message": "Success"
}
```


---

# Create payment consent

Create a payment consent and receive a magicLinkToken containing the authentication code for execution.


URL: /baas/api/reference/financial-operations/create-payment-consent



## Endpoint

`POST /api/v2.1/fintrans/{accountId}/payment-consents/types/{operationType}`

<Note>
  This endpoint requires `X-Forwarded-From` and a device header. The backend accepts any of:
  `deviceId`, `X-Device-Id`, `device-id`.
</Note>

## Sample cURL

```bash
curl --request POST \
  --url 'https://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/payment-consents/types/{operationType}' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'X-Tenant-Id: <TENANT_ID>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'User-Agent: <USER_AGENT>' \
  --header 'X-Forwarded-From: <FORWARDED_FROM>' \
  --header 'platform: Web' \
  --header 'deviceId: <DEVICE_ID>' \
  --data '{
    "metadata": {
      "parameters": {
        "validity": {
          "endDate": "2027-12-31",
          "startDate": "2025-10-01",
          "maxUsageCount": 100
        },
        "beneficiaries": {
          "requireBeneficiaryName": true,
          "allowedTypes": [
            "sepa_transfer_internal"
          ],
          "allowedAccounts": [
            "LT213320011000055860"
          ],
          "allowNewBeneficiaries": false
        },
        "limits": {
          "maxTransactionsPerDay": 10,
          "maxAmountPerTransaction": {
            "currency": "EUR",
            "amount": 10000
          },
          "maxAmountPerDay": {
            "currency": "EUR",
            "amount": 20000
          }
        }
      },
      "paymentType": "TRANSFER",
      "questions": {
        "question": "I consent to the processing",
        "answer": ""
      },
      "title": "Payment Consent"
    },
    "verificationData": {
      "consentVersion": "1.0",
      "scope": "Transfer processing",
      "consentPurpose": "Payment Consent"
    },
    "entityId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
    "verificationStatus": "PENDING",
    "entityType": "ORGANIZATION",
    "verificationType": "CONSENT",
    "tenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
    "documentId": "59ddc658-7cfc-4dbe-ac82-c716330b44eb",
    "documentType": "PAYMENT_CONSENT"
  }'
```

## Response Example

```json
{
  "code": 200,
  "data": {
    "consentId": "f3822ff0-3986-4fef-84eb-7b517e657b6f",
    "id": "f3822ff0-3986-4fef-84eb-7b517e657b6f",
    "operationType": "transfer",
    "status": "APPROVED",
    "walletId": "d7d94804-4d8b-45af-862f-77cbcef740f4",
    "accountId": "d7d94804-4d8b-45af-862f-77cbcef740f4",
    "message": "Consent created successfully",
    "magicLinkToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "message": "Success"
}
```

<Note>
  Decode the `magicLinkToken` JWT and extract the `answer` field. That value is the `authenticationCode` required to execute a prepared operation.
</Note>

## Missing Headers Error Example

```json
{
  "code": 500,
  "data": {
    "deviceId_accepted": [
      "deviceId",
      "X-Device-Id",
      "device-id"
    ],
    "missingHeaders": [
      "X-Forwarded-From",
      "deviceId"
    ]
  },
  "message": "Missing required header(s)"
}
```


---

# Prepare financial operation

Prepare a financial operation before execution. Returns a preparedOrderId used by the execute endpoint.


URL: /baas/api/reference/financial-operations/prepare-financial-operation



## Endpoint

`POST /api/v2.1/fintrans/{accountId}/types/{operationType}/prepare`

<Note>
  This endpoint requires `X-Forwarded-From` and a device header. The backend accepts any of:
  `deviceId`, `X-Device-Id`, `device-id`.
</Note>

## Sample cURL

```bash
curl --request POST \
  --url 'https://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/types/{operationType}/prepare' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'X-Tenant-Id: <TENANT_ID>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'User-Agent: <USER_AGENT>' \
  --header 'X-Forwarded-From: <FORWARDED_FROM>' \
  --header 'platform: Web' \
  --header 'deviceId: <DEVICE_ID>' \
  --data '{
    "type": "INTERNAL",
    "target": {
      "name": "John Customer",
      "iban": "LT213320011000055860"
    },
    "currency": "EUR",
    "beneficiaryName": "John Customer",
    "amount": {
      "value": "100000",
      "scale": 2,
      "currency": "EUR"
    },
    "beneficiaryId": "eba40e17-e539-430e-a6cc-2b0f01e4c86e",
    "sourceAccount": {
      "walletId": "d7d94804-4d8b-45af-862f-77cbcef740f4"
    },
    "companyName": "John Customer",
    "description": "Internal funding transfer to customer wallet",
    "consent": {
      "consentReference": "f3822ff0-3986-4fef-84eb-7b517e657b6f"
    }
  }'
```

## Response Example

```json
{
  "code": 200,
  "data": {
    "preparedOrderId": "621d1386-f2fb-4655-88a8-997db0ec446a",
    "status": "READY"
  },
  "message": "Success"
}
```

<Note>
  Use the returned `preparedOrderId` as input to the execute endpoint.
</Note>

## Missing Headers Error Example

```json
{
  "code": 500,
  "data": {
    "deviceId_accepted": [
      "deviceId",
      "X-Device-Id",
      "device-id"
    ],
    "missingHeaders": [
      "X-Forwarded-From",
      "deviceId"
    ]
  },
  "message": "Missing required header(s)"
}
```


---

# Execute prepared operation

Execute a previously prepared operation using preparedOrderId and authenticationCode.


URL: /baas/api/reference/financial-operations/execute-prepared-operation



## Endpoint

`POST /api/v2.1/fintrans/{accountId}/types/{operationType}/execute`

<Note>
  This endpoint requires `X-Forwarded-From` and a device header. The backend accepts any of:
  `deviceId`, `X-Device-Id`, `device-id`.
</Note>

## Sample cURL

```bash
curl --request POST \
  --url 'https://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/types/{operationType}/execute' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'X-Tenant-Id: <TENANT_ID>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'User-Agent: <USER_AGENT>' \
  --header 'X-Forwarded-From: <FORWARDED_FROM>' \
  --header 'platform: Web' \
  --header 'deviceId: <DEVICE_ID>' \
  --data '{
    "consentConfirmation": {
      "consentId": "f3822ff0-3986-4fef-84eb-7b517e657b6f",
      "channel": "WEB",
      "signature": "integration-test-signature",
      "confirmed": true
    },
    "preparedOrderId": "621d1386-f2fb-4655-88a8-997db0ec446a",
    "authenticationCode": "768807"
  }'
```

## Response Example

```json
{
  "code": 200,
  "data": {
    "preparedOrderId": "621d1386-f2fb-4655-88a8-997db0ec446a",
    "status": "EXECUTING",
    "executedAt": "2026-03-31T11:50:16+03:00"
  },
  "message": "Success"
}
```

<Note>
  The `authenticationCode` is taken from the `magicLinkToken` returned when creating the payment consent (decode the JWT and extract the `answer` field).
</Note>

## Missing Headers Error Example

```json
{
  "code": 500,
  "data": {
    "deviceId_accepted": [
      "deviceId",
      "X-Device-Id",
      "device-id"
    ],
    "missingHeaders": [
      "X-Forwarded-From",
      "deviceId"
    ]
  },
  "message": "Missing required header(s)"
}
```


---

# Administration

APIs for administrative operations


URL: /baas/api/reference/administration



# Administration APIs

APIs for session management, user management, and consent template administration.

## Base URL

```
https://api.finhub.cloud/api/v2.1/admin
```

<CardGroup cols={3}>
  <Card title="Session Management" icon="key" href="/baas/api/integration/flows/individual-customer/session-management">
    Customer and admin session login flows
  </Card>
  <Card title="User Management" icon="users-round" href="/baas/api/reference/customer-apis/organization/management">
    Manage organization users, directors, and employees
  </Card>
  <Card title="Consent Templates" icon="file-text" href="/baas/api/reference/verification-compliance/consents-individual">
    Consent collection for individuals and organizations
  </Card>
</CardGroup>

## Authentication

Admin APIs require elevated permissions. Ensure your access token has the appropriate admin role.

```bash
curl -X POST "https://api.finhub.cloud/api/v2.1/admin/session/login" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -d '{"username": "admin@tenant.com", "password": "..."}'
```


---

# Developer Tools

Developer utilities and tools


URL: /baas/api/reference/developer-tools



# Developer Tools

APIs and tools for developers.

## Categories

| Category | Description |
|----------|-------------|
| **Testing** | Test utilities |
| **Webhooks** | Webhook management |

## Guides

- [Testing tools](/baas/api/development/testing-tools)
- [Webhooks (FinCard)](/paas/fincard-virtual/webhooks)


---

# Hybrid Service Model

Combined CoreX and API approach for maximum flexibility


URL: /baas/hybrid/introduction



# Hybrid Service Model

The Hybrid Service Model combines CoreX and API approaches for maximum flexibility.

## What is Hybrid?

Hybrid allows you to use CoreX for some processes while using API for others. This gives you the best of both worlds:

- **Speed**: Use CoreX for standard flows
- **Customization**: Use API for custom features
- **Flexibility**: Mix and match as needed

## Common Hybrid Patterns

| Use Case | CoreX | API |
|----------|-------|-----|
| **Standard + Custom Payments** | Onboarding, accounts | Custom payment UI |
| **White-Label + Custom Analytics** | Full front-end | Custom reporting |
| **Migration Path** | Start with CoreX | Gradually add API |

## Benefits

- **Faster Time to Market**: Launch with CoreX
- **Gradual Customization**: Add API integrations over time
- **Reduced Risk**: Proven CoreX + custom where needed
- **Cost Optimization**: CoreX for standard, API for differentiators

## When to Choose Hybrid

Choose Hybrid if you:

- Want to launch quickly but need some custom features
- Have limited initial resources but plan to customize later
- Need standard flows + specific differentiators
- Are migrating from CoreX to API gradually

## Admin Panel

Hybrid clients have unified access to the Admin Panel for both CoreX and API operations.

## Next Steps

<CardGroup cols={2}>
  <Card title="Getting Started" icon="rocket" href="/baas/hybrid/getting-started">
    Start with Hybrid
  </Card>
  <Card title="Configuration" icon="gear" href="/baas/hybrid/configuration">
    Configure Hybrid setup
  </Card>
</CardGroup>


---

# Getting Started with Hybrid

Getting started with Hybrid Service Model


URL: /baas/hybrid/getting-started



# Getting Started with Hybrid

Set up your Hybrid integration combining CoreX and API.

## Hybrid Journey

<Steps>
  <Step title="Plan Your Architecture">
    Decide which processes use CoreX vs API
  </Step>
  <Step title="Set Up CoreX">
    Configure your white-label platform
  </Step>
  <Step title="Set Up API Access">
    Get API credentials for custom integrations
  </Step>
  <Step title="Integrate">
    Connect your custom components
  </Step>
  <Step title="Go-Live">
    Launch your hybrid solution
  </Step>
</Steps>

## Planning Considerations

| Question | CoreX | API |
|----------|-------|-----|
| Standard user flows? | ✅ | |
| Custom user flows? | | ✅ |
| Fast time to market? | ✅ | |
| Deep customization? | | ✅ |
| Managed maintenance? | ✅ | |

## Common Configurations

### CoreX Front-end + API Back-office

- CoreX for customer-facing apps
- API for custom back-office integrations

### CoreX Standard + API Custom Flows

- CoreX for onboarding, accounts
- API for custom payment experiences

### CoreX MVP + API Future

- Launch with CoreX
- Add API customizations over time

## Timeline

| Phase | Duration |
|-------|----------|
| Planning | 1 week |
| CoreX Setup | 2-3 weeks |
| API Integration | 2-4 weeks |
| Testing | 1-2 weeks |
| Go-Live | 1 week |

**Total: 4-8 weeks**


---

# Configuration

Configure your Hybrid Service Model setup


URL: /baas/hybrid/configuration



# Hybrid Configuration

Configure how CoreX and API work together in your Hybrid setup.

## Configuration Areas

### CoreX Configuration

Same as standalone CoreX:

- Branding and white-labeling
- Product selection
- Feature configuration
- Domain setup

### API Configuration

Same as standalone API:

- Sandbox credentials
- Webhook setup
- Integration endpoints

### Integration Points

Configure how CoreX and API connect:

| Integration | Configuration |
|-------------|---------------|
| **Authentication** | Shared or separate sessions |
| **Data Sync** | Real-time or batch |
| **Webhooks** | Event subscriptions |
| **Deep Links** | CoreX ↔ Custom app |

## Session Management

Options for handling user sessions:

- **Unified**: Single session across CoreX and custom apps
- **Separate**: Independent sessions with SSO
- **Handoff**: Transfer session between systems

## Data Consistency

Ensure data consistency between CoreX and API:

- Use webhooks to sync state
- Implement idempotency keys
- Handle race conditions

## Best Practices

- Start with CoreX for core flows
- Add API integrations incrementally
- Test integration points thoroughly
- Monitor both systems together


---

# Hybrid Operations

Day-to-day operations for Hybrid clients


URL: /baas/hybrid/operations



# Hybrid Operations

Manage your Hybrid setup with unified operations.

## Unified Admin Panel

Hybrid clients get a single Admin Panel for:

- CoreX customer management
- API integration monitoring
- Unified reporting
- Cross-system workflows

<Card title="Admin Panel" icon="gauge" href="/baas/hybrid/operations/admin-panel">
  Access the unified Admin Panel
</Card>

## Operational Responsibilities

### FinHub Manages

- CoreX platform infrastructure
- API gateway and services
- Security updates
- Compliance framework

### You Manage

- Custom API integrations
- Integration point monitoring
- Business operations
- Customer support

## Monitoring

Monitor both systems:

| System | Metrics |
|--------|---------|
| **CoreX** | User activity, errors |
| **API** | Response times, error rates |
| **Integration** | Sync status, webhook delivery |

## Support

Single support channel for both CoreX and API issues.


---

# Admin Panel

Unified Admin Panel for Hybrid operations


URL: /baas/hybrid/operations/admin-panel



# Hybrid Admin Panel

The Hybrid Admin Panel provides unified management for both CoreX and API components.

## Key Features

| Feature | Description |
|---------|-------------|
| **Customer Management** | View all customers (CoreX + API) |
| **Transaction Monitoring** | All transactions in one view |
| **Approvals** | Unified approval workflows |
| **Reporting** | Combined analytics |

## CoreX Functions

- Manage CoreX users
- View CoreX activity
- Configure CoreX settings

## API Functions

- Monitor API usage
- View API transactions
- Manage webhooks

## Unified Functions

- Combined customer view
- Cross-system reporting
- Unified compliance workflows

## Access Control

- Role-based permissions
- Separate roles for CoreX vs API admin
- Super admin for full access


---

# Platform as a Service (PaaS)

System-to-system integration via connectors


URL: /paas/introduction



# Platform as a Service (PaaS)

FinHub PaaS provides system-to-system integration capabilities for organizations with existing financial infrastructure.

## What is PaaS?

Unlike BaaS which provides complete business processes, PaaS offers **connectors** that enable your existing systems to integrate with financial networks, payment rails, and third-party services.

## Key Differences from BaaS

| Aspect | BaaS | PaaS |
|--------|------|------|
| **Focus** | Business processes | System connectivity |
| **Target** | End-user services | Backend integration |
| **Approach** | Microservices | Connectors |
| **UI** | Optional (CoreX) | None |
| **Use Case** | Build financial products | Extend existing systems |

## PaaS Connectors

FinHub PaaS provides connectors for:

<CardGroup cols={2}>
  <Card title="Payment Rails" icon="road" href="/paas/connectors/banking-networks">
    SEPA, SWIFT, local schemes
  </Card>
  <Card title="Card Networks" icon="credit-card" href="/paas/connectors/acquiring-ipg">
    Visa, Mastercard, schemes
  </Card>
  <Card title="KYC Providers" icon="id-card" href="/paas/connectors/kyc-kyb">
    Identity verification services
  </Card>
  <Card title="Banking Partners" icon="building-columns" href="/paas/connectors/banking-networks">
    Correspondent banking
  </Card>
</CardGroup>

## When to Choose PaaS

PaaS is ideal if you:

- Have existing core banking systems
- Need to connect to specific payment rails
- Want to add capabilities to current infrastructure
- Require system-to-system integration
- Don't need end-user interfaces

## Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                    Your Existing Systems                        │
│         (Core Banking, ERP, CRM, Custom Applications)          │
└───────────────────────────────┬─────────────────────────────────┘
                                │
                                │ REST APIs / Webhooks
                                │
┌───────────────────────────────▼─────────────────────────────────┐
│                        FinHub PaaS                              │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                   Connector Layer                        │   │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────────┐│   │
│  │  │ Banking │ │Acquiring│ │ KYC/KYB │ │  Communication  ││   │
│  │  │Networks │ │  & IPG  │ │         │ │                 ││   │
│  │  └─────────┘ └─────────┘ └─────────┘ └─────────────────┘│   │
│  │  ┌─────────────────────┐ ┌─────────────────────────────┐│   │
│  │  │       Crypto        │ │     Additional Connectors   ││   │
│  │  └─────────────────────┘ └─────────────────────────────┘│   │
│  └─────────────────────────────────────────────────────────┘   │
└───────────────────────────────┬─────────────────────────────────┘
                                │
        ┌───────────┬───────────┼───────────┬───────────┐
        ▼           ▼           ▼           ▼           ▼
   ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
   │  SEPA   │ │  SWIFT  │ │  Card   │ │   KYC   │ │   SMS   │
   │ Network │ │ Network │ │ Schemes │ │Providers│ │  Email  │
   └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Connectors" icon="plug" href="/paas/connectors">
    Explore available connectors
  </Card>
  <Card title="Integration" icon="code" href="/paas/journey/integration">
    Integration guide
  </Card>
</CardGroup>


---

# Connectors Overview

Available FinHub PaaS connectors for system integration


URL: /paas/connectors



# Connectors Overview

FinHub PaaS provides connectors for integrating your systems with financial networks and services.

## Available Connectors

<CardGroup cols={2}>
  <Card title="Payment Rails" icon="road" href="/paas/connectors/banking-networks">
    Payment network connectivity
  </Card>
  <Card title="Card Networks" icon="credit-card" href="/paas/connectors/acquiring-ipg">
    Card scheme integration
  </Card>
  <Card title="KYC Providers" icon="id-card" href="/paas/connectors/kyc-kyb">
    Identity verification
  </Card>
  <Card title="Banking Partners" icon="building-columns" href="/paas/connectors/banking-networks">
    Correspondent banking
  </Card>
</CardGroup>

## Connector Categories

### Payment Rails

Connect to payment networks:

| Connector | Coverage | Features |
|-----------|----------|----------|
| **SEPA** | Eurozone | SCT, SDD, Instant |
| **SWIFT** | Global | MT, MX messages |
| **Local Rails** | Country-specific | Domestic payments |

### Card Networks

Integrate with card schemes:

| Connector | Networks | Features |
|-----------|----------|----------|
| **Issuing** | Visa, MC | Card issuance |
| **Acquiring** | Visa, MC | Payment acceptance |
| **Processing** | All | Authorization, settlement |

### KYC Providers

Connect to verification services:

| Connector | Type | Features |
|-----------|------|----------|
| **Document** | ID verification | OCR, validation |
| **Biometric** | Face matching | Liveness, comparison |
| **Data** | Database checks | PEP, sanctions |

### Banking Partners

Access banking services:

| Connector | Service | Features |
|-----------|---------|----------|
| **Correspondent** | Nostro/Vostro | Account access |
| **Clearing** | Settlement | Net settlement |
| **FX** | Currency | Exchange services |

## Integration Model

All connectors follow a standard integration pattern:

1. **Authentication**: OAuth 2.0 credentials
2. **Configuration**: Connector-specific settings
3. **API Calls**: RESTful endpoints
4. **Webhooks**: Event notifications

## Next Steps

<CardGroup cols={2}>
  <Card title="Payment Rails" icon="road" href="/paas/connectors/banking-networks">
    Connect to payments
  </Card>
  <Card title="Integration Guide" icon="code" href="/paas/journey/integration">
    Start integrating
  </Card>
</CardGroup>


---

# Acquiring (IPG)

Internet Payment Gateway for card acquiring


URL: /paas/connectors/acquiring-ipg



# Acquiring (IPG)

Connect to card acquiring and payment gateway services.

## Overview

The IPG connector enables merchants to accept card payments through FinHub's acquiring partners.

## Features

| Feature | Description |
|---------|-------------|
| **Authorization** | Real-time card authorization |
| **Capture** | Settlement and capture |
| **Refunds** | Full and partial refunds |
| **3D Secure** | Strong customer authentication |
| **Tokenization** | Secure card storage |

## Supported Cards

- Visa
- Mastercard
- Local schemes (region-specific)

## Integration

```json
{
  "connector": "acquiring_ipg",
  "operation": "authorize",
  "amount": 100.00,
  "currency": "EUR",
  "card_token": "tok_123"
}
```

## Use Cases

- E-commerce payments
- In-app purchases
- Subscription billing
- Point of sale


---

# Banking Networks

SEPA, SWIFT, and local payment network connectors


URL: /paas/connectors/banking-networks



# Banking Networks

Connect to major banking and payment networks.

## Available Networks

| Network | Coverage | Type |
|---------|----------|------|
| **SEPA** | Eurozone | Credit/Debit/Instant |
| **SWIFT** | Global | Wire transfers |
| **Local Rails** | Regional | Domestic payments |

## SEPA Services

- SEPA Credit Transfer (SCT)
- SEPA Direct Debit (SDD)
- SEPA Instant (SCT Inst)

## SWIFT Services

- MT messages (legacy)
- MX messages (ISO 20022)
- SWIFT gpi tracking

## Integration

```json
{
  "connector": "banking_networks",
  "network": "sepa_sct",
  "amount": 1000.00,
  "currency": "EUR",
  "creditor_iban": "DE89370400440532013000"
}
```

## See Also

- [Acquiring & IPG](/paas/connectors/acquiring-ipg) - Card acquiring and payment gateway


---

# KYC/KYB

Identity verification and compliance connectors


URL: /paas/connectors/kyc-kyb



# KYC/KYB Connectors

Connect to identity verification and compliance services.

## Verification Types

| Type | Description |
|------|-------------|
| **KYC** | Know Your Customer (individuals) |
| **KYB** | Know Your Business (companies) |
| **AML** | Anti-money laundering screening |

## KYC Services

- Document verification (ID, passport)
- Biometric verification (face match)
- Liveness detection
- Address verification

## KYB Services

- Company registry checks
- Director verification
- UBO identification
- Business document validation

## Screening Services

- PEP screening
- Sanctions lists
- Adverse media
- Ongoing monitoring

## Integration

```json
{
  "connector": "kyc_kyb",
  "type": "individual",
  "checks": ["document", "biometric", "pep"],
  "document_type": "passport"
}
```

## See Also

- [Communication](/paas/connectors/communication) - Communication connectors


---

# Communication

SMS, email, and push notification connectors


URL: /paas/connectors/communication



# Communication Connectors

Connect to messaging and notification services.

## Available Channels

| Channel | Use Cases |
|---------|-----------|
| **SMS** | OTP, alerts, notifications |
| **Email** | Transactional, statements |
| **Push** | Mobile app notifications |

## SMS Connector

- OTP delivery
- Transaction alerts
- Marketing (opt-in)
- Multi-provider support

## Email Connector

- Transactional emails
- Account statements
- Marketing campaigns
- Template management

## Push Notifications

- iOS APNs
- Android FCM
- Web push

## Integration

```json
{
  "connector": "communication",
  "channel": "sms",
  "to": "+1234567890",
  "template": "otp_verification",
  "data": { "code": "123456" }
}
```

## Delivery Tracking

- Delivery status webhooks
- Read receipts (email)
- Failure handling


---

# Crypto

Cryptocurrency and blockchain connectors


URL: /paas/connectors/crypto



# Crypto Connectors

Connect to cryptocurrency and blockchain services.

## Available Services

| Service | Description |
|---------|-------------|
| **Wallet** | Crypto wallet management |
| **Exchange** | Fiat-crypto conversion |
| **Custody** | Secure asset storage |
| **Payments** | Crypto payment acceptance |

## Supported Assets

- Bitcoin (BTC)
- Ethereum (ETH)
- Stablecoins (USDT, USDC)
- Other major cryptocurrencies

## Features

- Real-time exchange rates
- Multi-signature security
- Compliance screening
- Transaction monitoring

## Integration

```json
{
  "connector": "crypto",
  "operation": "exchange",
  "from_currency": "EUR",
  "to_currency": "BTC",
  "amount": 1000.00
}
```

## Compliance

- Travel rule compliance
- AML screening
- Transaction monitoring
- Regulatory reporting


---

# PaaS Journey

Complete PaaS client journey from onboarding to production


URL: /paas/journey



# PaaS Client Journey

The path to becoming a FinHub PaaS client.

## Journey Overview

<Steps>
  <Step title="Initial Contact">
    Discuss requirements with sales team
  </Step>
  <Step title="Technical Assessment">
    Evaluate connector requirements
  </Step>
  <Step title="Agreement">
    Sign PaaS client agreement
  </Step>
  <Step title="Sandbox Setup">
    Get sandbox credentials for connectors
  </Step>
  <Step title="Integration">
    Build and test your integration
  </Step>
  <Step title="Certification">
    Complete connector certification
  </Step>
  <Step title="Production">
    Go live with connectors
  </Step>
</Steps>

## Timeline

| Phase | Duration |
|-------|----------|
| Assessment | 1-2 weeks |
| Agreement | 1 week |
| Sandbox Setup | 1-2 days |
| Integration | 4-8 weeks |
| Certification | 1-2 weeks |
| Production | 1 week |

**Total: 8-14 weeks** (varies by connector complexity)

## Requirements

To become a PaaS client:

- Existing financial systems
- Technical integration capability
- Compliance framework
- Specific connector needs

## Next Steps

<CardGroup cols={2}>
  <Card title="Connectors" icon="plug" href="/paas/connectors">
    Browse available connectors
  </Card>
  <Card title="Integration" icon="code" href="/paas/journey/integration">
    Start integrating
  </Card>
</CardGroup>


---

# Getting Started

Apply for PaaS access


URL: /paas/journey/getting-started



# Getting Started with PaaS

Begin your PaaS journey by applying for connector access.

## Prerequisites

- Existing financial infrastructure
- Technical integration capability
- Compliance framework in place
- Specific connector requirements identified

## Application Process

1. **Contact Sales**: Discuss your connector requirements
2. **Technical Assessment**: Evaluate integration needs
3. **Agreement**: Sign PaaS client agreement
4. **Credentials**: Receive sandbox credentials

## What to Prepare

| Item | Description |
|------|-------------|
| **Company Info** | Legal entity details |
| **Use Case** | Connector requirements |
| **Technical Contact** | Integration team lead |
| **Compliance Docs** | Regulatory status |

## Next Steps

<Card title="Integration" icon="plug" href="/paas/journey/integration">
  Start integrating connectors
</Card>


---

# Integration

Connect to PaaS connectors


URL: /paas/journey/integration



# PaaS Integration

Build your integration with FinHub PaaS connectors.

## Integration Steps

1. **Get Credentials**: Obtain sandbox API credentials
2. **Configure**: Set up connector-specific settings
3. **Develop**: Build integration using APIs
4. **Test**: Validate in sandbox environment

## Authentication

All connectors use OAuth 2.0:

```bash
POST /paas/oauth/token
```

## Common Integration Pattern

```json
{
  "connector": "connector_name",
  "operation": "operation_type",
  "data": { ... }
}
```

## Best Practices

- Use idempotency keys
- Implement webhook handlers
- Handle errors gracefully
- Log all transactions

## Next Steps

<Card title="Testing" icon="vial" href="/paas/journey/testing">
  Test your integration
</Card>


---

# Testing

Validate your PaaS integrations


URL: /paas/journey/testing



# Testing & Certification

Validate your PaaS integration before going to production.

## Testing Phases

| Phase | Focus |
|-------|-------|
| **Unit Testing** | Individual connector calls |
| **Integration Testing** | End-to-end flows |
| **Performance Testing** | Load and stress tests |
| **Security Review** | Vulnerability assessment |

## Sandbox Testing

- Test all connector operations
- Simulate error scenarios
- Validate webhook handling
- Check edge cases

## Certification Checklist

- [ ] All endpoints tested
- [ ] Error handling verified
- [ ] Webhooks configured
- [ ] Security review passed
- [ ] Performance validated

## Common Test Scenarios

- Successful transactions
- Failed transactions
- Timeout handling
- Rate limit handling
- Webhook delivery

## Next Steps

<Card title="Production" icon="rocket" href="/paas/journey/production">
  Go to production
</Card>


---

# Production

Go live with PaaS connectors


URL: /paas/journey/production



# Production Deployment

Deploy your PaaS integration to production.

## Pre-Production Checklist

- [ ] Certification completed
- [ ] Security review passed
- [ ] Production credentials obtained
- [ ] Monitoring configured
- [ ] Rollback plan documented

## Production Credentials

After certification approval:

1. Request production credentials
2. Configure production environment
3. Update API endpoints
4. Test connectivity

## Go-Live Process

1. **Phased Rollout**: Start with limited traffic
2. **Monitor**: Watch for errors and anomalies
3. **Scale**: Gradually increase volume
4. **Validate**: Confirm all flows working

## Production URLs

| Environment | URL |
|-------------|-----|
| **Sandbox** | sandbox.paas.finhub.cloud |
| **Production** | paas.finhub.cloud |

## Post-Launch

- Monitor transaction volumes
- Track error rates
- Review performance metrics
- Optimize as needed


---

# PaaS Operations

Day-to-day operations for PaaS clients


URL: /paas/operations



# PaaS Operations

Manage your PaaS connectors day-to-day.

## Operational Dashboard

Access the PaaS dashboard for:

- Connector status monitoring
- Transaction tracking
- Error logs and alerts
- Usage statistics

## Monitoring

### Connector Health

| Metric | Description |
|--------|-------------|
| **Status** | Up/Down/Degraded |
| **Latency** | Response times |
| **Error Rate** | Failed requests |
| **Throughput** | Transactions/second |

### Alerts

Configure alerts for:

- Connector outages
- High error rates
- Rate limit warnings
- Settlement issues

## Support

| Type | Response Time |
|------|---------------|
| **Critical** | 1 hour |
| **High** | 4 hours |
| **Normal** | 24 hours |

**Contact:** support@finhub.cloud

## Maintenance

- Scheduled maintenance windows
- Connector updates
- API version changes
- Security patches

## Reporting

- Transaction reports
- Usage reports
- Settlement reports
- Compliance reports


---

# Admin Panel

PaaS monitoring, logs, and administration


URL: /paas/operations/admin-panel



# PaaS Admin Panel

Monitor and manage your PaaS connector integrations.

## Dashboard

- Connector status overview
- Transaction metrics
- Error rates
- Usage statistics

## Monitoring

| Feature | Description |
|---------|-------------|
| **Real-time Status** | Connector health monitoring |
| **Logs** | Transaction and error logs |
| **Alerts** | Configurable notifications |
| **Metrics** | Performance dashboards |

## Transaction Management

- Search transactions
- View transaction details
- Export reports
- Handle exceptions

## Configuration

- Connector settings
- Webhook management
- API credentials
- Rate limit monitoring

## Access Control

- Role-based permissions
- Audit logging
- Session management


---

# Support

Getting help with PaaS


URL: /paas/operations/support



# PaaS Support

Get help with your PaaS connector integrations.

## Support Channels

| Channel | Contact |
|---------|---------|
| **Email** | support@finhub.cloud |
| **Portal** | Developer Portal tickets |
| **Emergency** | 24/7 hotline (production) |

## Response Times

| Priority | Response |
|----------|----------|
| **Critical** | 1 hour |
| **High** | 4 hours |
| **Normal** | 24 hours |

## Before Contacting Support

Please have ready:

- Tenant ID and connector name
- Transaction reference (if applicable)
- Error messages or codes
- Steps to reproduce

## Common Issues

- Authentication errors
- Connector timeouts
- Webhook delivery failures
- Rate limit exceeded

## Self-Service

- [Connectors Documentation](/paas/connectors)
- [Integration Guide](/paas/journey/integration)


---

# FinCard Virtual

Virtual card issuance, management, and crypto wallet integration


URL: /paas/fincard-virtual



# FinCard Virtual

FinCard Virtual provides comprehensive card issuance and management APIs, supporting virtual cards, physical cards, shared (budget) cards, and gift cards across Visa, MasterCard, and Discover networks.

<Info>
  **Base URL:** `https://sandbox.finhub.cloud/api/v2.1/fincard/virtual`
</Info>

<Note>
  All endpoints use `POST` method with JSON body. The response envelope is always `{ "success": bool, "code": int, "msg": string, "data": ... }`.
</Note>

---

## API Groups

<CardGroup cols={2}>
  <Card title="Common" icon="globe" href="/paas/fincard-virtual/common">
    Reference data: countries, cities, mobile codes, file uploads, work orders
  </Card>
  <Card title="Accounts" icon="wallet" href="/paas/fincard-virtual/accounts">
    Merchant accounts, balances, ledger transactions, fund transfers
  </Card>
  <Card title="Crypto Wallet" icon="bitcoin" href="/paas/fincard-virtual/wallet">
    Coin list, wallet addresses, crypto deposit/withdrawal transactions
  </Card>
  <Card title="Cards" icon="credit-card" href="/paas/fincard-virtual/cards">
    Card types, issuance, deposit/withdraw, freeze/unfreeze, cancel, transactions
  </Card>
  <Card title="Card Holders" icon="id-card" href="/paas/fincard-virtual/card-holders">
    KYC cardholder creation (B2B/B2C), update, approval status, listing
  </Card>
  <Card title="Webhooks" icon="bell" href="/paas/fincard-virtual/webhooks">
    Real-time event notifications for card operations and transactions
  </Card>
  <Card title="Work Orders" icon="clipboard-list" href="/paas/fincard-virtual/api/work-list">
    Work order management and submission
  </Card>
</CardGroup>

---

## Card Issuance Flows

<CardGroup cols={2}>
  <Card title="Issuance Processes" icon="diagram-project" href="/paas/fincard-virtual/card-issuance-flows">
    Step-by-step flows for Virtual, Physical, Shared, and Gift cards
  </Card>
</CardGroup>

---

## Quick Start: Issue a Virtual Card

### Step 1: Get Available Card Types
```bash
POST /api/v2.1/fincard/virtual/card/v2/cardTypes
Body: {}
```

### Step 2: Create Cardholder (if required)
```bash
POST /api/v2.1/fincard/virtual/card/holder/v2/create
Body: { "cardHolderModel": "B2B", "cardTypeId": 111001, ... }
```

### Step 3: Create Card
```bash
POST /api/v2.1/fincard/virtual/card/v2/openCard
Body: { "merchantOrderNo": "...", "cardTypeId": 111001, "amount": 100 }
```

### Step 4: Query Card Info
```bash
POST /api/v2.1/fincard/virtual/card/info
Body: { "cardNo": "FC-XXXX" }
```

### Step 5: Get Sensitive Info (Card Number, CVV, Expiry)
```bash
POST /api/v2.1/fincard/virtual/card/info/sensitive
Body: { "cardNo": "FC-XXXX" }
```

---

## Endpoint Summary

| Group | Endpoints | Description |
|-------|-----------|-------------|
| **Common** | 7 | Reference data, file upload, work orders |
| **Accounts** | 8 | Account CRUD, balances, ledger, transfers |
| **Crypto Wallet** | 4 | Coins, addresses, deposit/withdraw history |
| **Cards** | 21 | Full card lifecycle + 5 transaction query types |
| **Card Holders** | 6 | KYC holder management (B2B/B2C) |
| **Webhooks** | 1 | Event callback receiver |
| **Work Orders** | 2 | Work order management |
| **Total** | **49** | |

---

## Authentication

All requests require standard FinHub authentication headers:

| Header | Required | Description |
|--------|----------|-------------|
| `X-Tenant-ID` | Yes | Tenant identifier |
| `Authorization` | Yes | Bearer JWT token |
| `Content-Type` | Yes | `application/json` |

---

## Environments

| Environment | Base URL |
|-------------|----------|
| **Sandbox** | `https://sandbox.finhub.cloud/api/v2.1/fincard/virtual` |
| **Integration** | `https://api-beta.finhub.cloud/api/v2.1/fincard/virtual` |
| **Production** | `https://api.finhub.cloud/api/v2.1/fincard/virtual` |


---

# Authentication & Headers

How to authenticate and which headers are required for every FinCard Virtual API call


URL: /paas/fincard-virtual/authentication



# Authentication & Headers

Every FinCard Virtual API request must carry a valid **Bearer JWT** token and a set of **required context headers**. Missing any of them returns `HTTP 400 Missing required header(s)`.

---

## Step 1 — Obtain a Session Token

Call the login endpoint once to obtain a short-lived JWT. Pass it as `Authorization: Bearer <token>` in all subsequent requests.

```bash
POST /api/auth/login
Content-Type: application/json
X-Tenant-ID: <your-tenant-id>
X-Forwarded-For: <client-ip>
X-Forwarded-From: <your-app-name>
platform: web
deviceId: <device-or-session-id>
```

**Request body:**

```json
{
  "email": "user@your-domain.com",
  "password": "your-password",
  "tenantId": "your-tenant-id"
}
```

**Response:**

```json
{
  "accessToken": "eyJ0eXAiOiJKV1Qi...",
  "tokenType": "Bearer",
  "expiresIn": 3600
}
```

<Note>
  `expiresIn` is in seconds. Tokens are valid for **1 hour**. Re-authenticate before expiry — there is no refresh token endpoint.
</Note>

---

## Step 2 — Include Headers on Every Request

All 46 FinCard Virtual endpoints require the following headers:

| Header | Required | Example | Description |
|--------|----------|---------|-------------|
| `Authorization` | **Yes** | `Bearer eyJ0eXAi...` | JWT from login |
| `Content-Type` | **Yes** | `application/json` | Always JSON |
| `X-Tenant-ID` | **Yes** | `tenant_acme` | Your tenant identifier |
| `X-Forwarded-For` | **Yes** | `203.0.113.42` | End-user IP address |
| `X-Forwarded-From` | **Yes** | `my-backend-service` | Originating service name |
| `platform` | **Yes** | `web` \| `ios` \| `android` | Client platform |
| `deviceId` | **Yes** | `device-abc-123` | Unique device or session ID |
| `User-Agent` | No | `MyApp/2.1` | Client user-agent (recommended) |

<Warning>
  `X-Forwarded-For`, `X-Forwarded-From`, `platform`, and `deviceId` are validated server-side. A `400 Missing required header(s)` error is returned if any are absent.
</Warning>

---

## Complete Request Example

```bash
curl -X POST https://sandbox.finhub.cloud/api/v2.1/fincard/virtual/card/info \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1Qi..." \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: tenant_acme" \
  -H "X-Forwarded-For: 203.0.113.42" \
  -H "X-Forwarded-From: my-backend" \
  -H "platform: web" \
  -H "deviceId: device-abc-123" \
  -d '{ "cardNo": "FC-XXXX-XXXX" }'
```

---

## Response Envelope

Every response — success or error — is wrapped in the same envelope:

```json
{
  "success": true,
  "code": 200,
  "msg": "Success",
  "data": { ... }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `success` | Boolean | `true` = operation succeeded |
| `code` | Integer | `200` = OK, `-1` = business error, `401` = unauthorized, `500` = server error |
| `msg` | String | Human-readable status message |
| `data` | Object \| Array | Response payload (varies per endpoint) |

<Info>
  Even HTTP `200` responses can have `"success": false` for business-level errors (e.g. card not found, insufficient balance). Always check `success` **and** `code`.
</Info>

---

## Error Reference

| HTTP | `code` | Cause | Action |
|------|--------|-------|--------|
| 400 | 500 | Missing required header | Add all required headers |
| 401 | 401 | Missing or expired token | Re-authenticate via `/api/auth/login` |
| 401 | 401 | Empty authorization token | Include `Authorization: Bearer <token>` |
| 200 | -1 | Business error (e.g. card not found) | Check `msg` for details |
| 200 | 200 | Success | Process `data` payload |

---

## SDK / Script Example (PowerShell)

```powershell
# 1. Login
$loginBody = @{
    email    = "user@domain.com"
    password = "your-password"
    tenantId = "your-tenant-id"
} | ConvertTo-Json -Compress

$loginResp = Invoke-RestMethod -Uri "https://sandbox.finhub.cloud/api/auth/login" `
    -Method Post `
    -Headers @{
        "Content-Type"     = "application/json"
        "X-Tenant-ID"      = "your-tenant-id"
        "X-Forwarded-For"  = "127.0.0.1"
        "X-Forwarded-From" = "my-script"
        "platform"         = "web"
        "deviceId"         = "script-device-001"
    } `
    -Body $loginBody

# 2. Use token in all subsequent calls
$headers = @{
    "Authorization"    = "Bearer $($loginResp.accessToken)"
    "Content-Type"     = "application/json"
    "X-Tenant-ID"      = "your-tenant-id"
    "X-Forwarded-For"  = "127.0.0.1"
    "X-Forwarded-From" = "my-script"
    "platform"         = "web"
    "deviceId"         = "script-device-001"
}

# 3. Call any endpoint
$cardInfo = Invoke-RestMethod -Uri "https://sandbox.finhub.cloud/api/v2.1/fincard/virtual/card/info" `
    -Method Post -Headers $headers -Body '{"cardNo":"FC-XXXX-XXXX"}'
```


---

# Login (Create Session)


URL: /paas/fincard-virtual/api/auth-login




---

# Card Issuance Flows

Step-by-step processes for Virtual, Physical, Shared, and Gift card issuance


URL: /paas/fincard-virtual/card-issuance-flows



# Card Issuance Flows

## Introduction

FinCard Virtual is a card-issuing service built on the FinCard platform. It enables tenants to programmatically issue, manage, and monitor prepaid cards — virtual or physical — for their end customers (B2B or B2C).

All endpoints are available for interactive testing at **`https://sandbox.finhub.cloud`**. Each endpoint page includes a **Try It** panel where you can send live requests against the sandbox.

---

### Architecture Overview

```
Your Application
      │
      ▼
FinHub BFF  (/api/v2.1/fincard/virtual/...)
      │
      ├── Playground mode  →  in-memory JPA/MariaDB (no external calls)
      └── Integration mode →  FinCard Virtual Production API (RSA-signed)
```

The BFF operates in one of two modes based on tenant configuration:

| Mode | Description | Use case |
|------|-------------|----------|
| **Playground** | Fully simulated — all data stored in sandbox DB | Development & testing |
| **Integration** | Live calls to FinCard Virtual API (RSA-signed) | Production |

---

### Prerequisites

Before issuing any card, ensure:

1. **Tenant credentials** — valid `X-Tenant-ID` header on every request
2. **Account funded** — the tenant's WALLET account has sufficient balance
3. **Card BINs available** — call `POST /card/v2/cardTypes` to discover available BINs and their requirements
4. **Cardholder created** (if `needCardHolder: true` on the BIN) — cardholder must reach `status: pass_audit` before a card can be linked

<Note>
  All API bodies are raw JSON strings (`Content-Type: application/json`). The BFF forwards them directly to FinCard Virtual after signature verification.
</Note>

---

### Choose Your Card Type

```
Start
  │
  ├─► Need multiple cards sharing a pool? ──► Shared Card (BUDGET_CARD)
  │
  ├─► Physical card issued offline? ────────► Physical Card
  │
  ├─► Redemption URL only (no card number)? ► Gift Card
  │
  └─► Standard virtual prepaid? ────────────► Virtual Card (PREPAID_CARD)
```

| Card Type | BIN Mode | BIN Type | Category |
|-----------|----------|----------|----------|
| **Virtual** | `PREPAID_CARD` | `Virtual` | `PURCHASE` / `SUBSCRIPTION` |
| **Physical** | `PREPAID_CARD` | `Physical` | `PHYSICAL` |
| **Shared** | `BUDGET_CARD` | `Virtual` | `PURCHASE` |
| **Gift** | `PREPAID_CARD` | `Virtual` | `GIFT` |

---

### Common Headers

Every request requires:

| Header | Description |
|--------|-------------|
| `X-Tenant-ID` | Your tenant identifier |
| `Content-Type` | `application/json` |

---

Four card issuance processes, each with a distinct flow. All share the same API endpoints but differ in required steps and configuration.

---

## 1. Virtual Card (PREPAID_CARD)

The standard flow for issuing virtual prepaid cards.

```mermaid
flowchart TD
    S(( )) --> GetCardBIN[GetCardBIN]
    GetCardBIN -->|needCardHolder?| CheckHolder{CheckHolder}
    CheckHolder -->|Yes| CreateHolder[CreateHolder]
    CheckHolder -->|No| CreateCard[CreateCard]
    CreateHolder --> WaitApproval[WaitApproval]
    WaitApproval -->|Approved| CreateCard
    CreateCard --> QueryInfo[QueryInfo]
    QueryInfo --> GetSensitive[GetSensitive]
    GetSensitive --> E([Ready to use])
```

| Step | API | Description |
|------|-----|-------------|
| 1 | `POST /card/v2/cardTypes` | Get available card BINs. Filter `mode=PREPAID_CARD`, `type=Virtual` |
| 2 | Check `needCardHolder` | If `true`, create cardholder first |
| 3 | `POST /card/holder/v2/create` | Create cardholder (B2B or B2C based on `metadata.cardHolderModel`) |
| 4 | `POST /card/v2/openCard` | Create card with `holderId` + initial `amount` |
| 5 | `POST /card/info` | Query card info (status, balance) |
| 6 | `POST /card/info/sensitive` | Get encrypted card number, CVV, expiry |

<Note>
  Monitor cardholder approval via [Cardholder List](/paas/fincard-virtual/card-holders) or [Webhooks](/paas/fincard-virtual/webhooks). Proceed to card creation only when `status=pass_audit`.
</Note>

---

## 2. Physical Card

Physical cards are purchased offline in bulk, then assigned and activated via API.

```mermaid
flowchart TD
    S(( )) --> PurchaseOffline[PurchaseOffline]
    PurchaseOffline --> GetCardBIN[GetCardBIN]
    GetCardBIN --> CreateHolder[CreateHolder]
    CreateHolder --> AssignCard[AssignCard]
    AssignCard -->|webhook| ReceiveCode[ReceiveCode]
    ReceiveCode --> ActivateCard[ActivateCard]
    ActivateCard --> GetSensitive[GetSensitive]
    GetSensitive --> E([Ready to use])
```

| Step | API | Description |
|------|-----|-------------|
| 1 | — | Customer purchases physical cards offline from BD |
| 2 | `POST /card/v2/cardTypes` | Get BIN config. Filter `type=Physical` |
| 3 | `POST /card/holder/v2/create` | Create cardholder (if `needCardHolder=true`) |
| 4 | `POST /card/v2/openCard` | Create card with `cardNumber` (from physical card) |
| 5 | Webhook: `activation_code` | Receive activation code via webhook or cardholder email |
| 6 | `POST /card/activate` | Activate with `pin` (6 digits) + `activeCode` |
| 7 | `POST /card/info/sensitive` | Get card number, CVV, expiry (available after activation) |

<Warning>
  Before activation, `card/info/sensitive` returns limited data. Full card details (number, CVV, expiry) are only available after successful activation.
</Warning>

---

## 3. Shared Card (BUDGET_CARD)

Multiple cards share the same wallet. Deposit = allocate credit limit, Withdraw = reduce credit limit.

```mermaid
flowchart TD
    S(( )) --> GetCardBIN[GetCardBIN]
    GetCardBIN --> CreateHolder[CreateHolder]
    CreateHolder --> CreateAccount[CreateAccount]
    CreateAccount --> FundAccount[FundAccount]
    FundAccount --> CreateCard1[CreateCard 1]
    FundAccount --> CreateCard2[CreateCard 2]
    CreateCard1 --> AllocateCredit[AllocateCredit]
    CreateCard2 --> AllocateCredit
    AllocateCredit --> E([Cards ready])
```

| Step | API | Description |
|------|-----|-------------|
| 1 | `POST /card/v2/cardTypes` | Get BIN config. Filter `mode=BUDGET_CARD` |
| 2 | `POST /card/holder/v2/create` | Create cardholder (if needed) |
| 3 | `POST /account/create` | Create MARGIN account for shared pool |
| 4 | `POST /account/transfer` | Fund MARGIN from WALLET |
| 5-6 | `POST /card/v2/openCard` | Create cards with `accountId` pointing to shared account |
| 7 | `POST /card/deposit` | Top-up = allocate credit limit to each card |

<Note>
  - **Deposit** on a shared card = allocating credit from the shared pool
  - **Withdraw** on a shared card = reducing the credit limit
  - All cards share the same underlying MARGIN account balance
</Note>

---

## 4. Gift Card

Gift cards return only a redemption URL. No card number/CVV/expiry. No deposit/withdraw/freeze/unfreeze.

```mermaid
flowchart TD
    S(( )) --> GetCardBIN[GetCardBIN]
    GetCardBIN --> CreateHolder[CreateHolder]
    CreateHolder --> CreateCard[CreateCard]
    CreateCard --> GetSensitive[GetSensitive]
    GetSensitive --> E([Share URL with recipient])
```

| Step | API | Description |
|------|-----|-------------|
| 1 | `POST /card/v2/cardTypes` | Get BIN config. Filter `category=GIFT` |
| 2 | `POST /card/holder/v2/create` | Create cardholder (if needed) |
| 3 | `POST /card/v2/openCard` | Create gift card with initial amount |
| 4 | `POST /card/info/sensitive` | Returns only `activateUrl` (redemption page) |

### Gift Card Restrictions

| Feature | Supported |
|---------|-----------|
| Card number / CVV / Expiry | **No** — only `activateUrl` |
| Deposit | **No** |
| Withdraw | **No** |
| Freeze / UnFreeze | **No** |
| Cancel | Yes |
| Card Info | Yes (basic status only) |

---

## Flow Comparison

| Feature | Virtual | Physical | Shared | Gift |
|---------|---------|----------|--------|------|
| **Mode** | PREPAID_CARD | PREPAID_CARD | BUDGET_CARD | PREPAID_CARD |
| **Type** | Virtual | Physical | Virtual | Virtual |
| **Category** | PURCHASE/SUBSCRIPTION | PHYSICAL | PURCHASE | GIFT |
| **Cardholder** | Optional | Optional | Optional | Optional |
| **Card Number Input** | No | Yes (offline) | No | No |
| **Activation** | Auto | Manual (PIN + code) | Auto | Auto |
| **Shared Account** | No | No | Yes (MARGIN) | No |
| **Deposit/Withdraw** | Yes | Yes | Yes (credit allocation) | No |
| **Freeze/UnFreeze** | Yes | Yes | Yes | No |
| **Sensitive Info** | Full | After activation | Full | Only `activateUrl` |


---

# Common

Reference data, file uploads, and work order management


URL: /paas/fincard-virtual/common



# Common APIs

Reference data endpoints for countries, cities, mobile codes, plus file upload and work order management.

<Info>
  **Base URL:** `POST /api/v2.1/fincard/virtual/...`
</Info>

---

## Country/Region List

Returns all supported countries and regions with ISO codes.

```bash
POST /api/v2.1/fincard/virtual/common/region
```

**Request:** `{}` (empty body)

**Response `data[]`:**

| Field | Type | Description |
|-------|------|-------------|
| `code` | String | ISO 3166-1 alpha-2 (e.g. `US`) |
| `standardCode` | String | ISO 3166-1 alpha-3 (e.g. `USA`) |
| `name` | String | Country/region name |

<Accordion title="Example Response">
```json
{
  "success": true,
  "code": 200,
  "msg": "Success",
  "data": [
    { "code": "AU", "standardCode": "AUS", "name": "Australia" },
    { "code": "BD", "standardCode": "BGD", "name": "Bangladesh" }
  ]
}
```
</Accordion>

<Warning>
  This data changes very infrequently. **Cache it locally** to minimize API calls.
</Warning>

---

## City List

Returns cities filtered by country/region code.

```bash
POST /api/v2.1/fincard/virtual/common/city
```

**Request:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `regionCode` | String | No | ISO 3166-1 alpha-2 filter |

**Response `data[]`:**

| Field | Type | Description |
|-------|------|-------------|
| `code` | String | City code |
| `name` | String | City name |
| `country` | String | ISO 3166-1 alpha-2 |

<Accordion title="Example Response">
```json
{
  "success": true,
  "code": 200,
  "msg": "Success",
  "data": [
    { "code": "AU_01", "name": "test", "country": "AU" }
  ]
}
```
</Accordion>

---

## City List v2 (Hierarchical)

Returns cities with province/state/city hierarchy (two levels).

```bash
POST /api/v2.1/fincard/virtual/common/v2/city
```

**Request:** Same as City List

**Response `data[]`:**

| Field | Type | Description |
|-------|------|-------------|
| `code` | String | Province/state code |
| `name` | String | Province/state name |
| `country` | String | ISO 3166-1 alpha-2 |
| `countryStandardCode` | String | ISO 3166-1 alpha-3 |
| `parentCode` | String | Parent code (`"0"` for root) |
| `children[]` | Array | Child cities (same structure recursively) |

<Accordion title="Example Response">
```json
{
  "success": true,
  "code": 200,
  "msg": "Success",
  "data": [
    {
      "code": "AU-ACT",
      "name": "Australian Capital Territory",
      "parentCode": "0",
      "country": "AU",
      "countryStandardCode": "AUS",
      "children": [
        {
          "code": "AU-ACT-80100",
          "name": "Australian Capital Territory (Canberra)",
          "parentCode": "AU-ACT",
          "country": "AU",
          "countryStandardCode": "AUS",
          "children": []
        }
      ]
    }
  ]
}
```
</Accordion>

---

## Mobile Code List

Returns mobile area codes by region.

```bash
POST /api/v2.1/fincard/virtual/common/mobileAreaCode
```

**Request:** `{}` (empty body)

**Response `data[]`:**

| Field | Type | Description |
|-------|------|-------------|
| `code` | String | Mobile code (e.g. `+1`) |
| `name` | String | Region name (e.g. `Canada`) |
| `areaCode` | String | ISO 3166-1 alpha-2 (e.g. `CA`) |
| `language` | String | `zh_CN` or `en_US` |
| `enableGlobalTransfer` | Boolean | Is global transfer available |

<Accordion title="Example Response">
```json
{
  "success": true,
  "code": 200,
  "msg": "Success",
  "data": [
    { "code": "+1", "name": "Canada", "areaCode": "CA", "language": "en_US", "enableGlobalTransfer": true }
  ]
}
```
</Accordion>

---

## Upload File

Upload a file for use in cardholder KYC or work orders. Supports **jpg, png, pdf** formats, max **2MB**.

```bash
POST /api/v2.1/fincard/virtual/common/file/upload
Content-Type: multipart/form-data
```

**Request (multipart):**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | String | Yes | Use `card` |
| `file` | File | Yes | jpg/png/pdf, max 2MB |

**Response `data`:**

| Field | Type | Description |
|-------|------|-------------|
| `fileId` | String | UUID reference for the uploaded file |

<Accordion title="Example Response">
```json
{
  "success": true,
  "code": 200,
  "msg": "Success",
  "data": {
    "fileId": "c7bf3c1b-25d1-4b75-b519-1e6bf383d0a7"
  }
}
```
</Accordion>

<Note>
  Use the returned `fileId` when creating cardholders (B2C model requires ID document uploads).
</Note>

---

## Submit Work Order

Submit a work order for card activation or support requests.

```bash
POST /api/v2.1/fincard/virtual/work/submit
```

**Request:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `merchantOrderNo` | String | Yes | Client transaction ID. Length `[20..40]` |
| `title` | String | Yes | Title. Length `[1..255]` |
| `target` | String | Yes | Target. Length `[1..255]`. Card number for activation |
| `content` | String | No | Content. Length `[0..1000]` |
| `files` | List\<String\> | No | File IDs from upload endpoint |
| `tradeType` | String | Yes | `CARD_ACTIVE` or `OTHER` |

**Response `data`:**

| Field | Type | Description |
|-------|------|-------------|
| `merchantOrderNo` | String | Client transaction ID |
| `orderNo` | String | Platform transaction ID |
| `title` | String | Title |
| `target` | String | Target |
| `content` | String | Content |
| `tradeType` | String | `CARD_ACTIVE` / `OTHER` |
| `tradeStatus` | String | `wait_process` / `processing` / `success` / `fail` |
| `remark` | String | Remark |
| `createTime` | Long | Millisecond timestamp |
| `updateTime` | Long | Millisecond timestamp |

<Accordion title="Example Response">
```json
{
  "merchantOrderNo": "13243897979979797999008085",
  "orderNo": "WORK-2025080719534",
  "title": "ApplePay",
  "target": "5533700042831234",
  "content": "Active",
  "tradeType": "CARD_ACTIVE",
  "tradeStatus": "processing",
  "remark": null,
  "createTime": 1754607865000,
  "updateTime": 1754648044000
}
```
</Accordion>

---

## Work Order List

Query work orders with optional filters and pagination.

```bash
POST /api/v2.1/fincard/virtual/work/list
```

**Request:** All fields optional (used as filters):

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `merchantOrderNo` | String | No | Filter by client tx ID |
| `orderNo` | String | No | Filter by platform tx ID |
| `target` | String | No | Filter by target |
| `tradeType` | String | No | `CARD_ACTIVE` / `OTHER` |
| `tradeStatus` | String | No | `wait_process` / `processing` / `success` / `fail` |

**Response `data`:** `{ total: Long, records: [...] }` — records have same shape as Submit response plus `description`.


---

# Country/Region List


URL: /paas/fincard-virtual/api/common-region




---

# City List


URL: /paas/fincard-virtual/api/common-city




---

# City List v2


URL: /paas/fincard-virtual/api/common-city-v2




---

# Mobile Code List


URL: /paas/fincard-virtual/api/common-mobile




---

# Upload File


URL: /paas/fincard-virtual/api/common-upload




---

# Accounts

Merchant account management, balances, ledger transactions, and fund transfers


URL: /paas/fincard-virtual/accounts



# Account APIs

Manage merchant accounts (WALLET and MARGIN types), query balances, view ledger transactions, and execute fund transfers.

<Info>
  **Base URL:** `POST /api/v2.1/fincard/virtual/account/...`
</Info>

---

## Assets (Account Info)

Returns all merchant accounts with balances.

```bash
POST /api/v2.1/fincard/virtual/account/info
```

**Request:** `{}` (empty body)

**Response `data[]`:**

| Field | Type | Description |
|-------|------|-------------|
| `accountId` | String | Account ID |
| `accountName` | String | Account name |
| `accountType` | String | `WALLET` or `MARGIN` |
| `currency` | String | Currency (e.g. `USD`) |
| `totalBalance` | BigDecimal | Total balance |
| `availableBalance` | BigDecimal | Available balance |
| `frozenBalance` | BigDecimal | Frozen balance |
| `digital` | Long | Decimal places for display |

<Accordion title="Example Response">
```json
{
  "success": true,
  "code": 200,
  "msg": "Success",
  "data": [
    {
      "accountId": "19847563867367666",
      "accountName": "wallet9023",
      "accountType": "WALLET",
      "currency": "USD",
      "totalBalance": 100,
      "availableBalance": 100,
      "frozenBalance": 0,
      "digital": 2
    }
  ]
}
```
</Accordion>

---

## Account List

Paginated list of accounts with optional type filter.

```bash
POST /api/v2.1/fincard/virtual/account/list
```

**Request:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `accountId` | Long | No | Filter by account ID |
| `type` | String | No | `WALLET` or `MARGIN` |
| `pageNum` | Integer | Yes | Page number (default 1) |
| `pageSize` | Integer | Yes | Page size (default 10, max 10) |

**Response `data`:** `{ total: Long, records: [...] }` — records same shape as Account Info.

---

## Single Account Query

Query a single account by ID.

```bash
POST /api/v2.1/fincard/virtual/account/single/query
```

**Request:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `accountId` | Long | Yes | Account ID |

**Response `data[]`:** Same shape as Account Info.

---

## Ledger Transactions

Query financial transaction history for an account.

```bash
POST /api/v2.1/fincard/virtual/account/transaction
```

**Request:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `pageNum` | Integer | Yes | Page number (default 1) |
| `pageSize` | Integer | Yes | Page size (default 10, max 100) |
| `orderNo` | String | No | Filter by transaction ID |
| `accountId` | Long | No | Filter by account |
| `bizType` | String | No | Transaction type (see below) |
| `startTime` | Long | No | Start time (ms). Max 30-day range |
| `endTime` | Long | No | End time (ms) |

**Transaction Types (`bizType`):**

| Value | Description |
|-------|-------------|
| `chain_deposit` | Wallet chain deposit |
| `chain_withdraw` | Wallet chain withdrawal |
| `card_purchase` | Card purchase (create fee + deposit) |
| `card_deposit` | Card deposit |
| `card_withdraw` | Card withdraw |
| `card_cancel` | Card cancel |
| `card_auth_fee_patch` | Card authorization fee |
| `card_auth_cross_board_patch` | Card cross-border fee |
| `gt_transfer` | Global transfer |
| `gt_transfer_refund` | Global transfer refund |
| `fixed` | Adjustment |
| `card_overdraft_statement` | Card overdraft bill |

**Response `data`:** `{ total, records[] }`

| Field | Type | Description |
|-------|------|-------------|
| `txId` | Long | Internal transaction ID |
| `accountId` | String | Account ID |
| `amount` | BigDecimal | Amount |
| `beforeBalance` | BigDecimal | Balance before transaction |
| `afterBalance` | BigDecimal | Balance after transaction |
| `orderNo` | String | Transaction ID |
| `bizType` | String | Transaction type |
| `direction` | String | `IN` or `OUT` |
| `remark` | String | Remark |
| `createTime` | Long | Millisecond timestamp |

<Accordion title="Example Response">
```json
{
  "success": true,
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "total": 34,
    "records": [
      {
        "txId": 517581,
        "accountId": "1979009257233215490",
        "currency": "USD",
        "amount": "4.08",
        "beforeBalance": "99327.04375",
        "afterBalance": "99322.96375",
        "orderNo": "C2C_UZS_2025122307584616966",
        "bizType": "gt_transfer",
        "direction": "OUT",
        "remark": "Global transfer",
        "createTime": 1766480100874
      }
    ]
  }
}
```
</Accordion>

---

## Create Shared Account

Create a new MARGIN account for shared card mode.

```bash
POST /api/v2.1/fincard/virtual/account/create
```

**Request:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `accountName` | String | Yes | Account name |

**Response `data[]`:** The created account (same shape as Account Info).

---

## Fund Transfer

Transfer or collect funds between accounts.

```bash
POST /api/v2.1/fincard/virtual/account/transfer
```

**Request:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `type` | String | Yes | `TRANSFER` or `COLLECTION` |
| `merchantOrderNo` | String | Yes | Client transaction ID `[20..40]` |
| `amount` | BigDecimal | Yes | Amount |
| `payerAccountId` | Long | Yes | Payer account (typically WALLET) |
| `payeeAccountId` | Long | Yes | Payee account (typically MARGIN) |
| `remark` | String | No | Remark |

**Response `data`:** `true` (boolean)

<Note>
  Use this to fund a MARGIN account before creating shared (BUDGET_CARD) cards linked to it.
</Note>

---

## Wallet Deposit (Deprecated)

<Warning>
  **Deprecated.** Use the [Wallet v2 APIs](/paas/fincard-virtual/wallet) instead.
</Warning>

Create a wallet deposit order. Returns deposit address and amount.

```bash
POST /api/v2.1/fincard/virtual/account/walletDeposit
```

**Request:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `chain` | String | No | `TRC20` (default) or `BEP20` |
| `amount` | BigDecimal | Yes | Deposit amount |

**Response `data`:**

| Field | Type | Description |
|-------|------|-------------|
| `orderNo` | String | Transaction ID |
| `userInputDepositAmount` | BigDecimal | Input amount |
| `actualDepositAmount` | BigDecimal | Actual amount (with decimal adjustment) |
| `currency` | String | `USDT` |
| `chain` | String | Network chain |
| `toAddress` | String | Wallet deposit address |
| `createTime` | Long | Order time (ms) |
| `expireSecond` | Long | Validity period (seconds) |

---

## Wallet Deposit Transactions (Deprecated)

<Warning>
  **Deprecated.** Use the [Wallet v2 Transaction History](/paas/fincard-virtual/wallet) instead.
</Warning>

```bash
POST /api/v2.1/fincard/virtual/account/walletDepositTransaction
```

Paginated query for wallet deposit transactions. Response: `{ total, records[] }`.


---

# Create Margin Account


URL: /paas/fincard-virtual/api/account-create




---

# Account List


URL: /paas/fincard-virtual/api/account-list




---

# Account Single Query


URL: /paas/fincard-virtual/api/account-query




---

# Account Assets


URL: /paas/fincard-virtual/api/account-info




---

# Ledger Transactions


URL: /paas/fincard-virtual/api/account-transaction




---

# Fund Transfer


URL: /paas/fincard-virtual/api/account-transfer




---

# Wallet Deposit


URL: /paas/fincard-virtual/api/account-wallet-deposit




---

# Wallet Deposit Transactions


URL: /paas/fincard-virtual/api/account-wallet-deposit-tx




---

# Crypto Wallet

Cryptocurrency wallet addresses, supported coins, and deposit/withdrawal transactions


URL: /paas/fincard-virtual/wallet



# Crypto Wallet APIs (v2)

Manage cryptocurrency wallet addresses for funding your merchant account. Supports USDT on TRC20 and BEP20 chains.

<Info>
  **Base URL:** `POST /api/v2.1/fincard/virtual/wallet/v2/...`
</Info>

---

## Coin List

Query all supported coins and blockchain networks.

```bash
POST /api/v2.1/fincard/virtual/wallet/v2/coins
```

**Request:** `{}` (empty body)

**Response `data[]`:**

| Field | Type | Description |
|-------|------|-------------|
| `coinKey` | String | Unique coin identifier (e.g. `USDT_TRC20`) |
| `chain` | String | Blockchain network (e.g. `TRC20`, `BEP20`) |
| `coinFullName` | String | Full name (e.g. `Tether`) |
| `coinName` | String | Short name (e.g. `USDT`) |
| `showCoinDecimal` | Integer | Display decimal places |
| `coinDecimal` | Integer | Transaction decimal places |
| `blockChainShowName` | String | Display name (e.g. `Tron (TRC20)`) |
| `browser` | String | Blockchain explorer URL template for addresses |
| `txRefUrl` | String | Blockchain explorer URL template for transactions |
| `contractAddress` | String | Smart contract address |
| `enableDeposit` | Boolean | Deposits enabled |
| `enableWithdraw` | Boolean | Withdrawals enabled |
| `confirmations` | Integer | Required block confirmations |
| `enabled` | Boolean | Coin is active |

<Accordion title="Example Response">
```json
{
  "success": true,
  "code": 200,
  "msg": "SUCCESS",
  "data": [
    {
      "coinKey": "USDT_TRC20",
      "chain": "TRC20",
      "coinFullName": "Tether",
      "coinName": "USDT",
      "showCoinDecimal": 6,
      "coinDecimal": 6,
      "blockChainShowName": "Tron (TRC20)",
      "browser": "https://tronscan.org/#/address/{address}",
      "txRefUrl": "https://tronscan.org/#/transaction/{txHash}",
      "contractAddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
      "enableDeposit": true,
      "enableWithdraw": true,
      "confirmations": 38,
      "enabled": true
    }
  ]
}
```
</Accordion>

---

## Create Wallet Address

Generate a new deposit address for a specific coin and chain.

```bash
POST /api/v2.1/fincard/virtual/wallet/v2/create
```

**Request:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `coinKey` | String | Yes | Coin key from Coin List (must have `enabled=true`) |

**Response `data`:**

| Field | Type | Description |
|-------|------|-------------|
| `coinKey` | String | Coin key |
| `chain` | String | Blockchain network |
| `coinName` | String | Coin name |
| `address` | String | Generated deposit address |

<Accordion title="Example Response">
```json
{
  "success": true,
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "coinKey": "USDT_BEP20",
    "chain": "BEP20",
    "coinName": "USDT",
    "address": "0xAAac5f0d8133424d86D5Ef3f170E0420e561125f"
  }
}
```
</Accordion>

<Note>
  You can also generate wallet addresses from the dashboard. Each `coinKey` has one address per merchant.
</Note>

---

## Wallet Address List

Query all generated wallet deposit addresses.

```bash
POST /api/v2.1/fincard/virtual/wallet/v2/addressList
```

**Request:** `{}` (empty body)

**Response `data[]`:** Same shape as Create Wallet Address response.

---

## Wallet Transaction History

Query crypto deposit and withdrawal transaction history.

```bash
POST /api/v2.1/fincard/virtual/wallet/v2/transaction
```

**Request:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `pageNum` | Long | Yes | Page number (default 1) |
| `pageSize` | Long | Yes | Page size (default 10, max 100) |
| `coinKey` | String | No | Filter by coin key |
| `coinName` | String | No | Filter by coin name |
| `txHash` | String | No | Filter by on-chain tx hash |
| `sourceAddress` | String | No | Filter by source address |
| `destinationAddress` | String | No | Filter by destination address |
| `orderNo` | String | No | Filter by platform tx ID |
| `type` | String | No | `DEPOSIT` or `WITHDRAW` |
| `status` | String | No | `wait_process` / `processing` / `success` / `fail` |
| `startTime` | Long | No | Start time (ms). Max 90-day range |
| `endTime` | Long | No | End time (ms) |

**Response `data`:** `{ total, records[] }`

| Field | Type | Description |
|-------|------|-------------|
| `orderNo` | String | Platform transaction ID |
| `coinKey` | String | Coin key |
| `coinName` | String | Coin name |
| `block` | Integer | Block height |
| `sourceAddress` | String | Source address |
| `destinationAddress` | String | Destination address |
| `txHash` | String | On-chain transaction hash |
| `txAmount` | BigDecimal | On-chain amount |
| `transactionTime` | Long | Chain transaction time (ms) |
| `confirmTime` | Long | Chain confirmation time (ms) |
| `feeRate` | BigDecimal | Platform fee rate (`1` = 1%) |
| `fee` | BigDecimal | Platform fee amount |
| `fixedFee` | BigDecimal | Platform fixed fee |
| `receivedAmount` | BigDecimal | Net received amount |
| `receivedCurrency` | String | Received currency (e.g. `USD`) |
| `type` | String | `DEPOSIT` or `WITHDRAW` |
| `status` | String | `wait_process` / `processing` / `success` / `fail` |
| `message` | String | Remark |
| `createTime` | Long | Order create time (ms) |
| `updateTime` | Long | Order update time (ms) |

<Accordion title="Example Response">
```json
{
  "success": true,
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "total": 5,
    "records": [
      {
        "orderNo": "CND2031235349498847232",
        "coinKey": "USDT_TRC20",
        "block": 80817428,
        "sourceAddress": "TK4ykR48cQQoyFcZ5N4xZCbsBaHcg6n3gJ",
        "destinationAddress": "TReJ9YfvmpPTXuq3kzQneXDco1fQprqZ9v",
        "txHash": "1c19a9635e8c11c6b7be0e402017e81e64e9f7f1ad1a10e1ea1304955745b434",
        "coinName": "USDT",
        "txAmount": "9",
        "feeRate": "1.5",
        "fee": "0.135",
        "fixedFee": "0",
        "receivedAmount": "8.86",
        "receivedCurrency": "USD",
        "type": "DEPOSIT",
        "status": "success",
        "createTime": 1773119220000,
        "updateTime": 1773119220000
      }
    ]
  }
}
```
</Accordion>

<Warning>
  If `status=fail`, it is **not necessarily final**. The platform may manually resolve failed deposits to `success`.
</Warning>


---

# Coin List


URL: /paas/fincard-virtual/api/wallet-coins




---

# Create Wallet Address


URL: /paas/fincard-virtual/api/wallet-create




---

# Wallet Address List


URL: /paas/fincard-virtual/api/wallet-addresses




---

# Wallet Transaction History


URL: /paas/fincard-virtual/api/wallet-transaction




---

# Cards

Card issuance, lifecycle management, and transaction queries


URL: /paas/fincard-virtual/cards



# Card APIs

Full card lifecycle: card types, issuance, balance, deposit/withdraw, freeze/unfreeze, cancel, activate (physical), PIN management, and 5 transaction query types.

<Info>
  **Base URL:** `POST /api/v2.1/fincard/virtual/card/...`
</Info>

---

## Support Bins (Card Types)

Returns all available card types with pricing, features, and cardholder requirements.

```bash
POST /api/v2.1/fincard/virtual/card/v2/cardTypes
```

**Request:** `{}` (empty body)

**Response `data[]`:**

| Field | Type | Description |
|-------|------|-------------|
| `cardTypeId` | Long | Card type ID (use in create card) |
| `organization` | String | `Visa` / `MasterCard` / `Discover` |
| `country` | String | Issue country (ISO alpha-2) |
| `mode` | String | `PREPAID_CARD` / `BUDGET_CARD` (shared) |
| `bankCardBin` | String | Card BIN (e.g. `531993`) |
| `type` | String | `Virtual` / `Physical` |
| `category` | String | `GIFT` / `PURCHASE` / `SUBSCRIPTION` / `PHYSICAL` |
| `cardName` | String | Display name |
| `cardDesc` | String | Description |
| `cardPrice` | BigDecimal | Card creation fee |
| `cardPriceCurrency` | String | Fee currency |
| `support` | List | Supported merchant names (reference only) |
| `risk` | List | High-risk merchants (card cancellation risk) |
| `needCardHolder` | Boolean | **true** = must create cardholder first |
| `supportHolderRegin` | List | Supported cardholder nationalities (ISO alpha-2) |
| `supportHolderAreaCode` | List | Supported mobile area codes |
| `needDepositForActiveCard` | Boolean | Initial deposit required |
| `depositAmountMinQuotaForActiveCard` | BigDecimal | Min initial deposit |
| `depositAmountMaxQuotaForActiveCard` | BigDecimal | Max initial deposit |
| `fiatCurrency` | String | Card currency (e.g. `USD`) |
| `balanceRetentionQuota` | BigDecimal | Min balance for withdrawal |
| `status` | String | `online` / `offline` |
| `rechargeCurrency` | String | Deposit currency |
| `rechargeMinQuota` | BigDecimal | Min deposit amount |
| `rechargeMaxQuota` | BigDecimal | Max deposit amount |
| `rechargeFeeRate` | BigDecimal | Deposit fee rate (`1` = 1%) |
| `rechargeFixedFee` | BigDecimal | Fixed deposit fee |
| `rechargeDigital` | Integer | Deposit amount decimal places |
| `enableActiveCard` | Boolean | Card creation enabled |
| `enableDeposit` | Boolean | Deposit enabled |
| `enableFreeze` | Boolean | Freeze enabled |
| `enableUnFreeze` | Boolean | Unfreeze enabled |
| `metadata.cardHolderMaxCardLimit` | Integer | Max cards per cardholder |
| `metadata.cardHolderModel` | String | `B2B` / `B2C` (cardholder creation mode) |
| `metadata.spendingControls[]` | List | Default spending limits |
| `metadata.supportSettingMcc` | Boolean | MCC whitelist/blacklist supported |

<Warning>
  `metadata.cardHolderModel` B2B/B2C is an internal code — it does NOT mean company vs individual. Use it to determine which cardholder creation fields are required.
</Warning>

---

## Create Card V2

Create a new virtual or physical card with initial deposit.

```bash
POST /api/v2.1/fincard/virtual/card/v2/openCard
```

**Request:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `merchantOrderNo` | String | Yes | Client transaction ID `[20..40]` |
| `holderId` | Long | No | Cardholder ID (required if `needCardHolder=true`) |
| `cardTypeId` | Long | Yes | Card type ID from cardTypes |
| `amount` | BigDecimal | Yes | Initial deposit. Range: `depositAmountMin..Max` |
| `cardNumber` | String | No | Required for physical card (offline card number) |
| `accountId` | Long | No | Account ID for shared card mode (BUDGET_CARD) |

**Response `data`:**

| Field | Type | Description |
|-------|------|-------------|
| `orderNo` | String | Platform transaction ID |
| `merchantOrderNo` | String | Client transaction ID |
| `cardNo` | String | **Card ID** (use for all subsequent operations) |
| `currency` | String | Currency |
| `amount` | BigDecimal | Initial deposit amount |
| `fee` | BigDecimal | Card creation fee |
| `receivedAmount` | BigDecimal | Amount credited to card |
| `receivedCurrency` | String | Currency |
| `type` | String | `create` |
| `status` | String | `wait_process` / `processing` / `success` / `fail` |
| `description` | String | Status description |
| `transactionTime` | Long | Millisecond timestamp |

<Note>
  `cardNo` is the unique card identifier. Use it for all card operations (info, deposit, withdraw, freeze, cancel).
</Note>

---

## Card Info

Get card details, status, and optional balance.

```bash
POST /api/v2.1/fincard/virtual/card/info
```

**Request:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `cardNo` | String | Yes | Card ID |
| `onlySimpleInfo` | Boolean | No | Default `true`. Set `false` for balance info |

**Response `data`:**

| Field | Type | Description |
|-------|------|-------------|
| `cardTypeId` | Long | Card type ID |
| `holderId` | Long | Cardholder ID |
| `cardNo` | String | Card ID |
| `status` | String | See card statuses below |
| `blocked` | Boolean | Card blocked by issuer |
| `bindTime` | Long | Card creation time (ms) |
| `balanceInfo.cardNo` | String | Card ID |
| `balanceInfo.amount` | BigDecimal | Available balance |
| `balanceInfo.usedAmount` | BigDecimal | Amount used |
| `balanceInfo.currency` | String | Currency |
| `noPinPaymentAmount` | BigDecimal | PIN-free payment limit (physical) |
| `spendingControls[]` | List | Spending controls |

**Card Statuses:**

| Status | Description |
|--------|-------------|
| `pending` | Card being created |
| `un_activated` | Physical card waiting for activation |
| `Normal` | Active and usable |
| `Freeze` | Frozen (by merchant) |
| `Freezing` | Freeze in progress |
| `UnFreezing` | Unfreeze in progress |
| `canceling` | Cancel in progress |
| `cancel` | Cancelled (permanent) |
| `fail` | Card creation failed |

---

## Card Sensitive Info

Get encrypted card number, CVV, and expiry date. Decrypted with merchant's RSA private key.

```bash
POST /api/v2.1/fincard/virtual/card/info/sensitive
```

**Request:** `{ "cardNo": "..." }`

**Response `data`:**

| Field | Type | Description |
|-------|------|-------------|
| `cardNumber` | String | RSA-encrypted card number |
| `cvv` | String | RSA-encrypted CVV |
| `expireDate` | String | RSA-encrypted expiry date |
| `activateUrl` | String | Gift card redemption URL (gift cards only) |

<Note>
  **Gift cards** only return `activateUrl`. No card number, CVV, or expiry date.
</Note>

---

## Card Balance

```bash
POST /api/v2.1/fincard/virtual/card/balance
```

**Request:** `{ "cardNo": "..." }`

**Response `data`:** `{ cardNo, amount, usedAmount, currency }`

---

## Card Operations

All card operations follow the same request/response pattern.

### Common Request Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `cardNo` | String | Yes | Card ID |
| `merchantOrderNo` | String | Yes | Client tx ID `[20..40]` |
| `amount` | BigDecimal | Varies | Amount (for deposit/withdraw) |
| `clientRemark` | String | No | Client remark `[0..50]` |

### Common Response Fields

| Field | Type | Description |
|-------|------|-------------|
| `orderNo` | String | Platform tx ID |
| `merchantOrderNo` | String | Client tx ID |
| `cardNo` | String | Card ID |
| `currency` | String | Currency |
| `amount` | BigDecimal | Amount |
| `fee` | BigDecimal | Fee |
| `receivedAmount` | BigDecimal | Net amount |
| `type` | String | Operation type |
| `status` | String | `wait_process` / `processing` / `success` / `fail` |
| `description` | String | Description |
| `transactionTime` | Long | Millisecond timestamp |

### Endpoints

| Operation | Path | `type` | Amount Required |
|-----------|------|--------|-----------------|
| **Deposit** | `/card/deposit` | `deposit` | Yes |
| **Withdraw** | `/card/withdraw` | `withdraw` | Yes (≥ 0.01) |
| **Freeze** | `/card/v2/freeze` | `Freeze` | No |
| **UnFreeze** | `/card/v2/unfreeze` | `UnFreeze` | No |
| **Cancel** | `/card/cancel` | `cancel` | No |
| **Update** | `/card/v2/update` | `card_update` | No |
| **Update PIN** | `/card/updatePin` | `update_pin` | No |

<Warning>
  **Cancel is permanent.** The card cannot be reactivated after cancellation.
</Warning>

### Update Card — Additional Fields

The Update endpoint also accepts:

| Field | Type | Description |
|-------|------|-------------|
| `noPinPaymentAmount` | BigDecimal | PIN-free limit (physical cards only) |
| `spendingControls[]` | List | Spending limits (if `supportSetting=true`) |
| `riskControls.allowedMcc` | List | MCC whitelist (if `supportSettingMcc=true`) |
| `riskControls.blockedMcc` | List | MCC blacklist |

<Note>
  Only one of `allowedMcc` or `blockedMcc` can be set. Send empty array `[]` to remove.
</Note>

### Update PIN — Rules

PIN must be 6 digits with these constraints:
- No 3+ consecutive repeated digits
- Not entirely ascending or descending
- No repeated 2-3 digit segments (e.g. 123123)

---

## Activate Card (Physical)

Activate a physical card with PIN and activation code.

```bash
POST /api/v2.1/fincard/virtual/card/activate
```

**Request:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `merchantOrderNo` | String | Yes | Client tx ID `[20..40]` |
| `cardNo` | String | Yes | Card ID |
| `pin` | String | Yes | 6-digit PIN |
| `activeCode` | String | Yes | Activation code (from webhook or email) |
| `noPinPaymentAmount` | BigDecimal | No | PIN-free limit (0-2000 USD, default 500) |

**Response `data`:** `{ merchantOrderNo, cardNo, type: "card_activated", status, remark }`

---

## Transaction Queries

All transaction queries return `{ total, records[] }` with pagination (`pageNum`, `pageSize`).

### Card Purchase Transactions

Card fee and initial deposit records.

```bash
POST /api/v2.1/fincard/virtual/card/purchase/transaction
```

### Card Operation Transactions (V1 / V2)

Card lifecycle operations (create, deposit, withdraw, freeze, cancel, etc.)

```bash
POST /api/v2.1/fincard/virtual/card/transaction       # V1
POST /api/v2.1/fincard/virtual/card/v2/transaction     # V2 (recommended)
```

**Filter:** `type` = `create` / `deposit` / `cancel` / `Freeze` / `UnFreeze` / `withdraw` / `update_pin` / `blocked` / `card_update` / `overdraft_statement`

### Card Authorization Transactions

Consumption (auth), refund, verification, reversal, and maintenance fee records.

```bash
POST /api/v2.1/fincard/virtual/card/authorize/transaction
```

**Filter:** `type` = `auth` / `refund` / `verification` / `Void` / `maintain_fee`

**Statuses:** `authorized` / `failed` / `succeed`

### Card Authorization Fee Transactions

Fee records when card balance is insufficient for authorization fees.

```bash
POST /api/v2.1/fincard/virtual/card/auth/fee/transaction
```

**Filter:** `tradeType` = `card_patch_fee` / `card_patch_cross_border`

### Card 3DS Transactions

3DS OTP codes, authorization URLs, and physical card activation codes.

```bash
POST /api/v2.1/fincard/virtual/card/3ds/transaction
```

**Filter:** `type` = `third_3ds_otp` / `auth_url` / `activation_code`

| Field | Type | Description |
|-------|------|-------------|
| `values` | String | RSA-encrypted value (OTP, URL, or activation code) |
| `expirationTime` | Long | Expiration time (ms) |


---

# Support Bins


URL: /paas/fincard-virtual/api/card-types




---

# Create Card V2


URL: /paas/fincard-virtual/api/card-create-v2




---

# Create Card


URL: /paas/fincard-virtual/api/card-create




---

# Card Info


URL: /paas/fincard-virtual/api/card-info




---

# Card Info Sensitive


URL: /paas/fincard-virtual/api/card-info-sensitive




---

# Card Balance


URL: /paas/fincard-virtual/api/card-balance




---

# Card List


URL: /paas/fincard-virtual/api/card-list




---

# Deposit Card


URL: /paas/fincard-virtual/api/card-deposit




---

# Withdraw Card


URL: /paas/fincard-virtual/api/card-withdraw




---

# Freeze Card


URL: /paas/fincard-virtual/api/card-freeze




---

# Unfreeze Card


URL: /paas/fincard-virtual/api/card-unfreeze




---

# Cancel Card


URL: /paas/fincard-virtual/api/card-cancel




---

# Update Card


URL: /paas/fincard-virtual/api/card-update




---

# Update Card Note


URL: /paas/fincard-virtual/api/card-update-note




---

# Activate Card


URL: /paas/fincard-virtual/api/card-activate




---

# Update PIN


URL: /paas/fincard-virtual/api/card-update-pin




---

# Card Operation Transaction


URL: /paas/fincard-virtual/api/card-transaction




---

# Card Operation Transaction V2


URL: /paas/fincard-virtual/api/card-transaction-v2




---

# Card Authorization Transaction


URL: /paas/fincard-virtual/api/card-auth-transaction




---

# Card Authorization Fee Transaction


URL: /paas/fincard-virtual/api/card-fee-transaction




---

# Card Purchase Transaction


URL: /paas/fincard-virtual/api/card-purchase-transaction




---

# Card 3DS Transaction


URL: /paas/fincard-virtual/api/card-3ds-transaction




---

# Card Holders

KYC cardholder creation, update, approval tracking, and listing


URL: /paas/fincard-virtual/card-holders



# Card Holder APIs

Manage KYC-verified cardholders. Required when card type has `needCardHolder=true`. Supports B2B (simplified) and B2C (full KYC with ID documents) models.

<Info>
  **Base URL:** `POST /api/v2.1/fincard/virtual/card/holder/...`
</Info>

<Warning>
  The `cardHolderModel` values `B2B` and `B2C` are **internal codes** — they do NOT correspond to company vs individual. Check the `metadata.cardHolderModel` field from the [Card Types](/paas/fincard-virtual/cards) response.
</Warning>

---

## Cardholder Occupations

List available occupation codes for B2C cardholder creation.

```bash
POST /api/v2.1/fincard/virtual/card/holder/occupations
```

**Request:** `{}` (empty body)

**Response `data[]`:**

| Field | Type | Description |
|-------|------|-------------|
| `occupationCode` | String | Occupation code (e.g. `11-1011`) |
| `description` | String | Occupation description (e.g. `Chief Executives`) |

---

## Create Cardholder V2

Create a new KYC-verified cardholder. Fields differ based on `cardHolderModel`.

```bash
POST /api/v2.1/fincard/virtual/card/holder/v2/create
```

### B2B Model Request

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `cardHolderModel` | String | Yes | `B2B` |
| `merchantOrderNo` | String | Yes | Client tx ID `[20..40]` |
| `cardTypeId` | Long | Yes | Card type ID |
| `areaCode` | String | Yes | Mobile area code `[2..5]` (from `supportHolderAreaCode`) |
| `mobile` | String | Yes | Mobile number `[5..20]` |
| `email` | String | Yes | Email `[5..50]` (receives verification codes) |
| `firstName` | String | Yes | First name (English only) `[2..32]` |
| `lastName` | String | Yes | Last name (English only) `[2..32]` |
| `birthday` | String | Yes | Date of birth `yyyy-MM-dd` |
| `country` | String | Yes | Bill address country (ISO alpha-2, from `supportHolderRegin`) |
| `town` | String | Yes | Bill address city code (from [City List](/paas/fincard-virtual/common)) |
| `address` | String | Yes | Bill address `[2..40]` (letters, numbers, hyphens, spaces) |
| `postCode` | String | Yes | Postal code `[2..15]` |

<Note>
  Total length of `firstName` + `lastName` cannot exceed 32 characters (including spaces).
</Note>

### B2C Model Request (additional fields)

All B2B fields plus:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `nationality` | String | Yes | ISO alpha-2 (from `supportHolderRegin`) |
| `gender` | String | Yes | `M` (male) / `F` (female) |
| `occupation` | String | Yes | Occupation code (from [Occupations](#cardholder-occupations)) |
| `annualSalary` | String | Yes | e.g. `100000 USD` |
| `accountPurpose` | String | Yes | English only (e.g. `Living Expense`) |
| `expectedMonthlyVolume` | String | Yes | e.g. `10000 USD` |
| `idType` | String | Yes | `PASSPORT` / `HK_HKID` / `DLN` / `GOVERNMENT_ISSUED_ID_CARD` |
| `idNumber` | String | Yes | ID number `[2..50]` |
| `issueDate` | String | Yes | ID issue date `yyyy-MM-dd` |
| `idNoExpiryDate` | String | Yes | ID expiry date `yyyy-MM-dd` |
| `idFrontId` | String | Yes | Front photo file ID (from [Upload File](/paas/fincard-virtual/common)) |
| `idBackId` | String | Yes | Back photo file ID |
| `idHoldId` | String | Yes | Selfie photo file ID |
| `ipAddress` | String | Yes | IPv4 address |

### ID Types by Region

| Region | Supported ID Types |
|--------|--------------------|
| **Hong Kong** | `PASSPORT`, `HK_HKID` |
| **All other** | `PASSPORT`, `DLN`, `GOVERNMENT_ISSUED_ID_CARD` |

### Restricted Countries/Regions

Cuba, North Korea, Egypt, Iran, Myanmar, Nigeria, Russia, Belarus, South Africa, Syria, Ukraine, Venezuela, Sudan, South Sudan, Libya, Crimea, Burundi, Central African Republic, Somalia, Zimbabwe, Afghanistan.

### Response `data`

| Field | Type | Description |
|-------|------|-------------|
| `holderId` | Long | **Cardholder ID** (use in create card) |
| `merchantOrderNo` | String | Client tx ID |
| `cardTypeId` | Long | Card type ID |
| `statusFlowLocation` | String | `admin` (platform review) / `channel` (bank review) |
| `status` | String | `wait_audit` / `pass_audit` / `under_review` / `reject` |
| `description` | String | Status description |

<Note>
  Approval flow: **admin** review first → then **channel** (bank) review. Cardholder can only be used for card creation when `status=pass_audit`.
</Note>

---

## Update Cardholder V2

Update a rejected cardholder. Only allowed when `statusFlowLocation=admin` AND `status=reject`.

```bash
POST /api/v2.1/fincard/virtual/card/holder/v2/update
```

**Request:** Same fields as Create + `holderId` (required). All fields are re-submitted.

**Response:** Same as Create response.

<Warning>
  Cardholder information **cannot be modified after bank submission**. Email and ID number are **globally unique** per card type — duplicates are rejected.
</Warning>

---

## Cardholder List

Query cardholders with pagination and filters.

```bash
POST /api/v2.1/fincard/virtual/card/holder/list
```

**Request:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `pageNum` | Integer | Yes | Page number (default 1) |
| `pageSize` | Integer | Yes | Page size (max 100, default 10) |
| `holderId` | Long | No | Filter by holder ID |
| `areaCode` | String | No | Filter by area code (requires `mobile` too) |
| `mobile` | String | No | Filter by mobile |
| `email` | String | No | Filter by email |
| `merchantOrderNo` | String | No | Filter by client tx ID |

**Response `data`:** `{ total, records[] }`

| Field | Type | Description |
|-------|------|-------------|
| `holderId` | String | Cardholder ID |
| `merchantOrderNo` | String | Client tx ID |
| `cardTypeId` | String | Card type ID |
| `areaCode` | String | Mobile area code |
| `mobile` | String | Mobile number |
| `email` | String | Email |
| `firstName` | String | First name |
| `lastName` | String | Last name |
| `birthday` | String | Date of birth |
| `country` | String | Country |
| `town` | String | City code |
| `address` | String | Address |
| `postCode` | String | Postal code |
| `statusFlowLocation` | String | `admin` / `channel` |
| `status` | String | `wait_audit` / `pass_audit` / `under_review` / `reject` |
| `description` | String | Status description |
| `createTime` | Long | Creation time (ms) |
| `updateTime` | Long | Update time (ms) |

---

## Deprecated Endpoints

The following V1 endpoints are still available but deprecated:

| Endpoint | Path | Replacement |
|----------|------|-------------|
| Create V1 | `/card/holder/create` | Use `/card/holder/v2/create` |
| Update V1 | `/card/holder/update` | Use `/card/holder/v2/update` |


---

# Create Cardholder V2


URL: /paas/fincard-virtual/api/holder-create-v2




---

# Create Cardholder


URL: /paas/fincard-virtual/api/holder-create




---

# Update Cardholder V2


URL: /paas/fincard-virtual/api/holder-update-v2




---

# Update Cardholder


URL: /paas/fincard-virtual/api/holder-update




---

# Cardholder List


URL: /paas/fincard-virtual/api/holder-list




---

# Cardholder Occupations


URL: /paas/fincard-virtual/api/holder-occupations




---

# Work Submit


URL: /paas/fincard-virtual/api/work-submit




---

# Work List


URL: /paas/fincard-virtual/api/work-list




---

# Webhooks

Real-time event notifications for card operations, transactions, and cardholder status changes


URL: /paas/fincard-virtual/webhooks



# Webhook Events

FinCard Virtual pushes real-time event notifications to your configured webhook URL. Events are signed with the platform RSA private key — verify using the platform public key.

<Info>
  **Callback URL:** `POST /api/v2.1/fincard/virtual/webhook/callback`
</Info>

---

## Signature Verification

All webhook events include an `X-FC-SIGNATURE` header containing a SHA256withRSA signature of the response body, base64-encoded.

```javascript
// Verify: SHA256withRSA(responseBody, platformPublicKey) === X-FC-SIGNATURE
```

Your endpoint must return `{"success": true}` to acknowledge receipt.

---

## Event Types

### Card Operation Transaction Event

Triggered when card operations complete (create, deposit, withdraw, freeze, unfreeze, cancel, block, overdraft).

| Field | Type | Description |
|-------|------|-------------|
| `orderNo` | String | Transaction ID |
| `merchantOrderNo` | String | Client tx ID |
| `cardNo` | String | Card ID |
| `currency` | String | Currency |
| `amount` | BigDecimal | Amount |
| `fee` | BigDecimal | Fee |
| `receivedAmount` | BigDecimal | Net amount |
| `type` | String | `create` / `deposit` / `withdraw` / `Freeze` / `UnFreeze` / `cancel` / `blocked` / `overdraft_statement` |
| `status` | String | `success` / `fail` |
| `transactionTime` | Long | Millisecond timestamp |

---

### Card Authorization Transaction Event

Triggered for card consumption events (purchases, refunds, verifications).

| Field | Type | Description |
|-------|------|-------------|
| `cardNo` | String | Card ID |
| `tradeNo` | String | Transaction serial number |
| `originTradeNo` | String | Original transaction (for refunds/voids) |
| `currency` | String | Transaction currency |
| `amount` | BigDecimal | Transaction amount |
| `authorizedAmount` | BigDecimal | Authorized amount (card currency) |
| `authorizedCurrency` | String | Card currency |
| `fee` | BigDecimal | Authorization fee |
| `crossBoardFee` | BigDecimal | Cross-border fee |
| `merchantName` | String | Merchant name |
| `merchantData` | Object | Merchant details (MCC, country, city, etc.) |
| `type` | String | `auth` / `refund` / `verification` / `Void` / `maintain_fee` |
| `status` | String | `authorized` / `failed` / `succeed` |
| `transactionTime` | Long | Millisecond timestamp |

---

### Card Authorization Fee Transaction Event

Triggered when insufficient card balance causes fee deduction from merchant reserve.

| Field | Type | Description |
|-------|------|-------------|
| `cardNo` | String | Card ID |
| `tradeNo` | String | Fee transaction ID |
| `originTradeNo` | String | Original authorization transaction |
| `currency` | String | Fee currency |
| `amount` | BigDecimal | Fee amount |
| `type` | String | `card_patch_fee` / `card_patch_cross_border` |
| `deductionSourceFunds` | String | `wallet` (deducted from merchant account) |
| `status` | String | `success` |
| `transactionTime` | Long | Millisecond timestamp |

---

### Card 3DS Transaction Event

Triggered for 3DS verification (OTP), transaction authorization URLs, and physical card activation codes.

| Field | Type | Description |
|-------|------|-------------|
| `cardNo` | String | Card ID |
| `tradeNo` | String | Transaction serial number |
| `currency` | String | Currency |
| `amount` | BigDecimal | Amount |
| `merchantName` | String | Merchant/scenario name |
| `values` | String | **RSA-encrypted** value (OTP code, auth URL, or activation code) |
| `type` | String | `third_3ds_otp` / `auth_url` / `activation_code` |
| `expirationTime` | Long | Expiration time (ms) |
| `transactionTime` | Long | Millisecond timestamp |

<Warning>
  The `values` field is encrypted with the merchant's RSA public key. Decrypt using your RSA private key.
</Warning>

---

### Card Holder Event

Triggered when cardholder approval status changes.

| Field | Type | Description |
|-------|------|-------------|
| `holderId` | Long | Cardholder ID |
| `statusFlowLocation` | String | `admin` / `channel` |
| `status` | String | `pass_audit` / `reject` / `under_review` |
| `description` | String | Reason (especially for rejections) |

---

### Activate Card Event

Triggered when a physical card is activated.

| Field | Type | Description |
|-------|------|-------------|
| `cardNo` | String | Card ID |
| `type` | String | `card_activated` |
| `status` | String | `success` / `fail` |

---

### Work Order Event

Triggered when work order status changes.

| Field | Type | Description |
|-------|------|-------------|
| `orderNo` | String | Work order ID |
| `merchantOrderNo` | String | Client tx ID |
| `tradeStatus` | String | `processing` / `success` / `fail` |

---

### Wallet Transaction Event (v2)

Triggered for crypto wallet deposit/withdrawal completions.

| Field | Type | Description |
|-------|------|-------------|
| `orderNo` | String | Transaction ID |
| `coinKey` | String | Coin key |
| `coinName` | String | Coin name |
| `txHash` | String | On-chain hash |
| `txAmount` | BigDecimal | On-chain amount |
| `receivedAmount` | BigDecimal | Net received |
| `receivedCurrency` | String | Currency |
| `type` | String | `DEPOSIT` / `WITHDRAW` |
| `status` | String | `success` / `fail` |

---

## Response Format

Your webhook endpoint must respond with:

```json
{
  "success": true
}
```

<Warning>
  If your endpoint fails to respond or returns an error, the platform will retry delivery. Ensure idempotent processing using `orderNo` / `tradeNo` as deduplication keys.
</Warning>


---

# Webhook Callback


URL: /paas/fincard-virtual/api/webhook-callback




---

# Page not found

The page you're looking for doesn't exist or has moved.


URL: /404



The page you're looking for doesn't exist or has moved. Index pages live at the folder URL (for example `/baas/api/reference/administration`, not `/…/administration/index`).

<CardGroup cols={2}>
  <Card title="FinHub Overview" icon="house" href="/overview/about">
    About FinHub and service models
  </Card>
  <Card title="Business as a Service" icon="building" href="/baas/introduction">
    BaaS products, CoreX, and API guides
  </Card>
  <Card title="API Reference" icon="code" href="/baas/api/reference">
    Customer, financial, and compliance APIs
  </Card>
  <Card title="Developer Portal" icon="key" href="https://sandbox.finhub.cloud/dev-portal">
    Sign in for playground and Postman
  </Card>
</CardGroup>


---

# Environments

Sandbox and Production environment details


URL: /baas/api/development/environments



# Environments

FinHub provides two distinct environments for development and live operations.

## Overview

| Environment | Purpose | Base URL |
|-------------|---------|----------|
| **Sandbox** | Development & Testing | `https://gateway.sandbox.finhub.cloud` |
| **Production** | Live Operations | `https://gateway.finhub.cloud` |

## Sandbox Environment

- **Isolated System**: Separate from production
- **Test Data**: Pre-populated sample data
- **No Financial Impact**: No real money movement
- **Simulated Services**: All services simulated

### Sandbox Limitations

- Simplified regulatory checks
- Some verification processes mocked
- Lower transaction limits
- Some features require approval

## Production Environment

- **Real Transactions**: Actual monetary transfers
- **Full Compliance**: Complete regulatory checks
- **Enhanced Security**: mTLS, IP whitelisting
- **24/7 Support**: Full production support

### Production Requirements

| Requirement | Description |
|-------------|-------------|
| **IP Whitelisting** | Approved IPs only |
| **mTLS** | Client certificate auth |
| **Request Signing** | Cryptographic signing |
| **Encryption** | All data encrypted |

## Feature Comparison

| Feature | Sandbox | Production |
|---------|---------|------------|
| Regulatory Checks | Simplified | Complete |
| Payment Networks | Simulated | Full Access |
| Support | Standard | 24/7 Priority |
| Security | Basic | mTLS + IP whitelist |

## Support

- **Sandbox**: sandbox-support@finhub.cloud
- **Production**: production-support@finhub.cloud


---

# Categorization Hierarchy

Understanding FinHub's risk-based customer categorization system


URL: /baas/api/getting-onboarded/categorization-hierarchy



# Categorization Hierarchy

FinHub uses a **hierarchical categorization system** to manage customer risk profiles, feature availability, and transaction limits. Understanding this system is essential for proper customer onboarding.

## Overview

The categorization hierarchy defines:
- **Risk levels** for different customer types
- **Feature availability** based on risk assessment
- **Transaction limits** and operational parameters
- **Verification requirements** per category

```mermaid
graph TD
    A[Tenant] --> B[Customer Categories]
    B --> C[Low Risk]
    B --> D[Medium Risk]
    B --> E[High Risk]
    C --> F[Features & Limits]
    D --> G[Features & Limits]
    E --> H[Features & Limits]
    F --> I[Parametrization]
    G --> J[Parametrization]
    H --> K[Parametrization]
```

## Hierarchy Components

### 1. Tenant Level

Each tenant has its own categorization configuration:

```json
{
  "tenantId": "your-tenant-id",
  "categories": [...]
}
```

### 2. Customer Categories

Categories define risk profiles for customer segmentation:

| Category | Risk Level | Typical Use Case |
|----------|------------|------------------|
| `RETAIL_LOW` | Low | Standard retail customers with basic needs |
| `RETAIL_MEDIUM` | Medium | Retail customers with moderate transaction volumes |
| `RETAIL_HIGH` | High | High-net-worth individuals, complex requirements |
| `BUSINESS_LOW` | Low | Small businesses with basic banking needs |
| `BUSINESS_MEDIUM` | Medium | SMEs with regular transaction activity |
| `BUSINESS_HIGH` | High | Large enterprises, complex corporate structures |

### 3. Category-Feature Relations

Each category has associated features with specific parameters:

```json
{
  "categoryFeatureRelations": [
    {
      "featureCode": "PAYMENTS",
      "enabled": true,
      "parametrization": {
        "riskLevel": "MEDIUM",
        "riskScore": 50,
        "monthlyLimit": 50000,
        "dailyLimit": 10000,
        "transactionLimit": 5000
      }
    },
    {
      "featureCode": "INTERNATIONAL_TRANSFERS",
      "enabled": true,
      "parametrization": {
        "riskLevel": "MEDIUM",
        "allowedCountries": ["EU", "US", "UK"],
        "monthlyLimit": 25000
      }
    }
  ]
}
```

## Retrieving the Categorization Hierarchy

Before registering a customer, retrieve the available categories:

<CodeGroup>
```bash cURL
curl -X GET "https://api.finhub.cloud/api/v2.1/categorization/hierarchy" \
  -H "Authorization: Bearer {admin_token}" \
  -H "X-Tenant-Id: {tenant_id}" \
  -H "Content-Type: application/json"
```

```powershell PowerShell
$headers = @{
    "Authorization" = "Bearer $adminToken"
    "X-Tenant-Id"   = $tenantId
    "Content-Type"  = "application/json"
}

$response = Invoke-RestMethod -Uri "$baseUrl/api/v2.1/categorization/hierarchy" `
    -Method Get -Headers $headers
```
</CodeGroup>

### Response Structure

```json
{
  "code": 200,
  "data": {
    "categories": [
      {
        "categoryCode": "RETAIL_MEDIUM",
        "categoryName": "Medium Risk Retail",
        "customerType": "INDIVIDUAL",
        "riskLevel": "MEDIUM",
        "features": [
          {
            "featureCode": "PAYMENTS",
            "featureName": "Payment Services",
            "defaultParameters": {
              "monthlyLimit": 50000,
              "dailyLimit": 10000
            }
          }
        ]
      }
    ]
  }
}
```

## Using Categories in Registration

When registering a customer, specify the category and any custom parametrization:

```json
{
  "customerCategory": "RETAIL_MEDIUM",
  "categoryFeatureRelations": [
    {
      "featureCode": "PAYMENTS",
      "parametrization": {
        "riskLevel": "MEDIUM",
        "riskScore": 50,
        "monthlyLimit": 50000
      }
    }
  ],
  "personalInfo": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com"
  }
}
```

## Risk Level Impact

| Risk Level | Verification Required | Approval Authority | Default Limits |
|------------|----------------------|-------------------|----------------|
| **Low** | Basic identity verification | Automatic | €10,000/month |
| **Medium** | Standard verification + documents | Tenant Admin | €50,000/month |
| **High** | Enhanced due diligence | Power Tenant | €200,000/month |

## Best Practices

<CardGroup cols={2}>
  <Card title="Select Appropriate Category" icon="list-check">
    Choose the category that matches your customer's actual risk profile and transaction needs.
  </Card>
  <Card title="Don't Over-Categorize" icon="scale-balanced">
    Avoid placing low-risk customers in high-risk categories as it adds unnecessary friction.
  </Card>
  <Card title="Plan for Growth" icon="chart-line">
    Consider future needs - upgrading categories later requires additional verification.
  </Card>
  <Card title="Document Decisions" icon="file-lines">
    Keep records of why specific categories were selected for compliance audits.
  </Card>
</CardGroup>

## Related Pages

<CardGroup cols={2}>
  <Card title="Individual Customer (B2C)" icon="user" href="/baas/api/integration/flows/individual-customer/registration">
    Individual customer registration with categorization
  </Card>
  <Card title="Organization Customer (B2B)" icon="building" href="/baas/api/integration/flows/organization-customer/registration">
    Organization registration with business categories
  </Card>
</CardGroup>


---

# Compliance Requirements

Compliance documentation required for FinHub tenant onboarding


URL: /baas/api/getting-onboarded/compliance-requirements



# Compliance Requirements

As a regulated financial services platform, FinHub requires all tenants to meet specific compliance requirements before accessing the platform.

## Required Compliance Documentation

### 1. Anti-Money Laundering (AML) Policy

Your AML policy should include:

- Customer due diligence procedures
- Transaction monitoring processes
- Suspicious activity reporting procedures
- Record-keeping requirements
- Staff training programs

### 2. Know Your Customer (KYC) Procedures

Document your KYC procedures covering:

- Customer identification requirements
- Verification methods and data sources
- Risk-based approach to customer due diligence
- Enhanced due diligence for high-risk customers
- Ongoing monitoring procedures

### 3. Risk Assessment Framework

Provide your risk assessment framework including:

- Risk categorization methodology
- Customer risk scoring criteria
- Geographic risk factors
- Product/service risk assessment
- Periodic review procedures

## Compliance Review Process

| Stage | Duration | Activities |
|-------|----------|------------|
| Document Submission | Day 1 | Submit all required documents |
| Initial Review | Days 2-3 | Completeness check |
| Detailed Assessment | Days 4-7 | Compliance team review |
| Clarifications | If needed | Address any questions |
| Approval | Final | Compliance sign-off |

## Regulatory Considerations

Depending on your business model and jurisdiction, you may need:

- **Financial Services License**: If operating as a regulated entity
- **Data Protection Registration**: GDPR compliance for EU operations
- **PCI DSS Compliance**: For card-related operations
- **Local Regulatory Approvals**: Country-specific requirements

## Ongoing Compliance

After onboarding, tenants must:

- Maintain updated compliance documentation
- Report material changes to FinHub
- Participate in periodic compliance reviews
- Complete required training programs

## Next Steps

<CardGroup cols={2}>
  <Card title="Select Products" icon="cube" href="/baas/api/getting-onboarded/selecting-products">
    Choose your FinHub products
  </Card>
  <Card title="Receive Credentials" icon="key" href="/baas/api/getting-onboarded/receiving-credentials">
    Get your API access
  </Card>
</CardGroup>


---

# Getting Onboarded

Complete the tenant registration and onboarding process with FinHub


URL: /baas/api/getting-onboarded



# Getting Onboarded

Before you can start integrating with FinHub API, you need to complete the tenant onboarding process. This section guides you through registration, compliance requirements, product selection, and receiving your API credentials.

## Onboarding Overview

```mermaid
flowchart LR
    A[Register] --> B[Compliance Review]
    B --> C[Select Products]
    C --> D[Receive Credentials]
    D --> E[Start Integration]
```

## Self-Service Registration

Get started immediately with our self-service signup:

<Card title="Register Now" icon="user-plus" href="https://bpm-beta.finhub.cloud/new-tenant/signup">
  Start your API tenant registration at bpm-beta.finhub.cloud
</Card>

## Onboarding Steps

<Steps>
  <Step title="Tenant Registration">
    Register your organization through our self-service portal
  </Step>
  <Step title="Compliance Requirements">
    Provide required compliance documentation (AML policy, KYC procedures)
  </Step>
  <Step title="Select Your Products">
    Choose which FinHub products you want to integrate
  </Step>
  <Step title="Receive Credentials">
    Get your sandbox tenant credentials and API access
  </Step>
</Steps>

## What You'll Need

Before starting the onboarding process, prepare the following:

### Business Documentation
- Certificate of Incorporation
- Business Registration Certificate
- Tax Identification Number

### Compliance Documentation
- AML Policy
- KYC Procedures
- Risk Assessment Framework

### Technical Contacts
- Primary Technical Contact
- Security Officer Contact
- Operations Manager Contact

## Timeline

| Phase | Duration | Activities |
|-------|----------|------------|
| Registration | Instant | Self-service signup, account creation |
| Compliance Review | 3-7 days | Document verification |
| Account Setup | 1-2 days | Credential provisioning |

## Next Steps

<CardGroup cols={2}>
  <Card title="Tenant Registration" icon="building" href="/baas/api/getting-onboarded/tenant-registration">
    Start your registration process
  </Card>
  <Card title="Compliance Requirements" icon="shield-check" href="/baas/api/getting-onboarded/compliance-requirements">
    Review compliance documentation
  </Card>
</CardGroup>


---

# Receiving Credentials

Understand the credentials you receive after tenant onboarding


URL: /baas/api/getting-onboarded/receiving-credentials



# Receiving Credentials

After completing the onboarding process, you will receive your FinHub credentials to access the platform.

## Credentials Package

You will receive the following credentials:

### API Credentials

| Credential | Description | Usage |
|------------|-------------|-------|
| **Tenant ID** | Unique identifier for your organization | Required in X-Tenant-ID header |
| **Client ID** | API client identifier | Used for authentication |
| **Client Secret** | API client secret | Used for authentication |
| **Sandbox URL** | Base URL for sandbox API | API endpoint |

### Portal Access

| Access | Description |
|--------|-------------|
| **Tenant Operation Panel** | Administrative dashboard for managing your tenant |
| **Developer Portal** | Access to API documentation and playground |

## Credential Delivery

Credentials are delivered securely via:

1. **Welcome Email** - Contains portal access and initial setup instructions
2. **Developer Portal** - API credentials available after first login
3. **Secure Channel** - Client secrets delivered via secure channel

## Security Best Practices

<Warning>
Never share your credentials or commit them to version control systems.
</Warning>

- Store credentials securely using environment variables or secret management
- Rotate credentials periodically
- Use different credentials for sandbox and production
- Implement proper access control for credential access

## Verifying Your Credentials

Test your credentials with a simple authentication request:

```bash
curl -X POST "https://gateway.sandbox.finhub.cloud/api/v2/auth/sandbox/token" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -d '{
    "username": "YOUR_USERNAME",
    "password": "YOUR_PASSWORD",
    "customerId": "YOUR_CLIENT_ID",
    "customerSecret": "YOUR_CLIENT_SECRET",
    "accountType": "b2b"
  }'
```

A successful response indicates your credentials are working correctly.

## Next Steps

<CardGroup cols={2}>
  <Card title="Development Environment" icon="laptop-code" href="/baas/api/development">
    Set up your sandbox
  </Card>
  <Card title="Categorization Hierarchy" icon="sitemap" href="/baas/api/getting-onboarded/categorization-hierarchy">
    Understand customer categories
  </Card>
</CardGroup>


---

# Selecting Your Products

Choose the FinHub products that fit your business needs


URL: /baas/api/getting-onboarded/selecting-products



# Selecting Your Products

FinHub offers a comprehensive suite of financial technology products. This guide helps you select the right products for your integration.

## Available Products

| Product | Description | Key Capabilities |
|---------|-------------|------------------|
| **FinCore™** | Core Banking System | Account management, transaction processing, multi-currency |
| **FinTrans™** | Transaction Processing | Domestic/international transfers, real-time payments |
| **FinCheck™** | RegTech & Compliance | KYC/KYB verification, AML screening |
| **FinCard™** | Card Issuing | Virtual/physical cards, card management |
| **FinExE™** | Currency Exchange | Multi-currency exchange, FX management |
| **FinPOS™** | Point of Sale | Payment acceptance, merchant management |

## Product Selection by Use Case

### For Embedded Finance
- FinCore™ (Core Banking)
- FinTrans™ (Payments)
- FinCheck™ (Compliance)

### For Banking-as-a-Service
- FinCore™ (Core Banking)
- FinTrans™ (Payments)
- FinCard™ (Card Issuing)
- FinCheck™ (Compliance)

### For Business Banking
- FinCore™ (Core Banking)
- FinTrans™ (Payments)
- FinCheck™ (Compliance)

## Product Dependencies

Some products require other products as prerequisites:

```mermaid
flowchart TD
    A[FinCore™] --> B[FinTrans™]
    A --> C[FinCard™]
    A --> D[FinExE™]
    E[FinCheck™] --> A
```

## Next Steps

After selecting your products:

1. Confirm your selection with your account manager
2. Proceed to [Receiving Credentials](/baas/api/getting-onboarded/receiving-credentials)
3. Begin your [Development Environment](/baas/api/development) setup


---

# Tenant Registration

Register your organization as a FinHub API tenant through self-service signup


URL: /baas/api/getting-onboarded/tenant-registration



# Tenant Registration

Register your organization as a FinHub API tenant through our self-service portal to start your API integration.

## Self-Service Registration

FinHub offers a streamlined self-registration process. Visit our tenant signup portal to get started:

<Card title="Register Now" icon="user-plus" href="https://bpm-beta.finhub.cloud/new-tenant/signup">
  Start your API tenant registration at bpm-beta.finhub.cloud
</Card>

## Registration Process

```mermaid
sequenceDiagram
    participant You
    participant Signup Portal
    participant FinHub Platform
    participant Compliance
    
    You->>Signup Portal: Visit signup page
    Signup Portal->>You: Registration form
    You->>Signup Portal: Submit business details
    Signup Portal->>FinHub Platform: Create tenant account
    FinHub Platform->>Compliance: Submit for review
    Compliance-->>FinHub Platform: Approval
    FinHub Platform->>You: Issue API credentials
```

## Registration Steps

<Steps>
  <Step title="Visit Signup Portal">
    Navigate to [bpm-beta.finhub.cloud/new-tenant/signup](https://bpm-beta.finhub.cloud/new-tenant/signup)
  </Step>
  <Step title="Complete Registration Form">
    Provide your business and contact information
  </Step>
  <Step title="Verify Email">
    Confirm your email address via verification link
  </Step>
  <Step title="Submit Compliance Documents">
    Upload required business and compliance documentation
  </Step>
  <Step title="Receive API Credentials">
    Get your sandbox credentials after approval
  </Step>
</Steps>

## Required Documents

| Document Type | Description | Format |
|---------------|-------------|--------|
| Certificate of Incorporation | Proof of legal entity | PDF |
| Business Registration | Government registration | PDF |
| Tax ID Certificate | Tax identification | PDF |
| Authorized Signatories | List of authorized persons | PDF |
| Bank Reference Letter | Banking relationship proof | PDF |

## Account Creation

Upon approval, FinHub will:

1. Create your tenant account in our system
2. Configure your selected products
3. Set up your sandbox environment
4. Generate API credentials

## Credential Delivery

You will receive:

- **Sandbox URL**: Your dedicated sandbox endpoint
- **Tenant ID**: Your unique tenant identifier
- **API Credentials**: Client ID and Client Secret
- **Admin Access**: Tenant Operation Panel credentials

## Next Steps

After completing registration:

1. Review [Compliance Requirements](/baas/api/getting-onboarded/compliance-requirements)
2. Proceed to [Selecting Your Products](/baas/api/getting-onboarded/selecting-products)
3. Set up your [Development Environment](/baas/api/development)


---

# Product Selection

Select FinHub products for API integration


URL: /baas/api/getting-started/product-selection



# Product Selection

Select which FinHub products you want to integrate via API.

## Available Products

| Product | API Capabilities |
|---------|------------------|
| **FinCore™** | Accounts, wallets, ledger |
| **FinTrans™** | Payments, transfers, SEPA, SWIFT |
| **FinCheck™** | KYC, KYB, AML screening |
| **FinCard™** | Card issuance, management |
| **FinExE™** | FX, multi-currency |

## Selection Considerations

- **Use Case**: What are you building?
- **Customer Type**: B2C, B2B, or both?
- **Transaction Types**: Payments, cards, FX?
- **Compliance Needs**: KYC/AML requirements?

## Common Combinations

| Use Case | Products |
|----------|----------|
| **Payment App** | FinCore + FinTrans |
| **Neobank** | FinCore + FinTrans + FinCard + FinCheck |
| **Marketplace Payments** | FinCore + FinTrans |
| **FX Platform** | FinCore + FinTrans + FinExE |

## Next Steps

<Card title="Sandbox Access" icon="flask" href="/baas/api/getting-started/sandbox-access">
  Get your sandbox credentials
</Card>


---

# Authenticate

Authenticate and get an access token


URL: /baas/api/getting-started/quick-start/authenticate



# Authenticate

Authenticate with the FinHub API using OAuth 2.0 Client Credentials flow.

## Token Endpoint

```
POST /api/v2/auth/sandbox/token
```

## Required Headers

| Header | Value |
|--------|-------|
| `X-Tenant-ID` | Your tenant ID |
| `Content-Type` | `application/json` |

## Request Body

```json
{
  "username": "your_username",
  "password": "your_password",
  "customerId": "your_client_id",
  "customerSecret": "your_client_secret",
  "accountType": "b2b"
}
```

## Example Request

```bash
curl -X POST "https://gateway.finhub.cloud/api/v2/auth/sandbox/token" \
  -H "X-Tenant-ID: 1234567" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your_username",
    "password": "your_password",
    "customerId": "your_client_id",
    "customerSecret": "your_client_secret",
    "accountType": "b2b"
  }'
```

## Response

```json
{
  "access_token": "eyJ4NXQiOiJNVFJsT1RFM1lXRmxNR1Jr...",
  "token_type": "Bearer",
  "expires_in": 10000
}
```

## Using the Token

Include in all subsequent requests:

```
Authorization: Bearer eyJ4NXQiOiJNVFJsT1RFM1lXRmxNR1Jr...
```

## Next Steps

<Card title="First Call" icon="code" href="/baas/api/getting-started/quick-start/first-call">
  Make your first API call
</Card>


---

# First Call

Make your first FinHub API call


URL: /baas/api/getting-started/quick-start/first-call



# First Call

Make your first API call to verify your integration is working.

## Test Endpoint

Let's call a simple endpoint to verify connectivity:

```
GET /api/v2/tenant/info
```

## Example Request

```bash
curl -X GET "https://gateway.finhub.cloud/api/v2/tenant/info" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "Content-Type: application/json"
```

## Expected Response

```json
{
  "tenantId": "1234567",
  "tenantName": "Your Company",
  "status": "active",
  "products": ["FinCore", "FinTrans"]
}
```

## Success!

If you received a successful response, your integration is working. You're ready to:

- Explore the [Development Environment](/baas/api/development)
- Review [Integration Guides](/baas/api/integration/flows)
- Browse the [API Reference](/baas/api/reference)

## Troubleshooting

| Error | Solution |
|-------|----------|
| 401 Unauthorized | Check access token, may be expired |
| 403 Forbidden | Check Tenant ID header |
| 404 Not Found | Check endpoint URL |

## Next Steps

<CardGroup cols={2}>
  <Card title="Development Environment" icon="code" href="/baas/api/development">
    Set up your dev environment
  </Card>
  <Card title="Integration Guide" icon="plug" href="/baas/api/integration/flows">
    Start integrating
  </Card>
</CardGroup>


---

# Get Credentials

Obtain your FinHub API credentials


URL: /baas/api/getting-started/quick-start/get-credentials



# Get Credentials

Obtain your API credentials from the FinHub Developer Portal.

## Access Developer Portal

1. Log into [FinHub Sandbox Portal](https://sandbox.finhub.cloud)
2. Navigate to **Sandbox** → **API Access**
3. View or generate credentials

## Your Credentials

| Credential | Description |
|------------|-------------|
| **Tenant ID** | Your unique tenant identifier |
| **Client ID** | OAuth client identifier |
| **Client Secret** | OAuth client secret (keep secure!) |

## Security Best Practices

- Never expose Client Secret in client-side code
- Store credentials in environment variables
- Use secrets management in production
- Rotate credentials periodically

## Example Environment Setup

```bash
export FINHUB_TENANT_ID="your_tenant_id"
export FINHUB_CLIENT_ID="your_client_id"
export FINHUB_CLIENT_SECRET="your_client_secret"
```

## Next Steps

<Card title="Authenticate" icon="lock" href="/baas/api/getting-started/quick-start/authenticate">
  Get an access token
</Card>


---

# Quick Start

Make your first FinHub API call in minutes


URL: /baas/api/getting-started/quick-start



# Quick Start

Get up and running with the FinHub API in minutes.

<Steps>
  <Step title="Get Credentials">
    Obtain your API credentials from the Developer Portal
  </Step>
  <Step title="Authenticate">
    Get an access token using OAuth 2.0
  </Step>
  <Step title="First Call">
    Make your first API request
  </Step>
</Steps>

## Prerequisites

- Sandbox tenant credentials (Client ID, Client Secret)
- HTTP client (cURL, Postman, or code)

## Quick Links

<CardGroup cols={3}>
  <Card title="Get Credentials" icon="key" href="/baas/api/getting-started/quick-start/get-credentials">
    Step 1
  </Card>
  <Card title="Authenticate" icon="lock" href="/baas/api/getting-started/quick-start/authenticate">
    Step 2
  </Card>
  <Card title="First Call" icon="code" href="/baas/api/getting-started/quick-start/first-call">
    Step 3
  </Card>
</CardGroup>

## Base URLs

| Environment | URL |
|-------------|-----|
| **Sandbox** | `https://gateway.finhub.cloud/sandbox` |
| **Production** | `https://gateway.finhub.cloud/api` |

## Next Steps

After completing the quick start:

- Explore the [Development Environment](/baas/api/development)
- Review [Integration Guides](/baas/api/integration/flows)
- Browse the [API Reference](/baas/api/reference)


---

# Registration

Register as a FinHub API client


URL: /baas/api/getting-started/registration



# Registration

Register as a FinHub API client to access our financial services APIs.

## Registration Process

1. **Application**: Submit application on Developer Portal
2. **Review**: FinHub reviews your application
3. **Agreement**: Sign API client agreement
4. **Compliance**: Pass initial compliance check
5. **Approval**: Receive sandbox access

## Required Information

| Category | Details |
|----------|---------|
| **Company** | Legal name, registration, address |
| **Business** | Business model, use case description |
| **Technical** | Technical contact, integration plans |
| **Compliance** | Regulatory status, licenses (if any) |

## Compliance Check

Initial compliance verification includes:

- Company verification
- Business model review
- Regulatory assessment
- AML/CFT screening

## After Approval

Upon approval, you receive:

- Sandbox tenant credentials
- Developer Portal access
- API documentation access
- Support channel access

## Next Steps

<Card title="Product Selection" icon="box" href="/baas/api/getting-started/product-selection">
  Choose your products
</Card>


---

# Sandbox Access

Get sandbox access for API development


URL: /baas/api/getting-started/sandbox-access



# Sandbox Access

Access the FinHub sandbox environment to develop and test your integration.

## Getting Sandbox Credentials

After registration approval:

1. Log into the Developer Portal
2. Navigate to "Sandbox" section
3. Create a new sandbox tenant
4. Generate API credentials

## Sandbox Credentials

You'll receive:

| Credential | Purpose |
|------------|---------|
| **Tenant ID** | Your tenant identifier |
| **Client ID** | API authentication |
| **Client Secret** | API authentication (keep secure) |
| **Username/Password** | Portal access |

## Sandbox Environment

The sandbox provides:

- Full API access (same as production)
- Simulated financial transactions
- Test data generation
- No real money movement
- Isolated from production

## Sandbox Limitations

| Aspect | Limitation |
|--------|------------|
| **Transaction Limits** | Lower than production |
| **Data Retention** | Periodic cleanup |
| **External Services** | Test/mock environments |

## Next Steps

<Card title="Quick Start" icon="bolt" href="/baas/api/getting-started/quick-start">
  Make your first API call
</Card>


---

# Integration Guide

Complete API integration guide from onboarding to go-live


URL: /baas/api/integration



# Integration Guide

Comprehensive guide to integrating with FinHub APIs.

## Integration Journey

<Steps>
  <Step title="Onboard as Tenant">
    Register and configure your tenant
  </Step>
  <Step title="Understand Architecture">
    Learn the API architecture and patterns
  </Step>
  <Step title="Implement Core Flows">
    Build customer onboarding, accounts, transactions
  </Step>
  <Step title="Test & Certify">
    Complete testing and certification
  </Step>
  <Step title="Go to Production">
    Deploy to production
  </Step>
</Steps>

## Guide Sections

<CardGroup cols={2}>
  <Card title="Onboarding as Tenant" icon="user-plus" href="/baas/api/integration/onboarding">
    Tenant setup process
  </Card>
  <Card title="Architecture" icon="sitemap" href="/baas/api/integration/architecture">
    API design patterns
  </Card>
  <Card title="Core Flows" icon="arrows-rotate" href="/baas/api/integration/flows">
    Integration flows
  </Card>
</CardGroup>

## Core Integration Flows

| Flow | Description |
|------|-------------|
| **Customer Onboarding** | B2C and B2B registration, KYC/KYB |
| **Account Management** | Create and manage accounts |
| **Transactions** | Payments, transfers, SEPA, SWIFT |

## Integration Principles

- **Idempotency**: Use idempotency keys for safe retries
- **Webhooks**: Subscribe to events for async operations
- **Error Handling**: Implement proper error handling
- **Rate Limits**: Respect API rate limits


---

# Categorization Hierarchy

Customer and account categorization


URL: /baas/api/integration/onboarding/categorization-hierarchy



# Categorization Hierarchy

Understand customer and account categorization.

## Hierarchy Structure

```
Tenant
├── Customer (B2C/B2B)
│   ├── Account
│   │   ├── Sub-account
│   │   └── Beneficiaries
│   └── Cards
└── Settings
```

## Customer Types

| Type | Description |
|------|-------------|
| **B2C** | Individual customers |
| **B2B** | Business customers |

## Account Categories

| Category | Description |
|----------|-------------|
| **Current** | Transaction accounts |
| **Savings** | Savings accounts |
| **Multi-currency** | Multi-currency wallets |

## Usage

- Categorization affects permissions
- Determines available operations
- Influences compliance requirements


---

# Compliance Requirements

Regulatory compliance requirements for tenants


URL: /baas/api/integration/onboarding/compliance-requirements



# Compliance Requirements

Regulatory requirements for FinHub tenants.

## KYB Requirements

| Requirement | Description |
|-------------|-------------|
| **Company Verification** | Verify legal entity |
| **Director Verification** | KYC on directors |
| **UBO Identification** | Ultimate beneficial owners |
| **License Verification** | Regulatory licenses |

## Ongoing Compliance

- Transaction monitoring
- Suspicious activity reporting
- Periodic reviews
- Regulatory reporting

## Your Responsibilities

- End-customer KYC/KYB
- AML screening
- Data protection (GDPR)
- Record keeping

## FinHub Support

- Compliance tools and APIs
- Screening services
- Reporting templates
- Compliance guidance


---

# Onboarding as Tenant

Tenant setup and onboarding process


URL: /baas/api/integration/onboarding



# Onboarding as Tenant

Complete the tenant onboarding process to access FinHub APIs.

## Onboarding Steps

<Steps>
  <Step title="Tenant Registration">
    Submit business information and documentation
  </Step>
  <Step title="Compliance Requirements">
    Complete KYB and regulatory requirements
  </Step>
  <Step title="Select Products">
    Choose FinHub products for your integration
  </Step>
  <Step title="Receive Credentials">
    Get API credentials and sandbox access
  </Step>
</Steps>

## Timeline

| Phase | Duration |
|-------|----------|
| Registration | 1-2 days |
| Compliance Review | 3-5 days |
| Product Setup | 1-2 days |
| **Total** | **1-2 weeks** |

## Next Steps

<CardGroup cols={2}>
  <Card title="Tenant Registration" icon="building" href="/baas/api/integration/onboarding/tenant-registration">
    Start registration
  </Card>
  <Card title="Compliance" icon="shield" href="/baas/api/integration/onboarding/compliance-requirements">
    Compliance requirements
  </Card>
</CardGroup>


---

# Receiving Credentials

Receive your API credentials


URL: /baas/api/integration/onboarding/receiving-credentials



# Receiving Credentials

After approval, receive your API credentials.

## Credentials Provided

| Credential | Description |
|------------|-------------|
| **Tenant ID** | Your organization identifier |
| **Client ID** | API client identifier |
| **Client Secret** | API client secret |
| **Username** | Sandbox login |
| **Password** | Sandbox password |

## Delivery

Credentials are sent via:
- Secure email
- Developer Portal access

## Security

- Store credentials securely
- Never commit to source control
- Use environment variables
- Rotate periodically

## Next Steps

1. Configure your environment
2. Authenticate with sandbox
3. Make your first API call


---

# Selecting Products

Choose FinHub products for your integration


URL: /baas/api/integration/onboarding/selecting-products



# Selecting Products

Choose the FinHub products for your integration.

## Available Products

| Product | Description |
|---------|-------------|
| **FinCore™** | Core banking |
| **FinTrans™** | Payments |
| **FinCard™** | Card issuing |
| **FinCheck™** | KYC/KYB |
| **FinPOS™** | Acquiring |
| **FinExE™** | Exchange |

## Selection Considerations

- Business requirements
- Customer types (B2C, B2B)
- Geographic coverage
- Transaction volumes
- Compliance needs

## Product Bundles

Common combinations:
- **Banking**: FinCore + FinTrans
- **Cards**: FinCore + FinCard
- **Full Suite**: All products


---

# Tenant Registration

Register as a FinHub tenant


URL: /baas/api/integration/onboarding/tenant-registration



# Tenant Registration

Register your organization as a FinHub tenant.

## Required Information

| Category | Details |
|----------|----------|
| **Company** | Legal name, registration number, address |
| **Contacts** | Primary contact, technical contact |
| **Business** | Use case, expected volumes |
| **Regulatory** | Licenses, jurisdiction |

## Registration Process

1. Submit registration form
2. Provide documentation
3. FinHub review (3-5 days)
4. Approval notification
5. Receive credentials

## Required Documents

- Certificate of incorporation
- Proof of address
- Director identification
- UBO declaration
- License (if applicable)

## Contact

For registration: sales@finhub.cloud


---

# Add beneficiary (account)

Create a beneficiary for a FinTrans account using the Step 10 integration payload.


URL: /baas/api/reference/financial-operations/beneficiaries/add-beneficiary



## Endpoint

`POST /api/v2.1/fintrans/{accountId}/beneficiaries`

This endpoint adds a beneficiary to a specific FinTrans account. The sample below is aligned with `step10-add-beneficiary.json`.

## Sample cURL

```bash
curl --request POST \
  --url "https://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/beneficiaries" \
  --header "Authorization: Bearer <ACCESS_TOKEN>" \
  --header "X-Tenant-ID: <TENANT_ID>" \
  --header "X-Forwarded-For: 127.0.0.1" \
  --header "X-Forwarded-From: integration-client" \
  --header "platform: web" \
  --header "deviceId: integration-device" \
  --header "Content-Type: application/json" \
  --data '{
    "purposeCode": "SUPP",
    "postalCode": "LT-01103",
    "shortName": "",
    "bicSwiftCode": "SONCLT21",
    "lastName": "Customer",
    "city": "Vilnius",
    "email": "customer.20260331114946-387074@testcorp.com",
    "bankName": "UAB Sonect Europe",
    "currency": "EUR",
    "country": "LT",
    "networkName": "SEPA",
    "firstName": "John",
    "bankAddress": "Gedimino pr. 20, Vilnius, Lithuania",
    "customerId": "2dac1793-ab48-420c-b0b5-01292302e188",
    "addressLine1": "1 Test Street",
    "partyType": "INDIVIDUAL_CUSTOMER",
    "iban": "LT213320011000055860",
    "companyName": ""
  }'
```

## Example success response

```json
{
  "code": 200,
  "data": {
    "id": "3114774a-aa94-4648-9e57-5ff226ef02dd",
    "name": "",
    "iban": "LT213320011000055860",
    "type": "INDIVIDUAL_CUSTOMER",
    "status": "ACTIVE",
    "currency": "EUR",
    "country": "",
    "email": "",
    "phoneNumber": "",
    "shortName": "",
    "networkName": "SEPA",
    "bankName": "",
    "purposeCode": "",
    "assetId": "eba40e17-e539-430e-a6cc-2b0f01e4c86e"
  },
  "message": "Success"
}
```


---

# Create beneficiary (nested request)


URL: /baas/api/reference/financial-operations/beneficiaries/create-nested



## Sample cURL

```bash
curl --request POST \
  --url 'https://sandbox.finhub.cloud/api/v2.1/fintrans/beneficiaries' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'X-Tenant-Id: <TENANT_ID>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'User-Agent: <USER_AGENT>' \
  --header 'X-Forwarded-From: <FORWARDED_FROM>' \
  --header 'platform: Web' \
  --header 'deviceId: <DEVICE_ID>' \
  --data '{
    "beneficiary": {
      "type": "SEPA",
      "name": "Partner GmbH",
      "iban": "DE89370400440532013000",
      "bicSwiftCode": "DEUTDEFF"
    }
  }'
```


---

# Create beneficiary


URL: /baas/api/reference/financial-operations/beneficiaries/create



## Sample cURL

```bash
curl --request POST \
  --url 'https://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/beneficiaries' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'X-Tenant-Id: <TENANT_ID>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'User-Agent: <USER_AGENT>' \
  --header 'X-Forwarded-From: <FORWARDED_FROM>' \
  --header 'platform: Web' \
  --header 'deviceId: <DEVICE_ID>' \
  --data '{
    "name": "Acme Corporation",
    "shortName": "Acme Corp",
    "iban": "DE89370400440532013000",
    "bicSwiftCode": "DEUTDEFF",
    "currency": "EUR",
    "country": "DE",
    "networkName": "SEPA",
    "bankName": "Deutsche Bank AG",
    "bankAddress": "Taunusanlage 12, 60325 Frankfurt am Main, Germany",
    "purposeCode": "SUPP",
    "email": "finance@acme.com",
    "phoneNumber": "+4912345678"
  }'
```

## Response Example

```json
{
  "code": 200,
  "data": {
    "id": "df019bb3-ad7f-440c-ba01-b79e27ef8a3f",
    "name": "Acme Corporation",
    "shortName": "Acme Corp",
    "iban": "DE89370400440532013000",
    "status": "ACTIVE",
    "currency": "EUR",
    "country": "DE",
    "networkName": "SEPA",
    "bankName": "Deutsche Bank AG",
    "email": "finance@acme.com",
    "phoneNumber": "+4912345678",
    "purposeCode": "SUPP"
  },
  "message": "Success"
}
```

<Note>
  The returned `id` is the beneficiaryId used in subsequent transfer operations (prepare/execute).
</Note>


---

# Delete beneficiary


URL: /baas/api/reference/financial-operations/beneficiaries/delete



## Sample cURL

```bash
curl --request DELETE \
  --url 'https://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/beneficiaries/{beneficiaryId}' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'X-Tenant-Id: <TENANT_ID>' \
  --header 'Accept: application/json' \
  --header 'User-Agent: <USER_AGENT>' \
  --header 'X-Forwarded-From: <FORWARDED_FROM>' \
  --header 'platform: Web' \
  --header 'deviceId: <DEVICE_ID>'
```


---

# Beneficiaries

Manage payment beneficiaries for FinTrans operations


URL: /baas/api/reference/financial-operations/beneficiaries


---
title: 'Beneficiaries'
description: 'Manage payment beneficiaries for FinTrans operations'
---

# Beneficiaries

<CardGroup cols={2}>
  <Card title="List beneficiaries" href="/baas/api/reference/financial-operations/beneficiaries/list">
    `GET /api/v2.1/fintrans/{accountId}/beneficiaries`
  </Card>
  <Card title="Create beneficiary" href="/baas/api/reference/financial-operations/beneficiaries/create">
    `POST /api/v2.1/fintrans/{accountId}/beneficiaries`
  </Card>
  <Card title="Delete beneficiary" href="/baas/api/reference/financial-operations/beneficiaries/delete">
    `DELETE /api/v2.1/fintrans/{accountId}/beneficiaries/{beneficiaryId}`
  </Card>
  <Card title="Create beneficiary (nested)" href="/baas/api/reference/financial-operations/beneficiaries/create-nested">
    `POST /api/v2.1/fintrans/beneficiaries`
  </Card>
  <Card title="Update beneficiary" href="/baas/api/reference/financial-operations/beneficiaries/update">
    `PUT /api/v2.1/fintrans/beneficiaries/{beneficiaryId}`
  </Card>
</CardGroup>


---

# List beneficiaries


URL: /baas/api/reference/financial-operations/beneficiaries/list



## Sample cURL

```bash
curl --request GET \
  --url 'https://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/beneficiaries' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'X-Tenant-Id: <TENANT_ID>' \
  --header 'Accept: application/json' \
  --header 'User-Agent: <USER_AGENT>' \
  --header 'X-Forwarded-From: <FORWARDED_FROM>' \
  --header 'platform: Web' \
  --header 'deviceId: <DEVICE_ID>'
```


---

# Update beneficiary


URL: /baas/api/reference/financial-operations/beneficiaries/update



## Sample cURL

```bash
curl --request PUT \
  --url 'https://sandbox.finhub.cloud/api/v2.1/fintrans/beneficiaries/{beneficiaryId}' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'X-Tenant-Id: <TENANT_ID>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'User-Agent: <USER_AGENT>' \
  --header 'X-Forwarded-From: <FORWARDED_FROM>' \
  --header 'platform: Web' \
  --header 'deviceId: <DEVICE_ID>' \
  --data '{
    "beneficiary": {
      "shortName": "Partner GmbH (Updated)",
      "email": "finance@partner.de"
    }
  }'
```


---

# Cancel order


URL: /baas/api/reference/financial-operations/orders/cancel



## Sample cURL

```bash
curl --request DELETE \
  --url 'https://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/orders/{orderId}' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'X-Tenant-Id: <TENANT_ID>' \
  --header 'Accept: application/json' \
  --header 'X-Forwarded-From: <FORWARDED_FROM>' \
  --header 'deviceId: <DEVICE_ID>'
```


---

# Get order details


URL: /baas/api/reference/financial-operations/orders/get



## Sample cURL

```bash
curl --request GET \
  --url 'https://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/orders/{orderId}' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'X-Tenant-Id: <TENANT_ID>' \
  --header 'Accept: application/json' \
  --header 'X-Forwarded-From: <FORWARDED_FROM>' \
  --header 'deviceId: <DEVICE_ID>'
```


---

# Orders

List, view, and cancel FinTrans orders


URL: /baas/api/reference/financial-operations/orders


---
title: 'Orders'
description: 'List, view, and cancel FinTrans orders'
---

# Orders

<CardGroup cols={2}>
  <Card title="List orders" href="/baas/api/reference/financial-operations/orders/list">
    `GET /api/v2.1/fintrans/{accountId}/orders`
  </Card>
  <Card title="Get order details" href="/baas/api/reference/financial-operations/orders/get">
    `GET /api/v2.1/fintrans/{accountId}/orders/{orderId}`
  </Card>
  <Card title="Cancel order" href="/baas/api/reference/financial-operations/orders/cancel">
    `DELETE /api/v2.1/fintrans/{accountId}/orders/{orderId}`
  </Card>
</CardGroup>


---

# List orders


URL: /baas/api/reference/financial-operations/orders/list



## Sample cURL

```bash
curl --request GET \
  --url 'https://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/orders?limit=50&offset=0' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'X-Tenant-Id: <TENANT_ID>' \
  --header 'Accept: application/json' \
  --header 'User-Agent: <USER_AGENT>' \
  --header 'X-Forwarded-From: <FORWARDED_FROM>' \
  --header 'platform: Web' \
  --header 'deviceId: <DEVICE_ID>'
```


---

# Create payment consent


URL: /baas/api/reference/financial-operations/payment-consents/create



## Sample cURL

```bash
curl --request POST \
  --url 'https://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/payment-consents/types/{operationType}' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'X-Tenant-Id: <TENANT_ID>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'User-Agent: <USER_AGENT>' \
  --header 'X-Forwarded-From: <FORWARDED_FROM>' \
  --header 'platform: Web' \
  --header 'deviceId: <DEVICE_ID>' \
  --data '{
    "paymentType": "TRANSFER",
    "title": "Payment Consent for Transfer Operations",
    "description": "Consent for processing transfer transactions",
    "parameters": {
      "validity": {
        "startDate": "2026-01-01",
        "endDate": "2027-12-31",
        "maxUsageCount": 500
      },
      "beneficiaries": {
        "allowNewBeneficiaries": false,
        "requireBeneficiaryName": true,
        "allowedAccounts": [
          "DE89370400440532013000",
          "FR1420041010050500013M02606"
        ],
        "allowedTypes": ["SEPA", "INTERNAL"]
      },
      "limits": {
        "maxAmountPerTransaction": { "amount": 10000, "currency": "EUR" },
        "maxAmountPerDay": { "amount": 50000, "currency": "EUR" },
        "maxTransactionsPerDay": 50
      }
    }
  }'
```

## Response Example

```json
{
  "code": 200,
  "data": {
    "consentId": "d519e2da-0084-4021-b98e-4de7ecf2551e",
    "operationType": "TRANSFER",
    "status": "APPROVED",
    "accountId": "d7d94804-4d8b-45af-862f-77cbcef740f4",
    "message": "Consent created successfully",
    "magicLinkToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "message": "Success"
}
```

<Note>
  The `magicLinkToken` JWT contains an `answer` field with the authentication code needed for executing the prepared order. The `consentId` must be referenced when preparing and executing financial operations.
</Note>


---

# Get payment consent


URL: /baas/api/reference/financial-operations/payment-consents/get



## Sample cURL

```bash
curl --request GET \
  --url 'https://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/payment-consents/{consentId}' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'X-Tenant-Id: <TENANT_ID>' \
  --header 'Accept: application/json' \
  --header 'X-Forwarded-From: <FORWARDED_FROM>' \
  --header 'deviceId: <DEVICE_ID>'
```


---

# Payment consents

Create, get, and revoke payment consents


URL: /baas/api/reference/financial-operations/payment-consents


---
title: 'Payment consents'
description: 'Create, get, and revoke payment consents'
---

# Payment consents

<CardGroup cols={2}>
  <Card title="Create payment consent" href="/baas/api/reference/financial-operations/payment-consents/create">
    `POST /api/v2.1/fintrans/{accountId}/payment-consents/types/{operationType}`
  </Card>
  <Card title="Get payment consent" href="/baas/api/reference/financial-operations/payment-consents/get">
    `GET /api/v2.1/fintrans/{accountId}/payment-consents/{consentId}`
  </Card>
  <Card title="Revoke payment consent" href="/baas/api/reference/financial-operations/payment-consents/revoke">
    `DELETE /api/v2.1/fintrans/{accountId}/payment-consents/{consentId}`
  </Card>
</CardGroup>


---

# Revoke payment consent


URL: /baas/api/reference/financial-operations/payment-consents/revoke



## Sample cURL

```bash
curl --request DELETE \
  --url 'https://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/payment-consents/{consentId}' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'X-Tenant-Id: <TENANT_ID>' \
  --header 'Accept: application/json' \
  --header 'X-Forwarded-From: <FORWARDED_FROM>' \
  --header 'deviceId: <DEVICE_ID>'
```


---

# Execute prepared operation


URL: /baas/api/reference/financial-operations/prepare-execute/execute



## Sample cURL

```bash
curl --request POST \
  --url 'https://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/types/{operationType}/execute' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'X-Tenant-Id: <TENANT_ID>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'User-Agent: <USER_AGENT>' \
  --header 'X-Forwarded-From: <FORWARDED_FROM>' \
  --header 'platform: Web' \
  --header 'deviceId: <DEVICE_ID>' \
  --data '{
    "preparedOrderId": "2c879a04-3b84-4654-b65e-d01a2275f720",
    "authenticationCode": "127255",
    "consentConfirmation": {
      "confirmed": true,
      "consentId": "d519e2da-0084-4021-b98e-4de7ecf2551e",
      "channel": "WEB",
      "signature": "integration-test-signature"
    }
  }'
```

## Response Example

```json
{
  "code": 200,
  "data": {
    "orderId": "2c879a04-3b84-4654-b65e-d01a2275f720",
    "status": "COMPLETED",
    "transactionId": "txn_abc123"
  },
  "message": "Success"
}
```

<Note>
  The `authenticationCode` is extracted from the `magicLinkToken` JWT returned during payment consent creation (decode the JWT and extract the `answer` field). The `preparedOrderId` comes from the prepare endpoint response. This endpoint supports both B2B and B2C customers.
</Note>


---

# Prepare / execute

Core flow for preparing and executing financial operations


URL: /baas/api/reference/financial-operations/prepare-execute


---
title: 'Prepare / execute'
description: 'Core flow for preparing and executing financial operations'
---

# Prepare / execute

<CardGroup cols={2}>
  <Card title="Prepare operation" href="/baas/api/reference/financial-operations/prepare-execute/prepare">
    `POST /api/v2.1/fintrans/{accountId}/types/{operationType}/prepare`
  </Card>
  <Card title="Execute operation" href="/baas/api/reference/financial-operations/prepare-execute/execute">
    `POST /api/v2.1/fintrans/{accountId}/types/{operationType}/execute`
  </Card>
</CardGroup>


---

# Prepare financial operation


URL: /baas/api/reference/financial-operations/prepare-execute/prepare



## Sample cURL

```bash
curl --request POST \
  --url 'https://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/types/{operationType}/prepare' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'X-Tenant-Id: <TENANT_ID>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'User-Agent: <USER_AGENT>' \
  --header 'X-Forwarded-From: <FORWARDED_FROM>' \
  --header 'platform: Web' \
  --header 'deviceId: <DEVICE_ID>' \
  --data '{
    "beneficiaryId": "0904e2cc-f21d-4d55-b754-2faffe9656e8",
    "target": {
      "name": "Acme Corporation",
      "iban": "DE89370400440532013000"
    },
    "amount": {
      "value": "100000",
      "currency": "EUR",
      "scale": 2
    },
    "description": "Payment to supplier",
    "consent": {
      "consentReference": "d519e2da-0084-4021-b98e-4de7ecf2551e"
    }
  }'
```

## Response Example

```json
{
  "code": 200,
  "data": {
    "preparedOrderId": "2c879a04-3b84-4654-b65e-d01a2275f720",
    "status": "READY"
  },
  "message": "Success"
}
```

<Note>
  The `preparedOrderId` must be used in the execute endpoint. The `beneficiaryId` comes from the beneficiary creation response, and `consentReference` is the `consentId` from payment consent creation.
</Note>


---

# Create purchase transfer (typed endpoint)


URL: /baas/api/reference/financial-operations/transfers/create-purchase



## Sample cURL

```bash
curl --request POST \
  --url 'https://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/transfers/types.purchase' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'X-Tenant-Id: <TENANT_ID>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'X-Forwarded-From: <FORWARDED_FROM>' \
  --header 'deviceId: <DEVICE_ID>' \
  --data '{
    "type": "PURCHASE",
    "amount": { "value": "1000", "currency": "EUR", "scale": 2 },
    "description": "Purchase"
  }'
```


---

# Create sale transfer (typed endpoint)


URL: /baas/api/reference/financial-operations/transfers/create-sale



## Sample cURL

```bash
curl --request POST \
  --url 'https://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/transfers/types.sale' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'X-Tenant-Id: <TENANT_ID>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'X-Forwarded-From: <FORWARDED_FROM>' \
  --header 'deviceId: <DEVICE_ID>' \
  --data '{
    "type": "SALE",
    "amount": { "value": "1000", "currency": "EUR", "scale": 2 },
    "description": "Sale"
  }'
```


---

# Create topup (typed endpoint)


URL: /baas/api/reference/financial-operations/transfers/create-topup



## Sample cURL

```bash
curl --request POST \
  --url 'https://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/transfers/types.topup' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'X-Tenant-Id: <TENANT_ID>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'X-Forwarded-From: <FORWARDED_FROM>' \
  --header 'deviceId: <DEVICE_ID>' \
  --data '{
    "type": "TOPUP",
    "amount": { "value": "5000000", "currency": "EUR", "scale": 2 },
    "sourceAccount": { "iban": "<EXTERNAL_SOURCE_IBAN>" },
    "description": "Incoming SEPA transfer"
  }'
```


---

# Create transfer (typed endpoint)


URL: /baas/api/reference/financial-operations/transfers/create-transfer



## Sample cURL

```bash
curl --request POST \
  --url 'https://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/transfers/types.transfer' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'X-Tenant-Id: <TENANT_ID>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'X-Forwarded-From: <FORWARDED_FROM>' \
  --header 'deviceId: <DEVICE_ID>' \
  --data '{
    "type": "TRANSFER",
    "amount": { "value": "10000", "currency": "EUR", "scale": 2 },
    "beneficiary": { "iban": "DE89370400440532013000", "name": "Partner GmbH" },
    "description": "External transfer"
  }'
```


---

# Create withdraw (typed endpoint)


URL: /baas/api/reference/financial-operations/transfers/create-withdraw



## Sample cURL

```bash
curl --request POST \
  --url 'https://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/transfers/types.withdraw' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'X-Tenant-Id: <TENANT_ID>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'X-Forwarded-From: <FORWARDED_FROM>' \
  --header 'deviceId: <DEVICE_ID>' \
  --data '{
    "type": "WITHDRAW",
    "amount": { "value": "10000", "currency": "EUR", "scale": 2 },
    "target": { "iban": "<TARGET_IBAN>", "name": "Target Account" },
    "description": "Withdrawal"
  }'
```


---

# Transfers (typed)

Typed transfer endpoints


URL: /baas/api/reference/financial-operations/transfers


---
title: 'Transfers (typed)'
description: 'Typed transfer endpoints'
---

# Transfers (typed)

<CardGroup cols={2}>
  <Card title="Create transfer" href="/baas/api/reference/financial-operations/transfers/create-transfer">
    `POST /api/v2.1/fintrans/{accountId}/transfers/types.transfer`
  </Card>
  <Card title="Create topup" href="/baas/api/reference/financial-operations/transfers/create-topup">
    `POST /api/v2.1/fintrans/{accountId}/transfers/types.topup`
  </Card>
  <Card title="Create withdraw" href="/baas/api/reference/financial-operations/transfers/create-withdraw">
    `POST /api/v2.1/fintrans/{accountId}/transfers/types.withdraw`
  </Card>
  <Card title="Create purchase" href="/baas/api/reference/financial-operations/transfers/create-purchase">
    `POST /api/v2.1/fintrans/{accountId}/transfers/types.purchase`
  </Card>
  <Card title="Create sale" href="/baas/api/reference/financial-operations/transfers/create-sale">
    `POST /api/v2.1/fintrans/{accountId}/transfers/types.sale`
  </Card>
</CardGroup>


---

# Verification of Payee (VoP)

Verify payee name and account details before payments


URL: /baas/api/reference/financial-operations/vop


---
title: 'Verification of Payee (VoP)'
description: 'Verify payee name and account details before payments'
---

# Verification of Payee (VoP)

<CardGroup cols={2}>
  <Card title="Verify payee" href="/baas/api/reference/financial-operations/vop/verify">
    `POST /api/v2.1/fintrans/vop/verify`
  </Card>
</CardGroup>


---

# Verify payee (VoP)


URL: /baas/api/reference/financial-operations/vop/verify



## Sample cURL

```bash
curl --request POST \
  --url 'https://sandbox.finhub.cloud/api/v2.1/fintrans/vop/verify' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'X-Tenant-Id: <TENANT_ID>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'X-Forwarded-From: <FORWARDED_FROM>' \
  --header 'deviceId: <DEVICE_ID>' \
  --data '{
    "iban": "DE89370400440532013000",
    "bic": "DEUTDEFF",
    "name": "Partner GmbH"
  }'
```


---

# Common Data Types

Shared data structures used across all FinHub API endpoints


URL: /baas/api/reference/schemas/common-types



# Common Data Types

This document describes common data structures used throughout the FinHub API. All endpoints follow these conventions unless explicitly documented otherwise.

<Info>
  **Purpose:** Standard data structures used across all FinHub API endpoints.
  
  Use these schemas for consistent request/response formatting.
</Info>

---

## BaseResponse&lt;T&gt;

**All API responses** are wrapped in this standard structure:

```typescript
interface BaseResponse<T> {
  code: number        // HTTP status code (200, 201, 400, 404, etc.)
  message: string     // Human-readable message
  data: T            // The actual response payload (generic type)
}
```

### Success Response Example

```json
{
  "code": 200,
  "message": "Success",
  "data": {
    "userId": "5887c98c-b5b1-4234-b819-a4987f54aa77",
    "email": "user@example.com",
    "status": "ACTIVE"
  }
}
```

### Error Response Example

```json
{
  "code": 400,
  "message": "Prepared order not found: prepared-order-123",
  "data": {
    "error": "Prepared order not found: prepared-order-123"
  }
}
```

<Warning>
  **Important:** Never expect direct data in responses. All responses are wrapped in `BaseResponse`.
  
  **Incorrect:**
  ```json
  { "userId": "123" }
  ```
  
  **Correct:**
  ```json
  { "code": 200, "message": "Success", "data": { "userId": "123" } }
  ```
</Warning>

---

## AmountDto

Financial amounts use **scaled integers** to avoid floating-point precision issues.

```typescript
AmountDto {
  value: string       // Scaled integer as string (e.g., "5000000")
  scale: number       // Number of decimal places (e.g., 2)
  currency?: string   // ISO 4217 currency code (e.g., "EUR")
}
```

### How It Works

The `value` field contains the amount multiplied by 10^scale:

- **€50,000.00** = `{ "value": "5000000", "scale": 2, "currency": "EUR" }`
- **€100.00** = `{ "value": "10000", "scale": 2, "currency": "EUR" }`
- **€0.01** = `{ "value": "1", "scale": 2, "currency": "EUR" }`

### Examples

#### Request with Amount

```json
{
  "amount": {
    "value": "5000000",
    "scale": 2,
    "currency": "EUR"
  },
  "description": "Incoming SEPA transfer"
}
```

#### Response with Amount

```json
{
  "code": 200,
  "message": "Success",
  "data": {
    "preparedOrderId": "666f111b-20fd-4756-b610-3ee24938e96a",
    "summary": {
      "amount": 100,
      "currency": "EUR",
      "totalAmount": 100
    }
  }
}
```

<Note>
  **Why Scaled Integers?**
  
  Floating-point numbers (like `1000.00`) can cause precision errors in financial calculations. 
  Scaled integers ensure exact arithmetic:
  - Addition: `"1000" + "500" = "1500"`
  - Subtraction: `"1000" - "500" = "500"`
  - Comparison: `"1000" > "500" = true`
</Note>

<Warning>
  **Common Mistake:**
  
  **Incorrect (using float):**
  ```json
  {
    "amount": {
      "value": 1000.00,
      "currency": "EUR"
    }
  }
  ```
  
  **Correct (using scaled integer):**
  ```json
  {
    "amount": {
      "value": "100000",
      "scale": 2,
      "currency": "EUR"
    }
  }
  ```
</Warning>

---

## AddressDto

Physical address structure used for customer registration and KYC.

```typescript
AddressDto {
  id?: string                // Optional ID for existing addresses
  type: AddressType          // "HOME" | "WORK" | "BILLING" | "SHIPPING"
  street: string             // Street address
  city: string               // City name
  postalCode: string         // Postal/ZIP code
  country: string            // ISO 3166-1 alpha-2 country code
  state?: string             // State/Province (optional)
  building?: string          // Building name/number (optional)
  apartment?: string         // Apartment/Unit number (optional)
  isPrimary: boolean         // Whether this is the primary address
}
```

### Example

```json
{
  "id": "6vsvy01jbzo",
  "type": "HOME",
  "street": "123 Medium Risk Street",
  "city": "Compliance City",
  "postalCode": "12345",
  "country": "LT",
  "isPrimary": true
}
```

### Address Types

| Type | Description |
|------|-------------|
| `HOME` | Residential address |
| `WORK` | Business/office address |
| `BILLING` | Billing address for invoices |
| `SHIPPING` | Delivery/shipping address |

---

## ContactDto

Contact information (email, phone, etc.) for customers.

```typescript
ContactDto {
  id?: string                // Optional ID for existing contacts
  type: ContactType          // "EMAIL" | "PHONE" | "MOBILE" | "FAX"
  value: string              // Contact value (email address, phone number, etc.)
  isPrimary: boolean         // Whether this is the primary contact method
  verified?: boolean         // Whether this contact has been verified (optional)
}
```

### Example

```json
{
  "id": "g4dh2ch831",
  "type": "EMAIL",
  "value": "marcus.jensen@example.com",
  "isPrimary": true,
  "verified": true
}
```

### Contact Types

| Type | Description | Format Example |
|------|-------------|----------------|
| `EMAIL` | Email address | `user@example.com` |
| `PHONE` | Landline phone | `+37060012345` |
| `MOBILE` | Mobile phone | `+37067890124` |
| `FAX` | Fax number | `+37060012399` |

---

## PersonDto

Personal information for individual customers, directors, shareholders, etc.

```typescript
PersonDto {
  id?: string                // Optional person ID
  firstName: string          // Given name(s)
  lastName: string           // Family name(s)
  middleName?: string        // Middle name(s) (optional)
  email: string              // Primary email address
  dateOfBirth: string        // ISO 8601 date (YYYY-MM-DD)
  nationality: string        // ISO 3166-1 alpha-2 country code
  gender?: Gender            // "MALE" | "FEMALE" | "OTHER" (optional)
  placeOfBirth?: string      // Birth city/location (optional)
  fullName?: string          // Full name display (optional)
  addresses?: AddressDto[]   // Array of addresses
  contacts?: ContactDto[]    // Array of contact methods
  documents?: DocumentDto[]  // Array of identity documents (optional)
}
```

### Example

```json
{
  "id": "the2r6zaa6",
  "firstName": "Marcus",
  "lastName": "Jensen",
  "email": "marcus.jensen@example.com",
  "dateOfBirth": "1990-05-15",
  "nationality": "LT",
  "gender": "MALE",
  "placeOfBirth": "Vilnius",
  "fullName": "Marcus Jensen",
  "addresses": [
    {
      "type": "HOME",
      "street": "123 Medium Risk Street",
      "city": "Compliance City",
      "postalCode": "12345",
      "country": "LT",
      "isPrimary": true
    }
  ],
  "contacts": [
    {
      "type": "EMAIL",
      "value": "marcus.jensen@example.com",
      "isPrimary": true
    }
  ]
}
```

---

## TelephoneNumberDto

Telephone number with metadata (used for organizations).

```typescript
TelephoneNumberDto {
  number: string             // E.164 format phone number
  country: string            // ISO 3166-1 alpha-2 country code
  phoneType: number          // 0=UNKNOWN, 1=MOBILE, 2=LANDLINE
  operator?: string          // Telecom operator (optional)
  purpose?: string           // Purpose (e.g., "personal", "business")
  isPrimary: boolean         // Whether this is the primary number
}
```

### Example

```json
{
  "number": "+37060012345",
  "country": "LT",
  "phoneType": 1,
  "operator": "Telia",
  "purpose": "personal",
  "isPrimary": true
}
```

---

## Standard HTTP Headers

### Request Headers

All API requests should include these headers:

| Header | Required | Description |
|--------|----------|-------------|
| `X-Tenant-ID` | Yes | Tenant identifier |
| `Authorization` | Yes | Bearer token from session login |
| `Content-Type` | Yes | `application/json` |
| `Accept` | Optional | `application/json` (default) |
| `X-Session-Id` | Conditional | Required for transfer operations |
| `X-User-ID` | Conditional | Required for some admin operations |
| `X-User-Roles` | Conditional | Comma-separated roles for authorization |

### Example Request Headers

```bash
curl -X POST "https://api.finhub.cloud/api/v2.1/customer/individual/registration" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJh..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ ... }'
```

---

## Standard Error Responses

### 400 Bad Request

```json
{
  "code": 400,
  "message": "Missing required role 'ADMIN_USER' for BUSINESS_TYPE_CLIENT_TO_TENANT organization. At least one employee must have this role.",
  "data": {
    "error": "Missing required role 'ADMIN_USER'"
  }
}
```

### 403 Forbidden

```json
{
  "code": 403,
  "message": "Access denied"
}
```

### 404 Not Found

```json
{
  "code": 404,
  "message": "Unable to find matching target resource method",
  "data": {
    "error": "Unable to find matching target resource method"
  }
}
```

### 500 Internal Server Error

```json
{
  "code": 500,
  "message": "Internal server error",
  "data": {
    "error": "An unexpected error occurred"
  }
}
```

---

## Enums Reference

### Gender

```typescript
enum Gender {
  MALE = "MALE",
  FEMALE = "FEMALE",
  OTHER = "OTHER"
}
```

### AddressType

```typescript
enum AddressType {
  HOME = "HOME",
  WORK = "WORK",
  BILLING = "BILLING",
  SHIPPING = "SHIPPING"
}
```

### ContactType

```typescript
enum ContactType {
  EMAIL = "EMAIL",
  PHONE = "PHONE",
  MOBILE = "MOBILE",
  FAX = "FAX"
}
```

### CustomerType

```typescript
enum CustomerType {
  CT_PERSON = "CT_PERSON",
  CT_ORGANIZATION = "CT_ORGANIZATION"
}
```

### CustomerStatus

```typescript
enum CustomerStatus {
  CS_REGISTRATION_COMPLETED = "CS_REGISTRATION_COMPLETED",
  CS_PENDING_ACTIVATION = "CS_PENDING_ACTIVATION",
  CS_ACTIVE = "CS_ACTIVE",
  CS_SUSPENDED = "CS_SUSPENDED",
  CS_CLOSED = "CS_CLOSED"
}
```

---

## Date and Time Formats

All dates and times use **ISO 8601** format:

| Type | Format | Example |
|------|--------|---------|
| **Date** | `YYYY-MM-DD` | `2026-01-13` |
| **DateTime** | `YYYY-MM-DDTHH:mm:ss.SSSZ` | `2026-01-13T19:21:47.631Z` |
| **DateTime (with timezone)** | `YYYY-MM-DDTHH:mm:ss.SSS+HH:mm` | `2026-01-12T22:21:56.903+03:00` |

### Examples

```json
{
  "dateOfBirth": "1990-05-15",
  "createdAt": "2026-01-12T19:21:59.019243Z",
  "expiresAt": "2027-01-12T22:21:53.254059600"
}
```

---

## Pagination (Future)

<Note>
  Pagination is not yet implemented in v2.1. All list endpoints currently return complete results.
  Future versions will support cursor-based pagination.
</Note>

---

## Validation Rules

### Email Format

- Must match RFC 5322 standard
- Example: `user@example.com`

### Phone Number Format

- Must use E.164 format
- Example: `+37060012345`

### Country Codes

- Must use ISO 3166-1 alpha-2 (2-letter codes)
- Examples: `LT`, `GB`, `DE`, `US`

### Currency Codes

- Must use ISO 4217 (3-letter codes)
- Examples: `EUR`, `USD`, `GBP`

---

## Related Resources

<CardGroup cols={2}>
  <Card title="Customer APIs" icon="user" href="/baas/api/reference/customer-apis/individual/registration">
    Customer registration and management
  </Card>
  <Card title="Financial Operations" icon="coins" href="/baas/api/reference/financial-operations/transfers">
    Transfers, payments, and wallet operations
  </Card>
  <Card title="Verification & Compliance" icon="shield-check" href="/baas/api/reference/verification-compliance/verification-management">
    KYC, AML, and compliance workflows
  </Card>
</CardGroup>



---

# baas/api/reference/schemas/required-headers-snippet


URL: /baas/api/reference/schemas/required-headers-snippet


{/* Tangly: ParamField is not in scope inside exported MDX functions — use plain markup. */}

export function HeaderRow({ name, children, required = false }) {
  return (
    <div style={{ marginBottom: "0.75rem" }}>
      <p style={{ margin: "0 0 0.25rem" }}>
        <code>{name}</code>
        {" "}
        <span style={{ opacity: 0.7 }}>string</span>
        {required ? <span style={{ color: "#B812D5" }}> required</span> : null}
      </p>
      <p style={{ margin: 0, opacity: 0.9 }}>{children}</p>
    </div>
  );
}

export function RequiredRunnerHeaders() {
  return (
    <>
      <HeaderRow name="X-Forwarded-For" required>
        Client source IP (runner default: <code>127.0.0.1</code>)
      </HeaderRow>
      <HeaderRow name="X-Tenant-ID" required>
        Tenant identifier
      </HeaderRow>
      <HeaderRow name="X-Forwarded-From" required>
        Client source identifier (runner default: <code>integration-client</code>)
      </HeaderRow>
      <HeaderRow name="platform" required>
        Client platform (runner default: <code>web</code>)
      </HeaderRow>
      <HeaderRow name="deviceId" required>
        Device identifier (runner default: <code>integration-device</code>)
      </HeaderRow>
      <HeaderRow name="Authorization" required>
        Bearer token
      </HeaderRow>
    </>
  );
}

export function RequiredRunnerHeadersWithUserContext() {
  return (
    <>
      <RequiredRunnerHeaders />
      <HeaderRow name="X-User-ID" required>
        User executing privileged organization action
      </HeaderRow>
      <HeaderRow name="X-User-Roles" required>
        Comma-separated roles (example: <code>ADMIN_USER,COMPLIANCE_OFFICER</code>)
      </HeaderRow>
    </>
  );
}


---

# Standard HTTP Headers

Required and optional HTTP headers for Finhub API requests


URL: /baas/api/reference/schemas/standard-headers



# Standard HTTP Headers

All Finhub API requests require specific HTTP headers for authentication, tenant identification, compliance tracking, and proper request handling.

## Required Headers

### Authorization

**Type:** `string`  
**Required:** Yes (except for public endpoints)  
**Format:** `Bearer <JWT_TOKEN>`

Bearer token for API authentication. Obtained from the session creation endpoint after successful login.

**Example:**
```
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

**When Required:**
- All authenticated API operations
- Customer operations (registration, verification, consents)
- Financial operations (transfers, beneficiaries, payment consents)
- Administrative operations

---

### X-Tenant-ID

**Type:** `string`  
**Required:** Yes (all endpoints)  
**Format:** Alphanumeric tenant identifier

Identifies the tenant context for multi-tenant operations. Must match the tenant associated with the authenticated user or admin token.

**Example:**
```
X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd
```

**Validation:**
- Must be a valid, active tenant identifier (UUID format)
- Must match the tenant context of the authenticated user
- Case-sensitive

---

### User-Agent

**Type:** `string`  
**Required:** Yes (all endpoints — enforced by global request filter)  
**Format:** Standard User-Agent string

Client application identifier including browser, mobile app, or SDK version. Used for security analysis, device fingerprinting, and compliance reporting.

**Examples:**
```
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36
User-Agent: FinhubApp/2.1.0 (iOS 15.0; iPhone13,2)
User-Agent: finhub-sdk-js/1.5.0 Node/18.12.0
```

**Format Guidelines:**
- **Browser:** Use standard browser User-Agent
- **Mobile Apps:** `{AppName}/{Version} ({OS} {OSVersion}; {DeviceModel})`
- **SDKs:** `finhub-sdk-{language}/{version} {runtime}/{runtime_version}`

**When Required:**
- Customer registration
- Session creation
- Consent acceptance
- Transaction operations
- Document uploads

**Security & Compliance:**
- Used for device fingerprinting and fraud detection
- Helps identify suspicious access patterns
- Required for security audit trails
- Analyzed for bot detection and abuse prevention

---

### Content-Type

**Type:** `string`  
**Required:** Yes (for requests with body)  
**Format:** MIME type

Specifies the media type of the request body.

**Common Values:**
```
Content-Type: application/json
Content-Type: multipart/form-data (for file uploads)
Content-Type: application/x-www-form-urlencoded
```

**Default:** `application/json` for all API endpoints unless otherwise specified.

---

### X-Forwarded-From

**Type:** `string`  
**Required:** Yes  
**Format:** Source identifier string

Identifies the originating source of the request for tracking and routing purposes.

**Example:**
```
X-Forwarded-From: e2e-test
```

**When Required:**
- All API requests through the BFF layer
- Helps identify the upstream caller (frontend app, test suite, integration partner)

---

### platform

**Type:** `string`  
**Required:** Yes (all endpoints — enforced by global request filter)  
**Format:** Platform identifier

Identifies the client platform making the request. Used for analytics, feature gating, and device-specific behavior.

<Info>
  **Accepted aliases:** The server also accepts `sec-ch-ua-platform` as an alternative header name. Either `platform` or `sec-ch-ua-platform` satisfies this requirement.
</Info>

**Example:**
```
platform: web
```

**Common Values:**
- `web` — Browser-based application
- `ios` — iOS mobile application
- `android` — Android mobile application

---

### deviceId

**Type:** `string`  
**Required:** Yes (all endpoints — enforced by global request filter)  
**Format:** Unique device identifier

Unique identifier for the device making the request. Used for session tracking, fraud detection, and device management.

<Info>
  **Accepted aliases:** The server also accepts `X-Device-Id` or `device-id` as alternative header names. Any one of `deviceId`, `X-Device-Id`, or `device-id` satisfies this requirement.
</Info>

**Example:**
```
deviceId: 356938035643809
```

**When Required:**
- All authenticated API operations
- Session creation and management
- Transaction operations

---

### sec-ch-ua-platform

**Type:** `string`  
**Required:** No (accepted as an alias for `platform`)  
**Format:** Client hint platform string

Browser client hint indicating the user's operating system platform. Automatically sent by modern browsers. This header is an accepted alias for the `platform` header — if `sec-ch-ua-platform` is present, the `platform` header requirement is satisfied.

**Example:**
```
sec-ch-ua-platform: "Windows"
```

**When Required:**
- Customer registration
- Session creation
- Account activation
- Verification operations
- Consent acceptance
- Transfer operations

---

## Contextual Headers

These headers are required only for specific endpoint groups.

### X-User-ID

**Type:** `string`  
**Required:** Conditional  
**Format:** User identifier string

Identifies the acting user within a customer or organization context. Required for operations that need user-level attribution.

**Example:**
```
X-User-ID: usr_a1b2c3d4
```

**When Required:**
- Consent acceptance
- Beneficiary management (create, delete)
- Payment consent management
- Order execution and cancellation
- Wallet operations (prepare, execute)
- Webhook subscription creation
- Verification approval

---

### X-Session-ID

**Type:** `string`  
**Required:** Conditional  
**Format:** Session identifier string

Identifies the current user session. Required for 2FA and session-bound operations.

**Example:**
```
X-Session-ID: sess_x1y2z3
```

**When Required:**
- 2FA code sending
- 2FA verification
- Session-bound CMS operations

---

### X-Organization-ID

**Type:** `string`  
**Required:** Conditional  
**Format:** Organization identifier string

Identifies the organization context for B2B operations. Required when acting within an organization scope.

**Example:**
```
X-Organization-ID: org_e5f6g7h8
```

**When Required:**
- Employee management (list, add)
- Director management
- Wallet balance queries (B2B)
- Customer transaction history (B2B)

---

### X-User-Roles

**Type:** `string`  
**Required:** Conditional  
**Format:** Comma-separated role list

Specifies the roles of the acting user. Required for operations that enforce role-based access.

**Example:**
```
X-User-Roles: ADMIN_USER,COMPLIANCE_OFFICER
```

**When Required:**
- Verification approval
- Employee management (add with role assignment)

---

### X-Consumer-ID

**Type:** `string`  
**Required:** Conditional  
**Format:** Consumer identifier string

Identifies the consumer context for wallet and transaction queries.

**Example:**
```
X-Consumer-ID: cons_i9j0k1l2
```

**When Required:**
- Customer transaction history
- Order detail retrieval

---

### X-Activity-ID

**Type:** `string`  
**Required:** Conditional  
**Format:** Activity tracking identifier

Tracks activity flow for password recovery and similar multi-step operations.

**Example:**
```
X-Activity-ID: act_m3n4o5p6
```

**When Required:**
- Password forgot flow

---

## Optional Headers

### Accept

**Type:** `string`  
**Required:** No (optional — defaults to `application/json`)  
**Default:** `application/json, text/plain, */*`  
**Format:** MIME type

Specifies the desired response format.

**Example:**
```
Accept: application/json, text/plain, */*
```

---

### X-Idempotency-Key

**Type:** `string`  
**Required:** No (recommended for financial operations)  
**Format:** UUID v4

Unique identifier for idempotent request handling. Prevents duplicate transaction processing.

**Example:**
```
X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
```

**When Recommended:**
- Payment transfers
- Beneficiary creation
- Payment consent creation
- Any operation that modifies financial state

**Behavior:**
- If a request with the same idempotency key is received within 24 hours, the original response is returned
- Prevents accidental duplicate transactions due to network issues or retries
- Key expires after 24 hours

---

### X-Request-ID

**Type:** `string`  
**Required:** No  
**Format:** UUID v4

Unique request identifier for tracing and debugging. Automatically generated if not provided.

**Example:**
```
X-Request-ID: 7c9e6679-7425-40de-944b-e07fc1f90ae7
```

**Use Cases:**
- Request tracing across microservices
- Debugging and troubleshooting
- Support ticket correlation

---

## SDK Implementation Examples

### JavaScript/TypeScript

```typescript
import axios from 'axios';

const finhubClient = axios.create({
  baseURL: 'https://sandbox.finhub.cloud/api/v2.1',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json, text/plain, */*',
    'X-Tenant-ID': process.env.FINHUB_TENANT_ID,
    'X-Forwarded-From': 'your-app-name',
    'platform': 'web',
    'deviceId': getDeviceId(),
  },
});

// Add interceptor for authentication
finhubClient.interceptors.request.use((config) => {
  const token = localStorage.getItem('authToken');
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  
  // Add compliance headers
  config.headers['User-Agent'] = 'finhub-sdk-js/1.5.0';
  
  return config;
});

// Example: Register customer
const registerCustomer = async (customerData) => {
  const response = await finhubClient.post('/customer/individual/registration', customerData);
  return response.data;
};
```

---

### Python

```python
import requests
import os
from typing import Dict, Any

class FinhubClient:
    def __init__(self, tenant_id: str, base_url: str = 'https://sandbox.finhub.cloud/api/v2.1'):
        self.base_url = base_url
        self.tenant_id = tenant_id
        self.session = requests.Session()
        self.session.headers.update({
            'Content-Type': 'application/json',
            'Accept': 'application/json, text/plain, */*',
            'X-Tenant-ID': tenant_id,
            'X-Forwarded-From': 'your-app-name',
            'platform': 'web',
            'deviceId': 'your-device-id',
        })
    
    def set_auth_token(self, token: str):
        self.session.headers['Authorization'] = f'Bearer {token}'
    
    def _add_compliance_headers(self, user_agent: str = None):
        """Add compliance-required headers"""
        if user_agent:
            self.session.headers['User-Agent'] = user_agent
        else:
            self.session.headers['User-Agent'] = 'finhub-sdk-python/1.5.0'
    
    def register_customer(self, customer_data: Dict[str, Any]) -> Dict[str, Any]:
        self._add_compliance_headers()
        response = self.session.post(
            f'{self.base_url}/customer/individual/registration',
            json=customer_data
        )
        response.raise_for_status()
        return response.json()

# Usage
client = FinhubClient(tenant_id='97e7ff29-15f3-49ef-9681-3bbfcce4f6cd')
client.set_auth_token('your_jwt_token')
result = client.register_customer(customer_data)
```

---

### Java

```java
import okhttp3.*;
import java.io.IOException;
import java.util.concurrent.TimeUnit;

public class FinhubClient {
    private final OkHttpClient client;
    private final String baseUrl;
    private final String tenantId;
    private String authToken;

    public FinhubClient(String tenantId) {
        this.baseUrl = "https://sandbox.finhub.cloud/api/v2.1";
        this.tenantId = tenantId;
        this.client = new OkHttpClient.Builder()
            .connectTimeout(30, TimeUnit.SECONDS)
            .readTimeout(30, TimeUnit.SECONDS)
            .build();
    }

    public void setAuthToken(String token) {
        this.authToken = token;
    }

    public Response registerCustomer(String customerJson) throws IOException {
        RequestBody body = RequestBody.create(
            customerJson,
            MediaType.parse("application/json")
        );

        Request request = new Request.Builder()
            .url(baseUrl + "/customer/individual/registration")
            .addHeader("Content-Type", "application/json")
            .addHeader("Accept", "application/json, text/plain, */*")
            .addHeader("X-Tenant-ID", tenantId)
            .addHeader("Authorization", "Bearer " + authToken)
            .addHeader("X-Forwarded-From", "your-app-name")
            .addHeader("User-Agent", "finhub-sdk-java/1.5.0")
            .addHeader("platform", "web")
            .addHeader("deviceId", "your-device-id")
            .post(body)
            .build();

        return client.newCall(request).execute();
    }
}
```

---

## Error Scenarios

### Missing Required Header

**Request:**
```bash
POST /customer/individual/registration
Content-Type: application/json
# Missing X-Tenant-ID, User-Agent
```

**Response:**
```json
{
  "success": false,
  "code": 400,
  "message": "Missing required header(s)",
  "data": {
    "platform_accepted": ["sec-ch-ua-platform", "platform"],
    "deviceId_accepted": ["deviceId", "X-Device-Id", "device-id"],
    "missingHeaders": ["User-Agent", "platform", "deviceId"]
  }
}
```

---

### Invalid Authorization Token

**Request:**
```bash
POST /customer/individual/activation
Authorization: Bearer invalid_token_here
X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd
```

**Response:**
```json
{
  "code": 401,
  "message": "Invalid or expired authentication token",
  "data": {
    "error": "INVALID_TOKEN"
  }
}
```

---

### Tenant Mismatch

**Request:**
```bash
POST /customer/individual/registration
Authorization: Bearer <token_for_tenant_A>
X-Tenant-ID: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
```

**Response:**
```json
{
  "code": 403,
  "message": "Tenant mismatch: token tenant does not match X-Tenant-ID header",
  "data": {
    "error": "TENANT_MISMATCH"
  }
}
```

---

## Security Best Practices

### Token Management

<Warning>
  - Never expose JWT tokens in client-side code or logs
  - Store tokens securely (HTTP-only cookies, secure storage)
  - Implement token refresh mechanism before expiry
  - Revoke tokens on logout
</Warning>

### User-Agent Best Practices

- Use descriptive User-Agent strings with version information
- Update User-Agent when releasing new app versions
- Include SDK version for better support diagnostics
- Avoid spoofing or randomizing User-Agent (triggers fraud detection)

---

## Compliance & Audit

### Data Captured

For each API request with compliance headers, the system captures:

| Field | Source | Purpose | Retention |
|-------|--------|---------|-----------|
| Client Source | `X-Forwarded-From` | Request origin tracking | 7 years |
| User Agent | `User-Agent` | Device fingerprinting, security | 7 years |
| Timestamp | System | Audit trail, compliance reporting | 7 years |
| Request ID | `X-Request-ID` or auto-generated | Tracing, debugging | 90 days |
| Tenant ID | `X-Tenant-ID` | Multi-tenant isolation | Permanent |
| User ID | JWT claims | User attribution | Permanent |

### Regulatory Compliance

The captured headers support compliance with:

- **GDPR (General Data Protection Regulation):** Right to audit, data processing records
- **PSD2 (Payment Services Directive 2):** Strong customer authentication
- **AML (Anti-Money Laundering):** Customer due diligence, transaction monitoring
- **KYC (Know Your Customer):** Identity verification, risk assessment
- **eIDAS (Electronic Identification):** Authentication and trust services

---

## Related Documentation

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="../authentication">
    JWT token management and session handling
  </Card>
  
  <Card title="Error Handling" icon="triangle-exclamation" href="../guides/error-handling">
    Common error codes and resolution strategies
  </Card>
  
  <Card title="Security Best Practices" icon="shield-halved" href="../guides/security">
    API security guidelines and recommendations
  </Card>
  
  <Card title="API Schema Mapping" icon="code" href="../../../docs/API_SCHEMA_MAPPING">
    Complete OpenAPI schema reference
  </Card>
</CardGroup>

---

## Changelog

| Version | Date | Changes |
|---------|------|---------|
| v2.1.1 | 2026-03-10 | Added X-Forwarded-From, platform, deviceId, sec-ch-ua-platform, X-User-ID, X-Session-ID, X-Organization-ID, X-User-Roles, X-Consumer-ID, X-Activity-ID headers; updated examples to UUID tenant IDs |
| v2.1.2 | 2026-03-14 | Removed X-Forwarded-For (CORS unsafe for browser clients); use X-Forwarded-From for client identification |
| v2.1 | 2026-01-13 | Added compliance headers (User-Agent) |
| v2.0 | 2025-12-01 | Initial multi-tenant support with X-Tenant-ID |


---

# B2B Channel

B2B distribution channel for business customers


URL: /baas/corex/features/b2b-channel



# B2B Distribution Channel

The B2B Distribution Channel provides interfaces for business customers with multi-user access and role-based permissions.

## Features

- **Business Registration**: Company onboarding with KYB
- **Multi-User Access**: Role-based permissions
- **Bulk Payments**: Batch payment processing
- **Business Accounts**: Corporate account management
- **Reporting**: Business analytics and reports
- **Integrations**: Accounting software connections

## Platform Options

| Platform | Description |
|----------|-------------|
| **Web** | Responsive browser application |
| **Android** | Native Android app |
| **iOS** | Native iOS app |

## Configuration Tiers

| Tier | Platforms | Features |
|------|-----------|----------|
| **Basic** | Web only | Essential business features |
| **Standard** | Web + 1 Mobile | Multi-user support |
| **Advanced** | All platforms | Accounting integrations |

## User Roles

- **Admin**: Full access, user management
- **Finance Manager**: Payments, reporting
- **Accountant**: View-only, exports
- **Employee**: Limited access

## Key Screens

- Business dashboard
- Account overview
- Batch payments
- User management
- Approval workflows
- Reports and exports


---

# B2C Channel

B2C distribution channel for individual customers


URL: /baas/corex/features/b2c-channel



# B2C Distribution Channel

The B2C Distribution Channel provides interfaces for individual customers to access financial services.

## Features

- **Customer Registration**: Self-service onboarding with KYC
- **Account Management**: View and manage accounts
- **Transaction History**: Statements and transaction details
- **Payments**: Send and receive money
- **Cards**: Virtual and physical card management
- **Settings**: Personal preferences and security

## Platform Options

| Platform | Description |
|----------|-------------|
| **Web** | Responsive browser application |
| **Android** | Native Android app |
| **iOS** | Native iOS app |

## Configuration Tiers

| Tier | Platforms | Features |
|------|-----------|----------|
| **Basic** | Web OR Mobile | Essential features |
| **Standard** | Web + 1 Mobile | Full feature set |
| **Advanced** | Web + Android + iOS | Biometric auth, offline |

## Key Screens

- Dashboard / Home
- Account overview
- Transaction list
- Payment initiation
- Card management
- Profile settings
- Help / Support


---

# Support Interface

Customer support interface for handling inquiries


URL: /baas/corex/features/support-interface



# Support Interface

The Customer Support Interface provides tools for handling customer inquiries and support tickets.

## Features

- **Ticket Management**: Create, track, resolve tickets
- **Customer Lookup**: Search and view customer details
- **Transaction Search**: Find specific transactions
- **Case Management**: Handle disputes and issues
- **Knowledge Base**: FAQ and help articles
- **Communication**: In-app messaging, email

## Support Capabilities

| Capability | Description |
|------------|-------------|
| **Customer Search** | Find customers by ID, email, phone |
| **Transaction Lookup** | Search transactions by reference |
| **Account Actions** | Freeze, unfreeze, update limits |
| **Document Review** | View KYC documents |
| **Audit Trail** | View customer activity history |

## Integration with Admin Panel

The Support Interface integrates with the Admin Panel for:

- Escalation workflows
- Compliance reviews
- Manual approvals
- Reporting


---

# Contact Sales

Start your CoreX journey by contacting our sales team


URL: /baas/corex/getting-started/contact-sales



# Contact Sales

The first step in your CoreX journey is engaging with our sales team to discuss your requirements.

## What to Prepare

Before contacting sales, consider:

- **Business Model**: What financial services will you offer?
- **Target Market**: B2C, B2B, or both?
- **Geographic Scope**: Which countries will you operate in?
- **Timeline**: When do you need to launch?
- **Budget**: Approximate budget range

## Discussion Topics

During the sales conversation, we'll cover:

| Topic | Details |
|-------|---------|
| **Requirements** | Your specific business needs and use cases |
| **Products** | Which FinHub products you need |
| **Subscription Tier** | Starter, Professional, Enterprise, or Custom |
| **White-Labeling** | Branding and customization requirements |
| **Compliance** | Regulatory requirements for your market |
| **Timeline** | Implementation and go-live schedule |

## Contact Options

<CardGroup cols={2}>
  <Card title="Email Sales" icon="envelope">
    [sales@finhub.cloud](mailto:sales@finhub.cloud)
  </Card>
  <Card title="Schedule a Call" icon="calendar">
    Book a consultation via our website
  </Card>
</CardGroup>

## What Happens Next

After initial contact:

1. **Discovery Call**: Detailed discussion of your requirements
2. **Proposal**: Custom proposal with pricing and timeline
3. **Agreement**: Contract signing and project kickoff
4. **Onboarding**: Begin the setup process

## Next Steps

<Card title="Select Products" icon="box" href="/baas/corex/getting-started/select-products">
  Learn about product selection
</Card>


---

# Quickstart Guide

Get started with FinHub API in 15 minutes


URL: /baas/quickstart



# FinHub API Quickstart Guide

Get your first customer registered, verified, and transacting in **15 minutes** with this step-by-step guide.

<Info>
  **All code examples in this guide are validated** with E2E integration tests.
  
  Expected success rate: **100%** when following exactly.
</Info>

---

## Prerequisites

<Check>
  **What you need:**
  
  - FinHub sandbox account
  - Organization ID and User ID
  - Tenant ID, Tenant Key, and Tenant Secret
  - Client ID and Client Secret (optional)
  - HTTP client or SDK
</Check>

### Get Your Credentials

1. Log in to [FinHub Admin Portal](https://admin.sandbox.finhub.cloud)
2. Navigate to **Settings → API Credentials**
3. Copy the following:
   - Organization ID: `f3a4b5c6-d7e8-49f0-1a2b-3c4d5e6f7a8b`
   - User ID: `e2f3a4b5-c6d7-48e9-0f1a-2b3c4d5e6f7a`
   - Tenant ID: `d1e2f3a4-b5c6-47d8-9e0f-1a2b3c4d5e6f`
   - Tenant Key: `cvK_9XDw5g_Y_8aUtRQgPyX4aTBb`
   - Tenant Secret: `[REDACTED]`

---

## Step 1: Authenticate (30 seconds)

Create an admin session to get your access token.

<CodeGroup>
```bash cURL
export ORG_ID="f3a4b5c6-d7e8-49f0-1a2b-3c4d5e6f7a8b"
export USER_ID="e2f3a4b5-c6d7-48e9-0f1a-2b3c4d5e6f7a"
export TENANT_ID="d1e2f3a4-b5c6-47d8-9e0f-1a2b3c4d5e6f"

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/admin/organization/$ORG_ID/users/$USER_ID/sessions" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin@yourcompany.com",
    "password": "your_password",
    "tenantKey": "cvK_9XDw5g_Y_8aUtRQgPyX4aTBb",
    "tenantSecret": "your_tenant_secret",
    "clientKeys": {
      "clientId": "cvK_9XDw5g_Y_8aUtRQgPyX4aTBb",
      "clientSecret": "your_client_secret"
    }
  }' | jq -r '.data.token' > token.txt

export TOKEN=$(cat token.txt)
echo "✅ Authenticated: $TOKEN"
```

```javascript JavaScript
const FinHubAPI = {
  baseURL: 'https://sandbox.finhub.cloud/api/v2.1',
  orgId: 'f3a4b5c6-d7e8-49f0-1a2b-3c4d5e6f7a8b',
  userId: 'e2f3a4b5-c6d7-48e9-0f1a-2b3c4d5e6f7a',
  tenantId: 'd1e2f3a4-b5c6-47d8-9e0f-1a2b3c4d5e6f',
  token: null
};

async function authenticate() {
  const response = await fetch(
    `${FinHubAPI.baseURL}/admin/organization/${FinHubAPI.orgId}/users/${FinHubAPI.userId}/sessions`,
    {
      method: 'POST',
      headers: {
        'X-Tenant-ID': FinHubAPI.tenantId,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        username: 'admin@yourcompany.com',
        password: process.env.ADMIN_PASSWORD,
        tenantKey: process.env.TENANT_KEY,
        tenantSecret: process.env.TENANT_SECRET,
        clientKeys: {
          clientId: process.env.CLIENT_ID,
          clientSecret: process.env.CLIENT_SECRET
        }
      })
    }
  );

  const result = await response.json();
  FinHubAPI.token = result.data.token;
  
  console.log('✅ Authenticated successfully');
  return FinHubAPI.token;
}

// Authenticated request helper
async function apiRequest(endpoint, options = {}) {
  const response = await fetch(`${FinHubAPI.baseURL}${endpoint}`, {
    ...options,
    headers: {
      'Authorization': `Bearer ${FinHubAPI.token}`,
      'X-Tenant-ID': FinHubAPI.tenantId,
      'Content-Type': 'application/json',
      ...options.headers
    }
  });
  
  return response.json();
}
```

```python Python
import requests
import os
from typing import Dict, Any

class FinHubAPI:
    def __init__(self):
        self.base_url = 'https://sandbox.finhub.cloud/api/v2.1'
        self.org_id = 'f3a4b5c6-d7e8-49f0-1a2b-3c4d5e6f7a8b'
        self.user_id = 'e2f3a4b5-c6d7-48e9-0f1a-2b3c4d5e6f7a'
        self.tenant_id = 'd1e2f3a4-b5c6-47d8-9e0f-1a2b3c4d5e6f'
        self.token = None
    
    def authenticate(self):
        url = f'{self.base_url}/admin/organization/{self.org_id}/users/{self.user_id}/sessions'
        
        response = requests.post(
            url,
            headers={
                'X-Tenant-ID': self.tenant_id,
                'Content-Type': 'application/json'
            },
            json={
                'username': 'admin@yourcompany.com',
                'password': os.getenv('ADMIN_PASSWORD'),
                'tenantKey': os.getenv('TENANT_KEY'),
                'tenantSecret': os.getenv('TENANT_SECRET'),
                'clientKeys': {
                    'clientId': os.getenv('CLIENT_ID'),
                    'clientSecret': os.getenv('CLIENT_SECRET')
                }
            }
        )
        
        data = response.json()['data']
        self.token = data['token']
        
        print('✅ Authenticated successfully')
        return self.token
    
    def request(self, method: str, endpoint: str, **kwargs) -> Dict[str, Any]:
        url = f'{self.base_url}{endpoint}'
        
        headers = {
            'Authorization': f'Bearer {self.token}',
            'X-Tenant-ID': self.tenant_id,
            'Content-Type': 'application/json'
        }
        
        if 'headers' in kwargs:
            headers.update(kwargs.pop('headers'))
        
        response = requests.request(method, url, headers=headers, **kwargs)
        return response.json()

# Initialize
api = FinHubAPI()
api.authenticate()
```
</CodeGroup>

**Expected Response:**
```json
{
  "code": 200,
  "message": "Success",
  "data": {
    "sessionId": "ed8e1ef7-d885-4753-88ad-afc5aedfac7b",
    "token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
    "refreshToken": "3c68d5a6-d567-4ec7...",
    "expiresAt": "2026-01-13T23:21:48.974Z"
  }
}
```

<Check>**Step complete!** You now have a bearer token valid for ~1 hour.</Check>

---

## Step 2: Get Categorization Hierarchy (1 minute)

Understand available customer risk categories before registration.

<CodeGroup>
```bash cURL
curl -X GET "https://sandbox.finhub.cloud/api/v2.1/customer/individual/categorization/hierarchy/$TENANT_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: $TENANT_ID" | jq '.data.categories'
```

```javascript JavaScript
const categories = await apiRequest(
  `/customer/individual/categorization/hierarchy/${FinHubAPI.tenantId}`
);

console.log('Available categories:', Object.keys(categories.data.categories));
// Output: ["LOW_RISK", "MEDIUM_RISK", "HIGH_RISK"]
```

```python Python
categories = api.request(
    'GET',
    f'/customer/individual/categorization/hierarchy/{api.tenant_id}'
)

print('Available categories:', list(categories['data']['categories'].keys()))
```
</CodeGroup>

**Expected Response (excerpt):**
```json
{
  "code": 200,
  "data": {
    "categories": {
      "LOW_RISK": {
        "id": "low-risk",
        "name": "Low Risk Customer",
        "limits": {
          "dailyTransactionLimit": { "value": "100000", "currency": "EUR", "scale": 2 },
          "monthlyTransactionLimit": { "value": "500000", "currency": "EUR", "scale": 2 }
        }
      },
      "MEDIUM_RISK": { ... },
      "HIGH_RISK": { ... }
    }
  }
}
```

<Check>**Step complete!** You can now choose appropriate categories for customers.</Check>

---

## Step 3: Register Individual Customer (2 minutes)

Create your first individual (B2C) customer.

<CodeGroup>
```bash cURL
# Generate unique email for testing
EMAIL="john.doe.$(date +%s)@example.com"

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/customer/individual/registration" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -H "Content-Type: application/json" \
  -d "{
    \"tenantId\": \"$TENANT_ID\",
    \"firstName\": \"John\",
    \"lastName\": \"Doe\",
    \"email\": \"$EMAIL\",
    \"phone\": \"+37060012345\",
    \"password\": \"SecurePass123!\",
    \"matchingPassword\": \"SecurePass123!\",
    \"roleIds\": [\"ACCOUNT_OWNER\", \"USER\"],
    \"individualCustomer\": {
      \"tenantId\": \"$TENANT_ID\",
      \"customerName\": \"John Doe\",
      \"person\": {
        \"firstName\": \"John\",
        \"lastName\": \"Doe\",
        \"email\": \"$EMAIL\",
        \"dateOfBirth\": \"1990-05-15\",
        \"gender\": \"MALE\",
        \"nationality\": \"LT\",
        \"addresses\": [
          {
            \"type\": \"HOME\",
            \"street\": \"123 Main Street\",
            \"city\": \"Vilnius\",
            \"postalCode\": \"12345\",
            \"country\": \"LT\",
            \"isPrimary\": true
          }
        ],
        \"contacts\": [
          {
            \"type\": \"EMAIL\",
            \"value\": \"$EMAIL\",
            \"isPrimary\": true
          }
        ]
      },
      \"user\": {
        \"username\": \"$EMAIL\",
        \"email\": \"$EMAIL\",
        \"password\": \"SecurePass123!\",
        \"status\": \"PENDING_ACTIVATION\",
        \"roles\": [\"ACCOUNT_OWNER\", \"USER\"],
        \"isActive\": false
      }
    }
  }" | jq -r '.data.customerId' > customer_id.txt

export CUSTOMER_ID=$(cat customer_id.txt)
echo "✅ Customer registered: $CUSTOMER_ID"
```

```javascript JavaScript
const timestamp = Date.now();
const email = `john.doe.${timestamp}@example.com`;

const customer = await apiRequest('/customer/individual/registration', {
  method: 'POST',
  body: JSON.stringify({
    tenantId: FinHubAPI.tenantId,
    firstName: 'John',
    lastName: 'Doe',
    email,
    phone: '+37060012345',
    password: 'SecurePass123!',
    matchingPassword: 'SecurePass123!',
    roleIds: ['ACCOUNT_OWNER', 'USER'],
    individualCustomer: {
      tenantId: FinHubAPI.tenantId,
      customerName: 'John Doe',
      person: {
        firstName: 'John',
        lastName: 'Doe',
        email,
        dateOfBirth: '1990-05-15',
        gender: 'MALE',
        nationality: 'LT',
        addresses: [{
          type: 'HOME',
          street: '123 Main Street',
          city: 'Vilnius',
          postalCode: '12345',
          country: 'LT',
          isPrimary: true
        }],
        contacts: [{
          type: 'EMAIL',
          value: email,
          isPrimary: true
        }]
      },
      user: {
        username: email,
        email,
        password: 'SecurePass123!',
        status: 'PENDING_ACTIVATION',
        roles: ['ACCOUNT_OWNER', 'USER'],
        isActive: false
      }
    }
  })
});

const customerId = customer.data.customerId;
console.log('✅ Customer registered:', customerId);
```

```python Python
import time

timestamp = int(time.time())
email = f'john.doe.{timestamp}@example.com'

customer = api.request(
    'POST',
    '/customer/individual/registration',
    json={
        'tenantId': api.tenant_id,
        'firstName': 'John',
        'lastName': 'Doe',
        'email': email,
        'phone': '+37060012345',
        'password': 'SecurePass123!',
        'matchingPassword': 'SecurePass123!',
        'roleIds': ['ACCOUNT_OWNER', 'USER'],
        'individualCustomer': {
            'tenantId': api.tenant_id,
            'customerName': 'John Doe',
            'person': {
                'firstName': 'John',
                'lastName': 'Doe',
                'email': email,
                'dateOfBirth': '1990-05-15',
                'gender': 'MALE',
                'nationality': 'LT',
                'addresses': [{
                    'type': 'HOME',
                    'street': '123 Main Street',
                    'city': 'Vilnius',
                    'postalCode': '12345',
                    'country': 'LT',
                    'isPrimary': True
                }],
                'contacts': [{
                    'type': 'EMAIL',
                    'value': email,
                    'isPrimary': True
                }]
            },
            'user': {
                'username': email,
                'email': email,
                'password': 'SecurePass123!',
                'status': 'PENDING_ACTIVATION',
                'roles': ['ACCOUNT_OWNER', 'USER'],
                'isActive': False
            }
        }
    }
)

customer_id = customer['data']['customerId']
print(f'✅ Customer registered: {customer_id}')
```
</CodeGroup>

**Expected Response:**
```json
{
  "code": 200,
  "message": "Success",
  "data": {
    "customerId": "5887c98c-b5b1-4234-b819-a4987f54aa77",
    "userId": "user_abc123",
    "email": "john.doe.1234567890@example.com",
    "status": "PENDING_ACTIVATION"
  }
}
```

<Check>**Step complete!** Customer created with ID `5887c98c-b5b1-4234-b819-a4987f54aa77`</Check>

---

## Step 4: Verify Customer (4 minutes)

Complete the KYC verification process.

### 4a. Create Identity Verification

<CodeGroup>
```bash cURL
curl -X POST "https://sandbox.finhub.cloud/api/v2.1/verifications" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -H "Content-Type: application/json" \
  -d "{
    \"customerId\": \"$CUSTOMER_ID\",
    \"requestedByTenantId\": \"$TENANT_ID\",
    \"type\": \"IDENTITY_VERIFICATION\",
    \"requestedLevel\": \"TENANT_VERIFIED\",
    \"requestedByUserId\": \"admin-user\"
  }" | jq -r '.data.id' > verification_id.txt

export VERIFICATION_ID=$(cat verification_id.txt)
echo "✅ Verification created: $VERIFICATION_ID"
```

```javascript JavaScript
const verification = await apiRequest('/verifications', {
  method: 'POST',
  body: JSON.stringify({
    customerId,
    requestedByTenantId: FinHubAPI.tenantId,
    type: 'IDENTITY_VERIFICATION',
    requestedLevel: 'TENANT_VERIFIED',
    requestedByUserId: 'admin-user'
  })
});

const verificationId = verification.data.id;
console.log('✅ Verification created:', verificationId);
```

```python Python
verification = api.request(
    'POST',
    '/verifications',
    json={
        'customerId': customer_id,
        'requestedByTenantId': api.tenant_id,
        'type': 'IDENTITY_VERIFICATION',
        'requestedLevel': 'TENANT_VERIFIED',
        'requestedByUserId': 'admin-user'
    }
)

verification_id = verification['data']['id']
print(f'✅ Verification created: {verification_id}')
```
</CodeGroup>

### 4b. Upload Document (Simplified for Sandbox)

<CodeGroup>
```bash cURL
# In sandbox, you can use a dummy document
curl -X POST "https://sandbox.finhub.cloud/api/v2.1/verifications/$VERIFICATION_ID/documents" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "documentType": "PASSPORT",
    "fileName": "passport.pdf",
    "fileContent": "JVBERi0xLjQKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwo+PgplbmRvYmoKdHJhaWxlcgo8PAovUm9vdCAxIDAgUgo+PgolJUVPRgo=",
    "mimeType": "application/pdf",
    "description": "Customer passport"
  }'

echo "✅ Document uploaded"
```

```javascript JavaScript
await apiRequest(`/verifications/${verificationId}/documents`, {
  method: 'POST',
  body: JSON.stringify({
    documentType: 'PASSPORT',
    fileName: 'passport.pdf',
    fileContent: 'JVBERi0xLjQKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwo+PgplbmRvYmoKdHJhaWxlcgo8PAovUm9vdCAxIDAgUgo+PgolJUVPRgo=',
    mimeType: 'application/pdf',
    description: 'Customer passport'
  })
});

console.log('✅ Document uploaded');
```

```python Python
api.request(
    'POST',
    f'/verifications/{verification_id}/documents',
    json={
        'documentType': 'PASSPORT',
        'fileName': 'passport.pdf',
        'fileContent': 'JVBERi0xLjQKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwo+PgplbmRvYmoKdHJhaWxlcgo8PAovUm9vdCAxIDAgUgo+PgolJUVPRgo=',
        'mimeType': 'application/pdf',
        'description': 'Customer passport'
    }
)

print('✅ Document uploaded')
```
</CodeGroup>

### 4c. Approve Verification

<CodeGroup>
```bash cURL
curl -X POST "https://sandbox.finhub.cloud/api/v2.1/verifications/$VERIFICATION_ID/approve" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "approvedBy": "admin-user",
    "adminNotes": "Document verified successfully"
  }'

echo "✅ Verification approved"
```

```javascript JavaScript
await apiRequest(`/verifications/${verificationId}/approve`, {
  method: 'POST',
  body: JSON.stringify({
    approvedBy: 'admin-user',
    adminNotes: 'Document verified successfully'
  })
});

console.log('✅ Verification approved');
```

```python Python
api.request(
    'POST',
    f'/verifications/{verification_id}/approve',
    json={
        'approvedBy': 'admin-user',
        'adminNotes': 'Document verified successfully'
    }
)

print('✅ Verification approved')
```
</CodeGroup>

<Check>**Step complete!** Customer is now TENANT_VERIFIED.</Check>

---

## Step 5: Create Account (1 minute)

Create a financial account (wallet) for the customer.

<CodeGroup>
```bash cURL
curl -X POST "https://sandbox.finhub.cloud/api/v2.1/accounts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -H "Content-Type: application/json" \
  -d "{
    \"customerId\": \"$CUSTOMER_ID\",
    \"accountType\": \"WALLET\",
    \"currency\": \"EUR\",
    \"accountName\": \"Main Wallet\"
  }" | jq -r '.data.accountId' > account_id.txt

export ACCOUNT_ID=$(cat account_id.txt)
echo "✅ Account created: $ACCOUNT_ID"
```

```javascript JavaScript
const account = await apiRequest('/accounts', {
  method: 'POST',
  body: JSON.stringify({
    customerId,
    accountType: 'WALLET',
    currency: 'EUR',
    accountName: 'Main Wallet'
  })
});

const accountId = account.data.accountId;
console.log('✅ Account created:', accountId);
```

```python Python
account = api.request(
    'POST',
    '/accounts',
    json={
        'customerId': customer_id,
        'accountType': 'WALLET',
        'currency': 'EUR',
        'accountName': 'Main Wallet'
    }
)

account_id = account['data']['accountId']
print(f'✅ Account created: {account_id}')
```
</CodeGroup>

**Expected Response:**
```json
{
  "code": 200,
  "message": "Success",
  "data": {
    "accountId": "a8b5cec6-f46f-4629-8bb2-c1849c909cae",
    "accountNumber": "LT121000011101001000",
    "currency": "EUR",
    "balance": { "value": "0", "currency": "EUR", "scale": 2 },
    "status": "ACTIVE"
  }
}
```

<Check>**Step complete!** Account created with €0.00 balance.</Check>

---

## Step 6: Fund Account (2 minutes)

Add funds using the topup workflow.

### 6a. Prepare Topup

<CodeGroup>
```bash cURL
curl -X POST "https://sandbox.finhub.cloud/api/v2.1/fintrans/$ACCOUNT_ID/types/topup/prepare" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -H "Content-Type: application/json" \
  -d "{
    \"type\": \"TOPUP\",
    \"sourceAccount\": {
      \"iban\": \"FI2112345600000785\"
    },
    \"target\": {
      \"name\": \"Wallet: $ACCOUNT_ID\"
    },
    \"amount\": {
      \"value\": \"10000000\",
      \"currency\": \"EUR\",
      \"scale\": 2
    }
  }" | jq -r '.data.preparedOrderId' > prepared_order_id.txt

export PREPARED_ORDER_ID=$(cat prepared_order_id.txt)
echo "✅ Topup prepared: $PREPARED_ORDER_ID (€1,000.00)"
```

```javascript JavaScript
const prepared = await apiRequest(
  `/fintrans/${accountId}/types/topup/prepare`,
  {
    method: 'POST',
    body: JSON.stringify({
      type: 'TOPUP',
      sourceAccount: { iban: 'FI2112345600000785' },
      target: { name: `Wallet: ${accountId}` },
      amount: {
        value: '10000000', // €1,000.00
        currency: 'EUR',
        scale: 2
      }
    })
  }
);

const preparedOrderId = prepared.data.preparedOrderId;
console.log('✅ Topup prepared:', preparedOrderId, '(€1,000.00)');
```

```python Python
prepared = api.request(
    'POST',
    f'/fintrans/{account_id}/types/topup/prepare',
    json={
        'type': 'TOPUP',
        'sourceAccount': {'iban': 'FI2112345600000785'},
        'target': {'name': f'Wallet: {account_id}'},
        'amount': {
            'value': '10000000',  # €1,000.00
            'currency': 'EUR',
            'scale': 2
        }
    }
)

prepared_order_id = prepared['data']['preparedOrderId']
print(f'✅ Topup prepared: {prepared_order_id} (€1,000.00)')
```
</CodeGroup>

### 6b. Execute Topup

<CodeGroup>
```bash cURL
curl -X POST "https://sandbox.finhub.cloud/api/v2.1/fintrans/$ACCOUNT_ID/types/topup/execute" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -H "Content-Type: application/json" \
  -d "{
    \"preparedOrderId\": \"$PREPARED_ORDER_ID\"
  }"

echo "✅ Topup executed - Account funded with €1,000.00"
```

```javascript JavaScript
await apiRequest(`/fintrans/${accountId}/types/topup/execute`, {
  method: 'POST',
  body: JSON.stringify({ preparedOrderId })
});

console.log('✅ Topup executed - Account funded with €1,000.00');
```

```python Python
api.request(
    'POST',
    f'/fintrans/{account_id}/types/topup/execute',
    json={'preparedOrderId': prepared_order_id}
)

print('✅ Topup executed - Account funded with €1,000.00')
```
</CodeGroup>

**Expected Response:**
```json
{
  "code": 200,
  "message": "Transaction executed successfully",
  "data": {
    "executionId": "01d40939-0b87-4cda-b4aa-ac6cf3ab61ab",
    "status": "EXECUTED",
    "amount": { "value": "10000000", "currency": "EUR", "scale": 2 },
    "executedAt": "2026-01-13T23:30:00Z"
  }
}
```

<Check>**Step complete!** Account balance is now €1,000.00.</Check>

---

## Complete End-to-End Flow (All Steps)

<CodeGroup>
```bash Complete Bash Script
#!/bin/bash
set -e

echo "🚀 FinHub API Quickstart - Complete Flow"
echo "=========================================="

# Configuration
export ORG_ID="f3a4b5c6-d7e8-49f0-1a2b-3c4d5e6f7a8b"
export USER_ID="e2f3a4b5-c6d7-48e9-0f1a-2b3c4d5e6f7a"
export TENANT_ID="d1e2f3a4-b5c6-47d8-9e0f-1a2b3c4d5e6f"
export BASE_URL="https://sandbox.finhub.cloud/api/v2.1"

# Step 1: Authenticate
echo "\n📝 Step 1: Authenticating..."
TOKEN=$(curl -s -X POST "$BASE_URL/admin/organization/$ORG_ID/users/$USER_ID/sessions" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin@yourcompany.com",
    "password": "'$ADMIN_PASSWORD'",
    "tenantKey": "'$TENANT_KEY'",
    "tenantSecret": "'$TENANT_SECRET'",
    "clientKeys": {
      "clientId": "'$CLIENT_ID'",
      "clientSecret": "'$CLIENT_SECRET'"
    }
  }' | jq -r '.data.token')

echo "✅ Authenticated"

# Step 2: Register Customer
echo "\n📝 Step 2: Registering customer..."
EMAIL="quickstart.$(date +%s)@example.com"

CUSTOMER_ID=$(curl -s -X POST "$BASE_URL/customer/individual/registration" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -H "Content-Type: application/json" \
  -d "{
    \"tenantId\": \"$TENANT_ID\",
    \"firstName\": \"John\",
    \"lastName\": \"Quickstart\",
    \"email\": \"$EMAIL\",
    \"phone\": \"+37060012345\",
    \"password\": \"SecurePass123!\",
    \"matchingPassword\": \"SecurePass123!\",
    \"roleIds\": [\"ACCOUNT_OWNER\", \"USER\"],
    \"individualCustomer\": {
      \"tenantId\": \"$TENANT_ID\",
      \"customerName\": \"John Quickstart\",
      \"person\": {
        \"firstName\": \"John\",
        \"lastName\": \"Quickstart\",
        \"email\": \"$EMAIL\",
        \"dateOfBirth\": \"1990-05-15\",
        \"gender\": \"MALE\",
        \"nationality\": \"LT\",
        \"addresses\": [{
          \"type\": \"HOME\",
          \"street\": \"123 Main Street\",
          \"city\": \"Vilnius\",
          \"postalCode\": \"12345\",
          \"country\": \"LT\",
          \"isPrimary\": true
        }],
        \"contacts\": [{
          \"type\": \"EMAIL\",
          \"value\": \"$EMAIL\",
          \"isPrimary\": true
        }]
      },
      \"user\": {
        \"username\": \"$EMAIL\",
        \"email\": \"$EMAIL\",
        \"password\": \"SecurePass123!\",
        \"status\": \"PENDING_ACTIVATION\",
        \"roles\": [\"ACCOUNT_OWNER\", \"USER\"],
        \"isActive\": false
      }
    }
  }" | jq -r '.data.customerId')

echo "✅ Customer registered: $CUSTOMER_ID"

# Step 3: Create Verification
echo "\n📝 Step 3: Creating verification..."
VERIFICATION_ID=$(curl -s -X POST "$BASE_URL/verifications" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -H "Content-Type: application/json" \
  -d "{
    \"customerId\": \"$CUSTOMER_ID\",
    \"requestedByTenantId\": \"$TENANT_ID\",
    \"type\": \"IDENTITY_VERIFICATION\",
    \"requestedLevel\": \"TENANT_VERIFIED\",
    \"requestedByUserId\": \"admin-user\"
  }" | jq -r '.data.id')

echo "✅ Verification created: $VERIFICATION_ID"

# Step 4: Approve Verification (simplified for sandbox)
echo "\n📝 Step 4: Approving verification..."
curl -s -X POST "$BASE_URL/verifications/$VERIFICATION_ID/approve" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "approvedBy": "admin-user",
    "adminNotes": "Quickstart verification"
  }' > /dev/null

echo "✅ Verification approved"

# Step 5: Create Account
echo "\n📝 Step 5: Creating account..."
ACCOUNT_ID=$(curl -s -X POST "$BASE_URL/accounts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -H "Content-Type: application/json" \
  -d "{
    \"customerId\": \"$CUSTOMER_ID\",
    \"accountType\": \"WALLET\",
    \"currency\": \"EUR\",
    \"accountName\": \"Main Wallet\"
  }" | jq -r '.data.accountId')

echo "✅ Account created: $ACCOUNT_ID"

# Step 6: Fund Account
echo "\n📝 Step 6: Funding account with €1,000.00..."
PREPARED_ORDER=$(curl -s -X POST "$BASE_URL/fintrans/$ACCOUNT_ID/types/topup/prepare" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -H "Content-Type: application/json" \
  -d "{
    \"type\": \"TOPUP\",
    \"sourceAccount\": { \"iban\": \"FI2112345600000785\" },
    \"target\": { \"name\": \"Wallet: $ACCOUNT_ID\" },
    \"amount\": { \"value\": \"10000000\", \"currency\": \"EUR\", \"scale\": 2 }
  }" | jq -r '.data.preparedOrderId')

curl -s -X POST "$BASE_URL/fintrans/$ACCOUNT_ID/types/topup/execute" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -H "Content-Type: application/json" \
  -d "{\"preparedOrderId\": \"$PREPARED_ORDER\"}" > /dev/null

echo "✅ Account funded"

# Summary
echo "\n🎉 Quickstart Complete!"
echo "======================="
echo "Customer ID: $CUSTOMER_ID"
echo "Account ID: $ACCOUNT_ID"
echo "Balance: €1,000.00"
echo "Status: ACTIVE & VERIFIED"
```
</CodeGroup>

---

## What's Next?

<CardGroup cols={2}>
  <Card title="API Reference" icon="book" href="./api/reference/customer-apis/individual/registration">
    Explore all available endpoints
  </Card>
  
  <Card title="Migration Guide" icon="arrow-right-arrow-left" href="./migration-guide">
    Upgrade from v2.0 to v2.1
  </Card>
  
  <Card title="Best Practices" icon="shield" href="./best-practices">
    Security and performance tips
  </Card>
</CardGroup>

---

## Troubleshooting

<AccordionGroup>
  <Accordion title="401 - Authentication Failed">
    **Problem:** Invalid credentials or expired token
    
    **Solution:**
    - Verify your credentials in Admin Portal
    - Check that user has ADMIN role
    - Ensure token hasn't expired (~1 hour validity)
  </Accordion>
  
  <Accordion title="400 - Customer Registration Failed">
    **Problem:** Invalid request structure
    
    **Common Causes:**
    - Missing required fields (`password`, `matchingPassword`, `roleIds`)
    - Incorrect nesting (`individualCustomer.person`, `individualCustomer.user`)
    - Email already registered
    
    **Solution:** Use exact structure from examples above
  </Accordion>
  
</AccordionGroup>

---

## E2E Test Validation

<Info>
  This entire quickstart flow is validated with E2E integration tests:
  
  - **Organization Flow:** test-log1768245707542.log
  - **Individual Flow:** test-log1768245718524.log
  - **Success Rate:** 100%
  - **Total Time:** ~10-15 minutes including verification approval
</Info>

---

## SDK Examples

Coming soon:
- Node.js SDK
- Python SDK
- Java SDK
- PHP SDK

---

**Need Help?**

- 📧 Email: api-support@finhub.cloud
- 💬 Discord: [FinHub Developers](https://discord.gg/finhub)
- 📚 Docs: [Full API Reference](./api/reference/authentication)



---

# Welcome to FinHub

The official developer portal for FinHub's financial technology platform. Access sandbox environments, comprehensive documentation, and integration guides.


URL: /



FinHub is a financial technology platform that enables you to build payment solutions, banking services, and embedded finance applications. We offer two primary service models: **Business as a Service (BaaS)** and **Platform as a Service (PaaS)**.

## Start Here

<CardGroup cols={3}>
  <Card title="New to FinHub?" icon="rocket" href="/overview/find-your-path">
    Find your integration path
  </Card>
  <Card title="Developer Portal" icon="key" href="https://sandbox.finhub.cloud/dev-portal">
    Sign in and try APIs with Postman + playground
  </Card>
  <Card title="Service Models" icon="code-compare" href="/overview/service-models">
    BaaS and PaaS explained
  </Card>
</CardGroup>

## Quick Navigation

<Tabs>
  <Tab title="New Users">
    <CardGroup cols={2}>
      <Card title="Find Your Path" icon="map" href="/overview/find-your-path">
        Decide between BaaS and PaaS
      </Card>
      <Card title="Service Models" icon="code-compare" href="/overview/service-models">
        Understand integration options
      </Card>
      <Card title="Getting Started" icon="play" href="/baas/api/getting-started">
        Begin your API journey
      </Card>
      <Card title="Developer Portal" icon="key" href="https://sandbox.finhub.cloud/dev-portal">
        Interactive API playground (tenant login)
      </Card>
    </CardGroup>
  </Tab>
  <Tab title="Returning Users">
    <CardGroup cols={2}>
      <Card title="API Reference" icon="code" href="/baas/api/reference">
        Full API documentation
      </Card>
      <Card title="Sandbox" icon="flask" href="https://sandbox.finhub.cloud/swagger-ui/#/">
        API Playground
      </Card>
      <Card title="Integration Flows" icon="sitemap" href="/baas/api/integration/flows">
        Implementation guides
      </Card>
      <Card title="Webhooks" icon="bell" href="/paas/fincard-virtual/webhooks">
        Event notifications
      </Card>
    </CardGroup>
  </Tab>
  <Tab title="By Product">
    <CardGroup cols={2}>
      <Card title="CoreX Platform" icon="desktop" href="/baas/corex/introduction">
        White-label banking UI
      </Card>
      <Card title="API Integration" icon="plug" href="/baas/api/introduction">
        Direct API access
      </Card>
      <Card title="PaaS Connectors" icon="link" href="/paas/introduction">
        System-to-system integration
      </Card>
      <Card title="Product Suite" icon="cubes" href="/baas/products">
        Available products
      </Card>
    </CardGroup>
  </Tab>
</Tabs>

## What You Can Build

<CardGroup cols={3}>
  <Card title="Payment Processing" icon="banknote">
    SEPA, SWIFT, and local payment networks
  </Card>
  <Card title="Banking Services" icon="building-columns">
    Accounts, wallets, and multi-currency transactions
  </Card>
  <Card title="Customer Onboarding" icon="user-check">
    Digital KYC/KYB verification flows
  </Card>
  <Card title="Card Issuing" icon="credit-card">
    Physical and virtual card programs
  </Card>
  <Card title="Merchant Acquiring" icon="store">
    POS terminals and payment acceptance
  </Card>
  <Card title="Crypto Exchanges" icon="bitcoin">
    Digital asset trading and custody
  </Card>
  <Card title="Embedded Finance" icon="puzzle-piece">
    Financial services in your platform
  </Card>
  <Card title="RegTech & Compliance" icon="shield-check">
    KYC, KYB, AML screening solutions
  </Card>
  <Card title="Communication" icon="message">
    SMS, email, and push notifications
  </Card>
</CardGroup>

## Platform at a Glance

| Capability | Description |
|------------|-------------|
| **Multi-Currency** | Support for 30+ currencies with real-time FX |
| **Payment Networks** | SEPA, SWIFT, local payment systems |
| **Compliance** | Built-in KYC/KYB and AML screening |
| **White-Label** | Fully customizable CoreX platform |

## Service Models

FinHub offers two primary service models:

| Model | Description | Best For |
|-------|-------------|----------|
| **BaaS** | Business processes via microservices with CoreX, API, or Hybrid integration | Companies needing full financial services |
| **PaaS** | Direct connector access for system-to-system integration | Companies with existing systems needing specific integrations |

<Card title="Learn About Service Models" icon="code-compare" href="/overview/service-models">
  Understand the difference between BaaS and PaaS
</Card>

## Explore by Service Model

<CardGroup cols={2}>
  <Card title="Business as a Service (BaaS)" icon="building" href="/baas/introduction">
    Full financial services via microservices - CoreX, API, or Hybrid
  </Card>
  <Card title="Platform as a Service (PaaS)" icon="plug" href="/paas/introduction">
    System-to-system connectors for existing infrastructure
  </Card>
</CardGroup>

## Developer Resources

<CardGroup cols={4}>
  <Card title="Quick Start" icon="bolt" href="/baas/api/getting-started/quick-start">
    First API call
  </Card>
  <Card title="Sandbox Setup" icon="laptop-code" href="/baas/api/development/sandbox-setup">
    Dev environment
  </Card>
  <Card title="Testing Tools" icon="vial" href="/baas/api/development/testing-tools">
    Test utilities
  </Card>
  <Card title="Go to Production" icon="rocket" href="/baas/api/production">
    Launch checklist
  </Card>
</CardGroup>

## Need Help?

<CardGroup cols={2}>
  <Card title="Technical Support" icon="headset">
    [support@finhub.cloud](mailto:support@finhub.cloud)
  </Card>
  <Card title="Sales Inquiries" icon="handshake">
    [sales@finhub.cloud](mailto:sales@finhub.cloud)
  </Card>
</CardGroup>

| Type | Contact | Response Time |
|------|---------|---------------|
| **Sandbox Support** | [sandbox-support@finhub.cloud](mailto:sandbox-support@finhub.cloud) | Within 24 hours |
| **Production Support** | [production-support@finhub.cloud](mailto:production-support@finhub.cloud) | Within 4 hours |
| **Compliance Questions** | [compliance@finhub.cloud](mailto:compliance@finhub.cloud) | Within 48 hours |

- **Documentation**: Browse our comprehensive guides and API reference
- **Website**: Visit [finhub.cloud](https://finhub.cloud) for more information


---

# Banking Partners

Correspondent banking and partner integrations


URL: /paas/connectors/banking-partners



# Banking Partner Connectors

Connect to correspondent banks and financial partners.

## Correspondent Banking

Access nostro/vostro accounts:

| Service | Description |
|---------|-------------|
| **Account Access** | Balance, statements |
| **Payments** | Initiate transfers |
| **FX** | Currency exchange |
| **Liquidity** | Cash management |

### Features

- Real-time balance
- Transaction history
- Payment initiation
- Multi-currency support

## Clearing Connectors

Settlement and clearing:

| Service | Description |
|---------|-------------|
| **Net Settlement** | Batch settlement |
| **Gross Settlement** | Real-time settlement |
| **Reconciliation** | Automated matching |

## FX Connectors

Currency exchange:

| Service | Description |
|---------|-------------|
| **Spot FX** | Immediate exchange |
| **Forward** | Future-dated |
| **Rates** | Real-time quotes |

### Features

- Competitive rates
- Multi-provider
- Rate locking
- Execution reporting

## Integration

### Balance Request

```json
{
  "account_id": "nostro_eur_001",
  "currency": "EUR"
}
```

### Response

```json
{
  "account_id": "nostro_eur_001",
  "currency": "EUR",
  "available_balance": 1500000.00,
  "current_balance": 1520000.00
}
```

## Next Steps

<Card title="Integration Guide" icon="code" href="/paas/journey/integration">
  Start integrating
</Card>


---

# Card Networks

Integrate with Visa, Mastercard, and card schemes


URL: /paas/connectors/card-networks



# Card Networks Connectors

Connect to card networks for issuing and acquiring.

## Issuing Connector

Issue cards on major networks:

| Network | Card Types | Features |
|---------|------------|----------|
| **Visa** | Debit, Credit, Prepaid | Virtual, Physical |
| **Mastercard** | Debit, Credit, Prepaid | Virtual, Physical |

### Issuing Features

- BIN sponsorship
- Card lifecycle management
- Real-time authorization
- 3D Secure support
- Tokenization

## Acquiring Connector

Accept card payments:

| Service | Description |
|---------|-------------|
| **Authorization** | Real-time auth requests |
| **Capture** | Settlement capture |
| **Refunds** | Return processing |
| **Chargebacks** | Dispute management |

### Acquiring Features

- Multi-scheme support
- PCI DSS compliance
- Fraud screening
- Settlement reporting

## Processing Connector

Card transaction processing:

- Authorization routing
- Stand-in processing
- Settlement files
- Reconciliation

## Integration

### Authorization Request

```json
{
  "card_token": "tok_123456",
  "amount": 50.00,
  "currency": "EUR",
  "merchant_id": "merch_789"
}
```

## Next Steps

<Card title="KYC/KYB" icon="id-card" href="/paas/connectors/kyc-kyb">
  Identity verification
</Card>


---

# KYC Providers

Connect to identity verification services


URL: /paas/connectors/kyc-providers



# KYC Provider Connectors

Integrate with identity verification and compliance services.

## Document Verification

Verify identity documents:

| Document Type | Verification |
|---------------|--------------|
| **Passport** | MRZ, NFC, visual |
| **ID Card** | OCR, validation |
| **Driver License** | OCR, database |
| **Proof of Address** | Document analysis |

### Features

- OCR extraction
- Document authenticity
- Data validation
- Fraud detection

## Biometric Verification

Face and liveness checks:

| Service | Description |
|---------|-------------|
| **Face Match** | Compare selfie to document |
| **Liveness** | Ensure real person |
| **Voice** | Voice biometrics |

### Features

- Passive liveness
- Active liveness
- Anti-spoofing
- Match scoring

## Data Verification

Database and watchlist checks:

| Check | Sources |
|-------|---------|
| **PEP** | Politically exposed persons |
| **Sanctions** | Global sanctions lists |
| **Adverse Media** | News screening |
| **Credit** | Credit bureau data |

## Integration

### Verification Request

```json
{
  "type": "full_kyc",
  "document": {
    "type": "passport",
    "front_image": "base64..."
  },
  "selfie": "base64...",
  "checks": ["pep", "sanctions"]
}
```

## Next Steps

<Card title="Banking Networks" icon="building-columns" href="/paas/connectors/banking-networks">
  Correspondent banking
</Card>


---

# Payment Rails

Connect to SEPA, SWIFT, and local payment networks


URL: /paas/connectors/payment-rails



# Payment Rails Connectors

Connect your systems to major payment networks and rails.

## SEPA Connector

Access the Single Euro Payments Area network:

| Service | Description |
|---------|-------------|
| **SEPA Credit Transfer (SCT)** | Euro transfers across SEPA zone |
| **SEPA Direct Debit (SDD)** | Euro direct debit collection |
| **SEPA Instant (SCT Inst)** | Real-time euro transfers |

### SEPA Features

- ISO 20022 message format
- IBAN validation
- BIC routing
- Real-time status updates
- Batch processing support

## SWIFT Connector

Global correspondent banking network:

| Service | Description |
|---------|-------------|
| **MT Messages** | Traditional SWIFT messages |
| **MX Messages** | ISO 20022 format |
| **gpi** | Global Payments Innovation |

### SWIFT Features

- 200+ country coverage
- Multi-currency support
- End-to-end tracking
- Compliance screening

## Local Rails

Country-specific payment systems:

| Country | Rail | Type |
|---------|------|------|
| UK | Faster Payments | Real-time |
| US | ACH | Batch |
| Singapore | FAST | Real-time |
| Australia | NPP | Real-time |

## Integration

### Endpoint

```
POST /paas/v1/payments/rails/{rail_type}
```

### Example Request

```json
{
  "rail": "sepa_sct",
  "amount": 1000.00,
  "currency": "EUR",
  "creditor_iban": "DE89370400440532013000",
  "debtor_iban": "FR7630006000011234567890189"
}
```

## Next Steps

<Card title="Card Networks" icon="credit-card" href="/paas/connectors/card-networks">
  Integrate with card schemes
</Card>