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

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

# 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>

---

## 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 --> A3["(3) Register individual"]
    A3 --> A4["(4) Create customer session"]
    A4 --> A5["(5) Verification: initiate, upload docs, approve"]
    A5 --> A6["(6) Accept consents (terms/privacy/data-processing)"]
    A6 --> A7["(7) Activation readiness check"]
    A7 --> A8["(8) Activate account"]
    A8 --> A9["(9) Poll wallets until IBAN exists"]
    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 --> B4["(4) Add employee"]
    B4 --> B5["(5) Create organization user session"]
    B5 --> B6["(6) KYB: verify, upload docs, approve"]
    B6 --> 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 |

---

## 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–2 | Same categorization pattern as B2C (filter for business categories) | [Categorization](/baas/api/reference/customer-apis/individual/categorization) |
| 3 | Organization registration | [Registration](/baas/api/reference/customer-apis/organization/registration) |
| 4 | Add employees / directors / shareholders as required | [Management](/baas/api/reference/customer-apis/organization/management), [Employee](/baas/api/reference/customer-apis/organization/employee), [Shareholders](/baas/api/reference/customer-apis/organization/shareholders) |
| 5 | Admin or org user session | [Administration](/baas/api/reference/administration) |
| 6 | KYB: initiate (e.g. organization verify) → upload → approve | [Create verification](/baas/api/reference/verification-compliance/create-verification), [Organization verify](/baas/api/reference/customer-apis/organization/verify), [Upload](/baas/api/reference/verification-compliance/upload-verification-document), [Approve](/baas/api/reference/verification-compliance/approve-verification) |
| 7 | Organization consents | [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+ | Beneficiaries, consents, 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>