> For the complete documentation index, see [llms.txt](https://host2host.onibonje.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://host2host.onibonje.com/docs/43-core-banking-integration-api.md). # Core Banking Integration API ## 1. Overview **Base library:** `h2h-core-banking-api` The platform treats core banking connectivity as a **first-class, vendor-neutral base library** — the same architectural role as `h2h-notification-api` or `h2h-persistence-spi`. **Finacle is not the integration layer**; it is **one CBS provider type** that plugs into the base library. | Layer | Module | Role | | -------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------ | | **Base library** | `h2h-core-banking-api` | `CoreBankingIntegration` contract, canonical CBS DTOs, `CoreBankingOperationProvider` SPI, provider registry | | **CBS provider (Finacle)** | `h2h-finacle-wrapper` | `FinacleCoreBankingIntegration` — FCJ/FCUBS adapter for `providerId=finacle` | | **CBS provider (others)** | `h2h-cbs-{vendor}` (optional) | Additional adapters — Temenos, Flexcube, mock/simulator — same interface | | **Orchestration** | `h2h-*-routes` | Depends on **base library only**; never on Finacle or any CBS SDK | Route modules, transforms, and Camel pipelines depend only on `CoreBankingIntegration`. The active CBS implementation is **selected at runtime** via configuration (`core_banking_provider_def` + Spring bean) — swap Finacle for another CBS by changing the provider JAR on the classpath and the database row, not by rewriting routes. ``` h2h-payments-routes ──depends on──► h2h-core-banking-api (BASE LIBRARY) ▲ ┌─────────────────────────┼─────────────────────────┐ │ implements │ implements │ FinacleCoreBankingIntegration MockCoreBankingIntegration Future CBS adapter (h2h-finacle-wrapper) (h2h-cbs-mock) (h2h-cbs-*) ``` See also: [23 Finacle Integration](/docs/23-finacle-integration.md), [29 Canonical Data Model](/docs/29-canonical-data-model.md), [03 Modular JAR Architecture](/docs/03-modular-jar-architecture.md). *** ## 1.1 Design rules | Rule | Rationale | | ------------------------------------------------- | ------------------------------------------------------------------------------------------ | | **Base library has zero CBS vendor dependencies** | Finacle SDK never appears in `h2h-core-banking-api` or route modules | | **One interface, many providers** | Finacle today; other CBS products via new `h2h-cbs-*` JARs | | **Provider selected by config** | Per country, environment, or partner — `core_banking_provider_def` | | **Canonical DTOs only across the boundary** | [29 Canonical Data Model](/docs/29-canonical-data-model.md) — no FCJ/FCUBS types in routes | | **Finacle wrapper injects the interface** | `finacle:` Camel component delegates to injected `CoreBankingIntegration` | *** ## 2. Module Responsibilities | Module | Responsibility | Depends on | | -------------------------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------- | | **`h2h-core-banking-api`** | **Base library** — `CoreBankingIntegration`, DTOs, `CoreBankingOperationProvider` SPI, `CoreBankingProviderRegistry` | `h2h-common` only | | **`h2h-finacle-wrapper`** | **CBS provider type: Finacle** — FCJ/FCUBS, `finacle:` Camel component | `h2h-core-banking-api` | | **`h2h-cbs-mock`** | **CBS provider type: mock/simulator** — CI, sandbox without live CBS | `h2h-core-banking-api` | | **`h2h-cbs-{vendor}`** | **CBS provider type: other** — e.g. Temenos, Flexcube (future L4) | `h2h-core-banking-api` | | **`h2h-*-routes`** | Orchestration — inject `CoreBankingIntegration` from base library only | `h2h-core-banking-api` | **Rule:** No route module imports `com.heirs.h2h.finacle.internal.*` or Finacle SDK types. *** ## 3. Architecture ```mermaid flowchart TB subgraph routes [Route Modules] Pay[h2h-payments-routes] Coll[h2h-collections-routes] Stmt[h2h-statements-routes] end subgraph api [h2h-core-banking-api BASE LIBRARY] IF[CoreBankingIntegration] SPI[CoreBankingOperationProvider SPI] REG[CoreBankingProviderRegistry] end subgraph finacle [CBS Provider: Finacle] Adapter[FinacleCoreBankingIntegration] FCJ[FcjClient] FCUBS[FcubsClient] Camel[finacle: / corebank: Camel component] end subgraph optional [Other CBS Provider Types] Mock[MockCoreBankingIntegration] Other[h2h-cbs-vendor adapter] end Pay --> IF Coll --> IF Stmt --> IF Camel --> IF Adapter -.->|implements| IF Adapter --> FCJ Adapter --> FCUBS SPI --> Adapter Mock -.->|implements| IF Other -.->|implements| IF ``` *** ## 4. Core Interface ```java package com.heirs.h2h.corebanking.api; /** * Vendor-neutral core banking contract — base library API. * Implementations are CBS provider JARs (Finacle, mock, or h2h-cbs-*). */ public interface CoreBankingIntegration { String providerId(); // e.g. "finacle", "mock", "temenos", "flexcube" PaymentResult postPayment(PaymentRequest request, CoreBankingContext ctx); PaymentResult postPaymentBatch(PaymentBatch batch, CoreBankingContext ctx); AccountInfo inquireAccount(AccountInquiry inquiry, CoreBankingContext ctx); BalanceInfo inquireBalance(BalanceInquiry inquiry, CoreBankingContext ctx); StatementResult requestStatement(StatementRequest request, CoreBankingContext ctx); PaymentStatus inquirePaymentStatus(PaymentStatusInquiry inquiry, CoreBankingContext ctx); /** * Extension point for provider-specific operations (treasury, FX, etc.) */ T executeOperation(String operationCode, Object request, CoreBankingContext ctx, Class responseType); } ``` All request/response types are **canonical DTOs** from `h2h-common` / [29 Canonical Data Model](/docs/29-canonical-data-model.md). No CBS vendor types cross this boundary. ### 4.1 CoreBankingContext ```java public record CoreBankingContext( String correlationId, String partnerId, String countryCode, String environment, CustomizationProfile customization // provider-specific slice, e.g. FinacleCustomization ) {} ``` Built from `H2hContext` by `CoreBankingContextMapper` in `h2h-finacle-wrapper` (or any adapter). *** ## 5. CBS Provider Registration CBS providers are **pluggable types** on the base library — not hardcoded to Finacle. ### 5.1 Database-driven provider selection **Table:** `core_banking_provider_def` | Column | Description | | ------------------- | ----------------------------------------------------------------- | | `provider_id` | Unique ID | | `provider_code` | `FINACLE`, `MOCK`, `TEMENOS`, … | | `adapter_bean` | Spring bean name or `CoreBankingIntegration` implementation class | | `scope_type` | `GLOBAL`, `COUNTRY`, `PARTNER` | | `scope_id` | e.g. `NG` — country using Finacle FCUBS vs FCJ | | `connection_params` | JSON — endpoints, pool sizes (adapter-specific) | | `credential_ref` | Vault path | | `enabled` | Boolean | | `priority` | When multiple providers match scope | `CoreBankingProviderRegistry` resolves the active `CoreBankingIntegration` for `H2hContext.countryCode` / partner. ### 5.2 Injection into Finacle provider (example) The Finacle wrapper **implements** the base library contract — it does not replace it: ```java @AutoConfiguration @ConditionalOnProperty(name = "h2h.core-banking.provider", havingValue = "finacle", matchIfMissing = true) public class FinacleAutoConfiguration { @Bean @ConditionalOnMissingBean(CoreBankingIntegration.class) public CoreBankingIntegration finacleCoreBankingIntegration( FcjClient fcjClient, FcubsClient fcubsClient, FinacleOperationMapper operationMapper, FinacleConnectionPool connectionPool, List operationProviders) { return new FinacleCoreBankingIntegration( fcjClient, fcubsClient, operationMapper, connectionPool, operationProviders); } @Bean public FinacleComponent finacleComponent(CoreBankingIntegration coreBanking) { return new FinacleComponent(coreBanking); // injected interface } } ``` **Camel component** (`finacle:postPayment`) delegates to the injected `CoreBankingIntegration` — routes never call FCJ/FCUBS directly. ### 5.3 Provider selection ```yaml h2h: core-banking: default-provider: finacle # FINACLE provider type — not the platform CBS layer # default-provider: mock # h2h-cbs-mock for CI/sandbox ``` | `provider_code` | JAR module | `CoreBankingIntegration` implementation | | ------------------- | --------------------- | --------------------------------------- | | `FINACLE` (default) | `h2h-finacle-wrapper` | `FinacleCoreBankingIntegration` | | `MOCK` | `h2h-cbs-mock` | `MockCoreBankingIntegration` | | `{VENDOR}` | `h2h-cbs-{vendor}` | Vendor-specific adapter | Add a new CBS product: implement `CoreBankingIntegration` in a new JAR, register auto-config, insert `core_banking_provider_def` row — **routes unchanged**. *** ## 6. Operation Extension SPI **Interface:** `CoreBankingOperationProvider` (in `h2h-core-banking-api`) ```java public interface CoreBankingOperationProvider { String providerId(); // must match CoreBankingIntegration.providerId() String operationCode(); // e.g. "TREASURY_FX_RATE" boolean supports(CoreBankingContext ctx); Object execute(Object request, CoreBankingContext ctx); } ``` | Layer | SPI | Example | | ----------------------- | --------------------------------------------------------------- | ------------------- | | Generic | `CoreBankingOperationProvider` | Treasury FX inquiry | | Finacle-specific plugin | `FinacleOperationProvider extends CoreBankingOperationProvider` | FCUBS-only service | Finacle wrapper aggregates providers at startup and routes `executeOperation()` to the matching provider. **Config table:** `core_banking_operation_mapping` (replaces Finacle-only naming in new deployments; `finacle_operation_mapping` retained as Finacle customization view). *** ## 7. Route Module Usage Route modules depend on **`h2h-core-banking-api`** only: ```java @AutoConfiguration public class PaymentsRoutesAutoConfiguration { @Bean public RouteBuilder bulkPaymentRouteBuilder( ConfigResolver configResolver, CoreBankingIntegration coreBanking) { // interface — not FinacleService return new BulkPaymentRouteBuilder(configResolver, coreBanking); } } ``` ```java // In route — Camel URI delegates to injected integration from("direct:post-to-cbs") .process(coreBankingContextProcessor) .to("finacle:postPayment"); // finacle: component uses injected CoreBankingIntegration ``` For provider-neutral routes, use **`corebank:postPayment`** — resolves the active `CoreBankingIntegration` from `CoreBankingProviderRegistry`. The `finacle:` URI is a **convenience alias** when the Finacle provider type is active. *** ## 8. Extensibility Scenarios | Scenario | Approach | | ------------------------------------------ | -------------------------------------------------------------------- | | **Heirs default (Finacle markets)** | `FINACLE` provider type via `h2h-finacle-wrapper` | | **Finacle FCJ vs FCUBS per country** | Single Finacle provider; internal router selects client | | **New Finacle operation** | `FinacleOperationProvider` plugin + `core_banking_operation_mapping` | | **Sandbox without live CBS** | `MOCK` provider type — `h2h-cbs-mock` on classpath | | **Acquisition / non-Finacle CBS** | New `h2h-cbs-{vendor}` JAR + `core_banking_provider_def` row | | **Country A Finacle, Country B other CBS** | Scope-specific provider rows — same runtime JARs | | **Surgical Finacle fix** | Bump `h2h-finacle-wrapper` only — base library and routes unchanged | *** ## 9. Testing | Test type | Approach | | ------------- | ------------------------------------------------------ | | Unit (routes) | Mock `CoreBankingIntegration` | | Integration | `MockCoreBankingIntegration` or Finacle simulator JAR | | Contract | `CoreBankingIntegration` conformance tests per adapter | No Finacle SDK on the classpath of route module tests. *** ## 10. Related Documents * [23 Finacle Integration](/docs/23-finacle-integration.md) — Finacle adapter implementation * [03 Modular JAR Architecture](/docs/03-modular-jar-architecture.md) * [14 Extensibility Framework](/docs/14-extensibility-framework.md) * [20 Universal Library Extensibility](/docs/20-universal-library-extensibility.md) * [29 Canonical Data Model](/docs/29-canonical-data-model.md) * [35 Testing Strategy](/docs/35-testing-strategy.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://host2host.onibonje.com/docs/43-core-banking-integration-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.