> 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/23-finacle-integration.md).

# Finacle Integration Architecture

## 1. Overview

**CBS provider type:** Finacle (`provider_code: FINACLE`)\
**Module:** `h2h-finacle-wrapper`\
**Base library contract:** [43 Core Banking Integration API](/docs/43-core-banking-integration-api.md) — `CoreBankingIntegration`

Finacle is the **system of record** across Heirs' 20+ markets today. The Finacle module is **one pluggable CBS provider** on the `h2h-core-banking-api` base library — not the platform's core banking layer itself. `FinacleCoreBankingIntegration` implements `CoreBankingIntegration` and registers as a provider bean; the `finacle:` / `corebank:` Camel component delegates to the injected interface.

**To integrate a different CBS product:** add `h2h-cbs-{vendor}` implementing the same base library — routes and canonical model unchanged.

See also: [29 Canonical Data Model](/docs/29-canonical-data-model.md), [31 Error Code Catalog](/docs/31-error-code-catalog.md).

***

## 2. Layering

| Layer             | Module                 | Role                                              |
| ----------------- | ---------------------- | ------------------------------------------------- |
| **Base library**  | `h2h-core-banking-api` | `CoreBankingIntegration` — all routes depend here |
| **CBS provider**  | `h2h-finacle-wrapper`  | Finacle type — `FinacleCoreBankingIntegration`    |
| **Orchestration** | `h2h-*-routes`         | Inject `CoreBankingIntegration` from base library |

```mermaid
flowchart TB
  Routes[h2h-payments-routes]
  API[CoreBankingIntegration interface]
  Wrapper[h2h-finacle-wrapper]
  Adapter[FinacleCoreBankingIntegration]
  FCJ[FcjClient]
  FCUBS[FcubsClient]
  CBS[(Finacle CBS)]

  Routes --> API
  Wrapper -->|registers bean| Adapter
  Adapter -.->|implements| API
  Adapter --> FCJ
  Adapter --> FCUBS
  FCJ --> CBS
  FCUBS --> CBS
```

***

## 3. Integration Targets

| Interface | Technology                       | Use when                          |
| --------- | -------------------------------- | --------------------------------- |
| **FCJ**   | Finacle Core Java APIs           | Markets on FCJ-native integration |
| **FCUBS** | Finacle Web Services (SOAP/REST) | Markets on FCUBS service layer    |

**Rule:** One `CoreBankingIntegration` bean per runtime; country/market selects FCJ vs FCUBS via `FinacleCustomization` in [CustomizationProfile](/docs/20-universal-library-extensibility.md).

***

## 4. Architecture (internal)

```mermaid
flowchart TB
  Camel[finacle: Camel component]
  IF[CoreBankingIntegration injected]
  Adapter[FinacleCoreBankingIntegration]
  Router[FinacleOperationRouter]
  FCJ[FcjClient]
  FCUBS[FcubsClient]
  Pool[ConnectionPool]
  CB[CircuitBreaker]

  Camel --> IF
  IF --> Adapter
  Adapter --> Router
  Router --> FCJ
  Router --> FCUBS
  FCJ --> Pool
  FCUBS --> Pool
  Pool --> CB
  CB --> Finacle[(Finacle CBS)]
```

***

## 5. Implementation

`FinacleCoreBankingIntegration` implements [CoreBankingIntegration](/docs/43-core-banking-integration-api.md):

```java
public class FinacleCoreBankingIntegration implements CoreBankingIntegration {

    private final FcjClient fcjClient;
    private final FcubsClient fcubsClient;
    private final FinacleOperationMapper operationMapper;
    private final List<CoreBankingOperationProvider> operationProviders;

    @Override
    public String providerId() { return "finacle"; }

    @Override
    public PaymentResult postPayment(PaymentRequest request, CoreBankingContext ctx) {
        FinacleCustomization fin = ctx.customization().finacle();
        var nativeReq = operationMapper.toFinacleRequest(request, fin);
        var nativeRes = router.route("POST_PAYMENT", nativeReq, fin);
        return operationMapper.toPaymentResult(nativeRes);
    }
    // ...
}
```

All DTOs use [canonical models](/docs/29-canonical-data-model.md) — no Finacle types leak across the `h2h-core-banking-api` boundary.

***

## 6. Operation Mapping

**Table: `finacle_operation_mapping`** (config DB, per country/product)

