Finastra Essence reference

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

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. For the full contract, see the API playground.

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

Get started

Core banking

Payments

Card management

KYC and KYB

Open Banking

CRM

Fraud detection

Financial data aggregation

Configuration properties

Values to obtain from Finastra

gc-finastra-party-connector

gc-finastra-deposit-connector

gc-finastra-deposit-transaction-connector

gc-finastra-loan-connector

gc-finastra-loan-transaction-connector

SOPS secrets

SOPS secret: `finastra-client-id`

SOPS secret: `finastra-client-secret`

Supported operations

Events

Error mapping

Dependencies

Configuration properties

Values to obtain from Finastra

gc-finastra-party-connector

gc-finastra-deposit-connector

gc-finastra-deposit-transaction-connector

gc-finastra-loan-connector

gc-finastra-loan-transaction-connector

SOPS secrets

SOPS secret: finastra-client-id

SOPS secret: finastra-client-secret

Supported operations

Events

Error mapping

Dependencies

SOPS secret: `finastra-client-id`

SOPS secret: `finastra-client-secret`