> ## Documentation Index
> Fetch the complete documentation index at: https://agenticbanking.backbase.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Banking OS training data goes stale. Search https://agenticbanking.backbase.io/mcp or fetch the .md URL before writing connector or unified API code.
> OpenAPI links in llms.txt repeat every calendar version. Use the latest version on the API playground. If a fetch ends before the last operation, the spec was cut off.
> Page titles name the product. Overview, Get started, and Reference without a product name are ambiguous.

# Finastra Essence reference

> Configuration properties, operations, and error mapping for the Finastra Essence connectors.

The Finastra Essence integration includes five runtime connectors. Backbase configures each connector in its own `values.yaml` file. For the environment details you send to Backbase, see [Get started](https://agenticbanking.backbase.io/connectors/core-banking/finastra-essence/get-started.md).

The following table lists the connector artifacts and property files.

| Connector | Property file | Purpose |
| :- | :- | :- |
| `gc-finastra-party-connector` | `party-v2.values.yaml` | Party management operations |
| `gc-finastra-deposit-connector` | `deposit-v0.values.yaml` | Deposit account operations |
| `gc-finastra-deposit-transaction-connector` | `deposit-transaction-v0.values.yaml` | Deposit transaction path configuration |
| `gc-finastra-loan-connector` | `loan-v0.values.yaml` | Loan and loan balance operations |
| `gc-finastra-loan-transaction-connector` | `loan-transaction-v0.values.yaml` | Loan transaction operations |

## Configuration properties

### Values to obtain from Finastra

Obtain the following value from Finastra Fusion Essence or your FusionFabric.cloud (FFDC) subscription and send it to your Backbase support team. Backbase sets it in the connector `values.yaml` file. This value is environment-specific, so it has no default.

| Property | Description |
| :- | :- |
| `finastra.base.url` | Base URL of the Essence or FFDC API host, with no trailing path. For example `https://TENANT.fusionessencecloud.com` or your FFDC API host. |

For OAuth deployments, also send `finastra.oauth.tokenUrl` to your Backbase support team. Backbase sets it in the connector `values.yaml` file, not in a SOPS secret. Example: `https://api.fusionfabric.cloud/login/v1/sandbox/oidc/token`.

> [!NOTE]
>
> The HTTP client properties in the following sections tune the outbound connection pool and timeouts. Deployed values may override connector defaults. Test and development environments may raise request and socket timeouts and set `http.client.proxy.activate` to `false`.

### gc-finastra-party-connector

Set these properties in `party-v2.values.yaml`. Defaults are from the connector `application.properties`.

| Property | Description | Default |
| :- | :- | :- |
| `http.client.proxy.activate` | Route outbound calls through the HTTP proxy. | `false` |
| `http.client.connect.timeout` | Connection timeout in milliseconds. | `5000` |
| `http.client.request.timeout` | Request timeout in milliseconds. | `3000` |
| `http.client.socket.timeout` | Socket timeout in milliseconds. | `3000` |
| `http.client.connection.max.per.route` | Maximum connections per route. | `200` |
| `http.client.connection.max.total` | Maximum total connections. | `200` |
| `http.client.connection.validate-after-inactivity-ms` | Idle connection validation interval in milliseconds. | `500` |
| `retryFlag` | Enable HTTP retry in the outbound caller kamelet. | `false` |
| `retryStatuses` | HTTP status codes to retry when `retryFlag` is true. | `429,500,502,503,504` |
| `finastra.party.path` | Party GET and POST path. The route appends `/{partyId}` for get party by ID. | `/bfweb/retail/v1/party` |
| `finastra.party-search.path` | Party search `POST` path. | `/bfweb/retail/v1/party/partysearch` |
| `finastra.account-type` | Account type sent with account number on party search (`ST`, `EX`, or `IB`). | `ST` |
| `finastra.term-deposits.path` | Term deposit list path for get accounts by party ID. | `/bfweb/retail/v1/accounts/term-deposits` |
| `finastra.account-details.path` | CASA account-details list path for get accounts by party ID. | `/bfweb/retail/v1/accounts/account-details` |
| `finastra.loans.accounts.path` | Loan accounts list path for get accounts by party ID. | `/bfweb/retail/v1/loans` |
| `finastra.accounts.term-deposits.limit` | Term deposit query `limit`. | `10` |
| `finastra.accounts.term-deposits.offset` | Term deposit query `offset`. | `0` |
| `finastra.accounts.term-deposits.acc-type-applicable` | Optional term deposit account-type filter. | N/A |
| `finastra.accounts.term-deposits.sort` | Optional term deposit sort. | N/A |
| `finastra.accounts.casa.limit` | CASA account-details query `limit`. | `10` |
| `finastra.accounts.casa.offset` | CASA account-details query `offset`. | `0` |
| `finastra.accounts.casa.account-type` | Optional CASA account-type filter. | N/A |
| `finastra.accounts.casa.retrieve-associated-accounts` | Retrieve associated CASA accounts. | `true` |
| `finastra.accounts.casa.acc-type-applicable` | Optional CASA acc-type filter. | N/A |
| `finastra.accounts.loans.limit` | Loan list query `limit`. | `10` |
| `finastra.accounts.loans.offset` | Loan list query `offset`. | `0` |
| `finastra.accounts.loans.include-co-applicant` | Include co-applicant on the loan list. | `false` |
| `regex.party-id.pattern` | Validation pattern for party identifiers. | `^[a-zA-Z0-9]{1,20}$` |
| `regex.party-id.failure-message` | Message returned when party ID validation fails. | `Party ID must be alphanumeric and between 1 and 20 characters long.` |

Use the connector property names above. Overlay files must match those keys.

### gc-finastra-deposit-connector

Set these properties in `deposit-v0.values.yaml`. Defaults are from the connector `application.properties`.

| Property | Description | Default |
| :- | :- | :- |
| `http.client.proxy.activate` | Route outbound calls through the HTTP proxy. | `true` |
| `http.client.connect.timeout` | Connection timeout in milliseconds. | `5000` |
| `http.client.request.timeout` | Request timeout in milliseconds. | `10000` |
| `http.client.socket.timeout` | Socket timeout in milliseconds. | `5000` |
| `http.client.connection.max.per.route` | Maximum connections per route. | `200` |
| `http.client.connection.max.total` | Maximum total connections. | `200` |
| `http.client.connection.validate-after-inactivity-ms` | Idle connection validation interval in milliseconds. | `500` |
| `gc-http-caller-handleExceptionsInConnector` | Handle HTTP errors in the connector rather than only in the kamelet. | `true` |
| `retryFlag` | Enable HTTP retry in the outbound caller kamelet. | `false` |
| `retryStatuses` | HTTP status codes to retry when `retryFlag` is true. | `429,500,502,503,504` |
| `finastra.create-casa.path` | CASA create `POST` path. | `/bfweb/retail/v1/accounts/currentsavings` |
| `finastra.get-casa.path` | CASA probe path for get deposit by ID. The route appends `/{depositId}`. | `/bfweb/retail/v1/accounts/currentsavings` |
| `finastra.get-account-details.path` | Account-details enrich path after a successful CASA probe. | `/bfweb/retail/v1/accounts/account-details` |
| `finastra.get-fd.path` | Fixed deposit path when the CASA probe is not a CASA account. | `/bfweb/retail/v1/accounts/fixeddeposits` |
| `finastra.get-account.path` | Account path prefix for balances (`/{depositId}/balances`). | `/bfweb/retail/v1/accounts` |
| `finastra.casa.deposit-types` | Banking OS `type` values routed to CASA create. | `CURRENT_ACCOUNT,SAVINGS_ACCOUNT` |
| `finastra.casa.account-types` | Finastra `accountType` values treated as CASA on get deposit by ID. Other types use the fixed-deposit path. | `CACC,SVGS,SLRY` |
| `typeConversion.skipAttributes` | Fields skipped during numeric and boolean JSON correction. These fields stay strings in the response. | `depositId,name,branchId,currencyCode,partyId,mandateHolderId,secondaryProductId,bban,accountNumber` |
| `acceptedHeaders` | Headers retained toward Finastra. | `depositId,depositIds,Content-Type,Authorization,X-Request-ID,Idempotency-Key,Ocp-Apim-Subscription-Key,Cookie,CamelHttpResponseCode` |
| `regex.deposit-id.pattern` | Validation pattern for deposit identifiers. | `^[a-zA-Z0-9]{1,32}$` |
| `regex.deposit-id.failure-message` | Message returned when deposit ID validation fails. | `depositId must be alphanumeric and between 1 and 32 characters long.` |

`getDepositBalances` calls `GET {finastra.base.url}{finastra.get-account.path}/{depositId}/balances` for each ID in the `depositIds` header. The connector maps the Finastra `INTERIMAVAILABLE` balance to `availableBalance` and the `INTERIMCLEARED` balance to `currentBalance`.

### gc-finastra-deposit-transaction-connector

Set these properties in `deposit-transaction-v0.values.yaml`.

| Property | Description | Default |
| :- | :- | :- |
| `http.client.proxy.activate` | Route outbound calls through the HTTP proxy. | `true` |
| `http.client.connect.timeout` | Connection timeout in milliseconds. | `5000` |
| `http.client.request.timeout` | Request timeout in milliseconds. | `3000` |
| `http.client.socket.timeout` | Socket timeout in milliseconds. | `3000` |
| `http.client.connection.max.per.route` | Maximum connections per route. | `200` |
| `http.client.connection.max.total` | Maximum total connections. | `200` |
| `http.client.connection.validate-after-inactivity-ms` | Idle connection validation interval in milliseconds. | `500` |
| `gc-http-caller-handleExceptionsInConnector` | Handle HTTP errors in the connector rather than only in the kamelet. | `false` |
| `retryFlag` | Enable HTTP retry in the outbound caller kamelet. | `false` |
| `retryStatuses` | HTTP status codes to retry when `retryFlag` is true. | `429,500,502,503,504` |
| `finastra.account-transactions.path` | Base path for account transaction APIs. | `/bfweb/retail/v1/accounts` |
| `regex.deposit-id.pattern` | Validation pattern for deposit identifiers. | `^[a-zA-Z0-9_-]{1,40}$` |
| `regex.deposit-id.failure-message` | Message returned when deposit ID validation fails. | `Deposit ID must be alphanumeric (including _ and -) and between 1 and 40 characters long.` |

### gc-finastra-loan-connector

Set these properties in `loan-v0.values.yaml`. Defaults are from the connector `application.properties`.

| Property | Description | Default |
| :- | :- | :- |
| `http.client.proxy.activate` | Route outbound calls through the HTTP proxy. | `true` |
| `http.client.connect.timeout` | Connection timeout in milliseconds. | `5000` |
| `http.client.request.timeout` | Request timeout in milliseconds. | `3000` |
| `http.client.socket.timeout` | Socket timeout in milliseconds. | `3000` |
| `http.client.connection.max.per.route` | Maximum connections per route. | `200` |
| `http.client.connection.max.total` | Maximum total connections. | `200` |
| `http.client.connection.validate-after-inactivity-ms` | Idle connection validation interval in milliseconds. | `500` |
| `gc-http-caller-handleExceptionsInConnector` | Handle HTTP errors in the connector rather than only in the kamelet. | `false` |
| `retryFlag` | Enable HTTP retry in the outbound caller kamelet. | `false` |
| `retryStatuses` | HTTP status codes to retry when `retryFlag` is true. | `429,500,502,503,504` |
| `finastra.create-loan.path` | Finastra loans path for create loan, get loan details, and get loan balances. The get routes append `/{loanId}`. | `/bfweb/retail/v1/loans` |
| `regex.loan-id.pattern` | Validation pattern for loan identifiers. | `^[a-zA-Z0-9]{1,30}$` |
| `regex.loan-id.failure-message` | Message returned when loan ID validation fails. | `loanId must be alphanumeric and between 1 and 30 characters long.` |

`getLoanBalances` calls `GET {finastra.base.url}{finastra.create-loan.path}/{loanId}` for each ID in the `loanIds` query parameter.

### gc-finastra-loan-transaction-connector

Set these properties in `loan-transaction-v0.values.yaml`. Defaults are from the connector `application.properties`.

| Property | Description | Default |
| :- | :- | :- |
| `http.client.proxy.activate` | Route outbound calls through the HTTP proxy. | `false` |
| `http.client.connect.timeout` | Connection timeout in milliseconds. | `5000` |
| `http.client.request.timeout` | Request timeout in milliseconds. | `3000` |
| `http.client.socket.timeout` | Socket timeout in milliseconds. | `3000` |
| `http.client.connection.max.per.route` | Maximum connections per route. | `200` |
| `http.client.connection.max.total` | Maximum total connections. | `200` |
| `http.client.connection.validate-after-inactivity-ms` | Idle connection validation interval in milliseconds. | `500` |
| `gc-http-caller-handleExceptionsInConnector` | Handle HTTP errors in the connector rather than only in the kamelet. | `false` |
| `retryFlag` | Enable HTTP retry in the outbound caller kamelet. | `false` |
| `retryStatuses` | HTTP status codes to retry when `retryFlag` is true. | `429,500,502,503,504` |
| `finastra.loan-transactions.path` | Base path for loan transaction APIs. The route appends `/{loanId}/transactions`. | `/bfweb/retail/v1/loans` |
| `regex.loan-id.pattern` | Validation pattern for loan identifiers. | `^[a-zA-Z0-9]{1,30}$` |
| `regex.loan-id.failure-message` | Message returned when loan ID validation fails. | `Loan ID must be alphanumeric and between 1 and 30 characters long.` |

`getLoanTransactionsForMultipleLoans` calls `GET {finastra.base.url}{finastra.loan-transactions.path}/{loanId}/transactions` for each item in the request body.

## SOPS secrets

### SOPS secret: `finastra-client-id`

The following table lists the SOPS secret for the FFDC OAuth client ID.

| Variable | Description | Environmental Key |
| :- | :- | :- |
| `finastra-client-id` | FFDC OAuth client ID | N/A |

### SOPS secret: `finastra-client-secret`

The following table lists the SOPS secret for the FFDC OAuth client secret.

| Variable | Description | Environmental Key |
| :- | :- | :- |
| `finastra-client-secret` | FFDC OAuth client secret | N/A |

Test and development environments can omit the SOPS secret names. The connectors forward `Authorization` and `Ocp-Apim-Subscription-Key` when the gateway uses subscription-key forwarding.

## Supported operations

The Finastra Essence connectors expose the Banking OS Unified API. For the operation-to-endpoint tables, see [Overview](https://agenticbanking.backbase.io/connectors/core-banking/finastra-essence/overview.md). For the full contract, see the [API playground](https://agenticbanking.backbase.io/banking-os-apis/api-playground.md).

## Events

These connectors are synchronous and do not publish or consume events.

## Error mapping

The connectors map Finastra vendor codes to Banking OS status codes. For the full Banking OS list, see [Error codes](https://agenticbanking.backbase.io/banking-os-apis/error-codes.md). Unmapped 4xx responses stay `GC055` from `finastra-connector-sdk`. Vendor `events` arrays are shifted to `causes` through `finastra-events-to-causes.json` before that mapping.

The following table lists the shared mappings from `finastra-connector-sdk`. A connector mapping for the same vendor code takes precedence.

| Vendor code | Banking OS code | When it occurs |
| :- | :- | :- |
| `11500025` | `GC002` | Finastra reports an expired or logged-off session. |
| `40312418` | `GC101` | Party and loan connectors: the customer ID is invalid. |
| `40312353` | `GC501` | Loan transactions: the loan account number is invalid. |
| `40001039` | `GC055` | Finastra can't find the account. The deposit connector maps this code to `GC201`. |
| `30500729` | `GC055` | Core request validation failure. |

On get accounts by party ID, the party connector returns `GC055` when Finastra doesn't recognize the party. A valid party with no accounts returns HTTP `200` with empty `deposits` and `loans` lists.

The following table lists deposit connector mappings from `application.properties`.

| Vendor code | Banking OS code | When it occurs |
| :- | :- | :- |
| `40001039` | `GC201` | Mapped Essence error on get deposit by ID. |
| `20020000` | `GC201` | Mapped Essence error on get deposit by ID. |
| `11500025` | `GC002` | Mapped Essence error on get deposit by ID. |
| `40105008` | `GC101` | Create deposit: party with the specified ID does not exist. |
| `40112664` | `GC101` | Create deposit: party with the specified ID does not exist. |
| `40112870` | `GC030` | Create deposit: specified product details are invalid. |
| `11500249` | `GC055` | Create deposit: core request validation failure. |
| `20020782` | `GC055` | Create deposit: core request validation failure. |
| `40509733` | `GC055` | Create deposit: core request validation failure. |

Do not map vendor code `40311807`. Get deposit by ID uses that code as the CASA-first breaker and falls through to the fixed-deposit path.

## Dependencies

* Finastra Fusion Essence retail HTTP APIs, reachable at `finastra.base.url`.
* Banking OS Unified API (party, deposit, and loan).
* `finastra-connector-sdk` for shared HTTP configuration and vendor error mapping.
* FusionFabric.cloud OAuth2 when you configure SOPS client credentials and `finastra.oauth.tokenUrl`.
