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, Verification & Compliance, and Financial Operations references. Use it as the narrative companion to those sections.Sandbox base URL (illustrative):
https://sandbox.finhub.cloud/api/v2.1 — your tenant receives the exact base URL and credentials during onboarding.Documentation map
Customer APIs
B2C and B2B registration, sessions, activation, and organization management
Verification & Compliance
Verifications, documents, approvals, and mandatory consents
Financial Operations
Wallets, beneficiaries, payment consents, prepare/execute, orders
Workflow diagrams
B2C workflow
B2B workflow
| Stage | What happens | Primary docs |
|---|---|---|
| Authenticate | Admin (or partner) JWT for back-office calls; customer JWT after session | Administration, API introduction |
| Register | Create B2C individual or B2B organization with categorization | Customer APIs |
| Verify | KYC/KYB initiation, document upload, approval | Verification & Compliance |
| Consents | terms, privacy, data-processing | Individual consents, Organization consents |
| Activate | Unlock account and downstream wallet provisioning | Individual activation, Organization activation |
| Wallets | Poll until Product GP wallet and IBAN are available | Get wallets by customer |
| Payments | Beneficiaries → payment consent → prepare → execute | 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:| Step | Action | API reference |
|---|---|---|
| 1 | Admin session (or partner auth) | Administration |
| 2 | Categorization hierarchy | Categorization |
| 3 | Individual registration | Registration |
| 4 | Customer session (POST .../users/{userId}/sessions) | Individual index (sessions table) |
| 5 | Verification: create → upload documents → approve | Create verification, Upload document, Approve |
| 6 | Accept consents (terms, privacy, data-processing) | Individual consents |
| 7 | Activation readiness | Activation readiness check |
| 8 | Activate account | Activation |
| 9 | Poll wallets until IBAN on Product GP wallet | Get wallets by customer (?customerType=B2C) |
| 10+ | Beneficiaries, payment consent, prepare, consent confirmation, execute | See Financial operations |
B2B organization — embedded journey
Aligned with Organization customer APIs:| Step | Action | API reference |
|---|---|---|
| 1–2 | Same categorization pattern as B2C (filter for business categories) | Categorization |
| 3 | Organization registration | Registration |
| 4 | Add employees / directors / shareholders as required | Management, Employee, Shareholders |
| 5 | Admin or org user session | Administration |
| 6 | KYB: initiate (e.g. organization verify) → upload → approve | Create verification, Organization verify, Upload, Approve |
| 7 | Organization consents | Organization consents |
| 8 | Activate organization | Activation |
| 9 | Poll wallets (?customerType=B2B) | Get wallets by customer |
| 10+ | Beneficiaries, consents, prepare, consent confirmation, execute | Financial Operations |
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:| Order | Operation | Documentation |
|---|---|---|
| 1 | Balance / allowed operations | Balance, Allowed operations |
| 2 | Register beneficiaries | Create beneficiary |
| 3 | Payment consent (when required) | Create payment consent |
| 4 | Prepare order | Prepare |
| 5 | Consent confirmation / OTP (flow depends on environment) | Approve verification, Consent verification |
| 6 | Execute order | Execute |
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.
API Service Model
Platform overview and authentication concepts
Next steps
Individual APIs (B2C)
Registration through activation
Organization APIs (B2B)
Business onboarding and activation
Verification & Compliance
Verifications, documents, and consents
Financial Operations
Wallets, transfers, and payment operations