| Canonical operation | FCJ operation                 | FCUBS service           | Notes                |
| ------------------- | ----------------------------- | ----------------------- | -------------------- |
| `POST_PAYMENT`      | `PaymentService.post()`       | `PaymentPostingService` | Single payment       |
| `POST_BATCH`        | `BulkPaymentService.submit()` | `BulkPaymentService`    | Batch header + lines |
| `ACCOUNT_INQUIRY`   | `AccountService.getDetails()` | `AccountInquiry`        | Pre-validation       |
| `BALANCE_INQUIRY`   | `AccountService.getBalance()` | `BalanceInquiry`        | Collections          |
| `STATEMENT`         | `StatementService.generate()` | `StatementService`      | MT940/camt source    |

Overrides per partner via `FinacleCustomization.operationOverrides` JSON.

***

## 7. Connection Management

| Setting                   | Source                 | Default           |
| ------------------------- | ---------------------- | ----------------- |
| `poolSize`                | `FinacleCustomization` | 20                |
| `maxWaitMs`               | customization          | 30000             |
| `timeoutMs`               | customization          | 30000             |
| `circuitBreakerThreshold` | customization          | 50% errors in 60s |
| Endpoint URL              | K8s env / Vault        | per region        |

**Pooling:** HikariCP-style pool per Finacle endpoint; pools keyed by `{region}-{serviceVariant}`.

***

## 8. Request / Response Flow

```mermaid
sequenceDiagram
  participant Camel
  participant CBS as CoreBankingIntegration
  participant Adapter as FinacleCoreBankingIntegration
  participant Map as OperationMapper
  participant Client as FCJ/FCUBS
  participant Finacle

  Camel->>CBS: postPayment(request, ctx)
  Note over CBS,Adapter: Injected FinacleCoreBankingIntegration
  CBS->>Map: toFinacleRequest(request, customization)
  Map->>Client: native call
  Client->>Finacle: protocol call
  Finacle-->>Client: response
  Client-->>Adapter: native response
  Adapter->>Adapter: toPaymentResult + map errors
  Adapter-->>Camel: PaymentResult
```

***

## 9. Error Handling

Finacle errors map to platform [error codes](/docs/31-error-code-catalog.md):

| Finacle category    | Platform code | Retryable               |
| ------------------- | ------------- | ----------------------- |
| Insufficient funds  | `FIN_001`     | No                      |
| Invalid account     | `FIN_002`     | No                      |
| Timeout             | `FIN_010`     | Yes                     |
| Service unavailable | `FIN_011`     | Yes                     |
| Duplicate reference | `FIN_003`     | No (idempotent success) |
| Limit exceeded      | `FIN_004`     | No                      |
| Cut-off exceeded    | `FIN_005`     | No                      |

Circuit breaker open → `FIN_011` → route to retry/DLQ per [Camel patterns](/docs/08-camel-integration-patterns.md).

***

## 10. Idempotency with Finacle

* Platform generates `bankReference` from idempotency key before first post
* On `FIN_003` duplicate → treat as success if original reference matches
* Stored in `payment_transaction` table ([schema](/docs/30-database-schema-reference.md))

***

## 11. Camel Component

```
finacle:postPayment
finacle:postBatch
finacle:accountInquiry
```

`FinacleComponent` is constructed with injected `CoreBankingIntegration`. Reads `FinacleCustomization` from `H2hContext.customizationProfile()`.

***

## 12. Extensibility

| Type                   | Mechanism                                                                       |
| ---------------------- | ------------------------------------------------------------------------------- |
| Alternate CBS (future) | New JAR implements `CoreBankingIntegration`; `h2h.core-banking.provider`        |
| New Finacle operation  | `CoreBankingOperationProvider` / `FinacleOperationProvider` SPI (L4 JAR plugin) |
| Field mapping          | `finacle_operation_mapping` config                                              |
| Pre/post hooks         | `finacle.pre_post`, `finacle.post_post` hooks                                   |
| Service variant        | `FinacleCustomization.serviceVariant`                                           |
| Sandbox / CI           | `MockCoreBankingIntegration` via `provider: mock`                               |

***

## 13. Multi-Country

| Concern                        | Approach                                                   |
| ------------------------------ | ---------------------------------------------------------- |
| Different FCJ/FCUBS per region | Regional endpoint in Helm values                           |
| Country field requirements     | Canonical model + validation rules                         |
| Same wrapper JAR               | Yes — config only; same `CoreBankingIntegration` interface |

***

## 14. Related Documents

* [43 Core Banking Integration API](/docs/43-core-banking-integration-api.md)
* [29 Canonical Data Model](/docs/29-canonical-data-model.md)
* [31 Error Code Catalog](/docs/31-error-code-catalog.md)
* [03 Modular JAR Architecture](/docs/03-modular-jar-architecture.md)
* [20 Universal Library Extensibility](/docs/20-universal-library-extensibility.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/23-finacle-integration.md?ask=<question>&goal=<endgoal>
```

`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.