fscd-adapter:
payment-returned:
enabled: true # enables the listener
return-reasons:
"901": "AC01" # IBAN incorrect
"902": "AC04" # Account closed
"903": "AC06" # Konto blocked
# ... additional mappingsRelease Notes
This section documents changes introduced since release 25.7.0.
26.1.0
New Features and Improvements
Improve Fscd-Adapter Auto-Configuration (PNC-3031)
A new auto-configuration module de.faktorzehn.fscd-adapter:fscd-adapter-autoconfigure has been introduced to ease customization of fscd-adapter beans.
All beans are now auto-configured with @ConditionalOnMissingBean and can thus be easily replaced.
As a result, some configuration properties have been moved and renamed.
| Old Property Name | New Property Name |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Kafka Listener for Payment Returns from FS-CD (PNC-2539)
The FS-CD Adapter now processes payment return notifications from FS-CD and automatically reports them to the appropriate ICS system via REST API. This enables automated handling of failed payments (e.g., SEPA returns) by notifying the claims system when payments cannot be processed.
Functionality
When FS-CD detects a payment return (Zahlungsrückläufer), it publishes an Info Container message to the Kafka topic de.faktorzehn.fscd.payment-returned.
The FS-CD Adapter processes these messages and calls the ICS REST endpoint /rest/paymentupdate to report the payment failure.
The adapter automatically:
-
Extracts claim number and position number from the Info Container
-
Maps FS-CD return reason codes (
RLGRD) to ICS payment failure types (SEPA codes) -
Resolves the target ICS system using the business system identifier (
BCON_BUSSYS) -
Reports the payment failure to the appropriate ICS instance
Configuration
The return-reasons mapping translates FS-CD return reason codes to SEPA failure codes as required by the ICS payment update API.
Error Handling
The listener uses Spring Kafka’s retry mechanism with exponential backoff for transient failures. Messages that cannot be processed after all retries are forwarded to a dead letter topic for manual investigation.
Improve Modularity by Splitting Kafka Module (PNC-2824)
The Maven module fscd-adapter-kafka has been split into multiple, focused modules to improve modularity, reduce transitive dependencies, and better separate domain-specific concerns.
New Module Structure
| Module | Description |
|---|---|
|
Shared foundation providing base classes, interfaces, and common utilities for Kafka event processing |
|
ICS event processing including claim payments, receivables, reserve changes, and failed payments |
|
Core IPM policy editing event processing with baseline mapping logic |
|
IPM-Base (IB) specific policy editing customizations and auto-configuration |
|
IPM-Basis (VB) specific policy editing customizations and auto-configuration |
This modular structure allows projects to include only the event listeners they need, reducing dependency footprint and clarifying architectural boundaries.
Package Restructuring
The package de.faktorzehn.fscdadapter.kafka.shared has been merged into de.faktorzehn.fscdadapter.kafka, providing a cleaner package structure.
Migration Guide
-
Update dependency declarations
Replace the singlefscd-adapter-kafkadependency with the specific modules needed:<!-- Before --> <dependency> <groupId>de.faktorzehn.fscd-adapter</groupId> <artifactId>fscd-adapter-kafka</artifactId> </dependency> <!-- After: Include only what you need --> <dependency> <groupId>de.faktorzehn.fscd-adapter</groupId> <artifactId>fscd-adapter-kafka-ics-core</artifactId> </dependency> <dependency> <groupId>de.faktorzehn.fscd-adapter</groupId> <artifactId>fscd-adapter-kafka-ipm-base</artifactId> </dependency> -
Update static ReferenceFactory calls
Replace static utility calls with dependency-injected instances.
Deleted Posting Tax Fields (PNC-3025)
The unused fields Posting.valueAddedTaxKey and Posting.otherTaxKey have been deleted.
If required, use Posting.extensions instead.
Support for Multiple IPM/ICS Systems (PNC-2247)
The FS-CD Adapter now supports operation with multiple IPM and ICS systems.
Changes to Mapper Strategy
The mapper strategies shu and kf have been merged into a single strategy called shuk.
Origin System
New configuration properties have been introduced under fscd-adapter.origin-system, replacing the following properties:
| Old Property | New Property |
|---|---|
|
|
|
|
|
|
Furthermore, the name originSystem is now used consistently:
-
The property
InsuranceObject.systemhas been renamed toInsuranceObject.originSystem.
Changes to BusinessObjectReader
To enable passing the originSystemId from a BusinessObjectReader to the InsuranceObjectMapper for persistence in FS-CD, all readers have been adjusted to return a wrapper object instead of a direct DTO response type.
| Old Return Value | New Return Value |
|---|---|
PolicyEditingDto |
PolicyEditingReading |
ReserveChangeInformationResponseDataDto |
ReserveChangeReading |
If any of the following beans have been defined, the generic type T must be adjusted accordingly:
-
TxoEventListener<T> -
BusinessObjectReader<T> -
BusinessObjectProcessor<T> -
ActionDetermination<T> -
InsuranceObjectMapper<T> -
PostingsMapper<T>
If a custom ReferenceFactory exists, it must also be adjusted to use the new types.
API Clients
The clients used to read data from ICS and IPM are now created based on the TxoEvent.baseUrl.
As a result, the following properties have been removed:
fscd-adapter.policy-editing.ipmBaseUrl
fscd-adapter.policy-editing.icsRestPath
fscd-adapter.reserve-change.icsBaseUrl
fscd-adapter.reserve-change.icsRestPathThe property fscd-adapter.origin-system.<system id>.rest-path (default: /rest) is used to build API client URLs by appending the value to the baseUrl from the TxoEvent.
For this to work, clients now need to be built on demand during event processing. BusinessObjectReader therefore now requires a ClientCache<T> instead of a client directly.
The new class instantiates clients based on the URL and caches the instances.
Additional Changes
-
MappingPropertiesHelper.findMappingnow returnsOptional<String>instead of throwing an exception when no mapping is found. A methodfindMappingOrThrowhas been added, which behaves like the original method.
Refactor Policy Editing Integration (PNC-2491)
When processing a policy editing event from IPM, two API calls are now made to IPM to collect all relevant information.
Previously, only the PolicyEditingClient was used.
Now, the PolicyVersionClient is additionally used to read the current premium payer, correspondence recipient, and policyholder.
A custom ClientCache<PolicyVersionClient> bean can be defined to override the default implementation if necessary.
Balanced Accounts Support (PNC-2126)
The FS-CD Adapter and the Info Tool now support displaying and managing balanced accounts by calling 2 new FS-CD function modules.
The FscdInsuranceObjectService service has been extended:
-
FscdInsuranceObjectService.readInsuranceObjectwith JCo implementation forBAPI_INSOBJECT_GETDETAIL- retrieves detailed information for specific insurance objects -
FscdInsuranceObjectService.readInsuranceObjectswith JCo implementation forBAPI_INSOBJECT_GETLIST- retrieves lists of insurance objects for a partner
A new class JcoFunctionToObjectMapper has been introduced to support these BAPI calls, and as a result, JcoFunctionMapper has been renamed to ObjectToJcoFunctionMapper.
New REST endpoints are now available:
-
GET /partners/{partnerNo}/insurance-objects- retrieves all insurance objects for a specific partner -
GET /partners/{partnerNo}/insurance-objects/{insuranceObjectNo}- retrieves detailed information for a specific insurance object
The tenant is now displayed in the InsuranceObjectView.
A mapping can be provided to map the tenant ID to a name using a DomainValueSource attribute called tenant:
tenant.1=ConVista Holding GmbH
tenant.2=Faktor Zehn GmbHJcoTableMapper has been extended with an additional parameter Map<String, Object> context. JcoInsuranceObjectService leverages this new parameter to pass the partnerNo to the mapper.
Claim Payments Integration (PNC-2257)
The FS-CD Adapter now supports processing of claim payments from ICS.
-
Listening to Kafka topic
de.faktorzehn.ics.event.payment-transferred -
Supporting configurable mapping properties for different claim payments types
For more customization and technical details see Customize Claim Payments.
Failed Claim Payments Integration (PNC-2503)
The FS-CD Adapter now supports processing of failed claim payment events from ICS.
-
Listening to Kafka topic
de.faktorzehn.ics.event.payment-failed -
Uses the same mapping configuration from claim payments
For more customization and technical details see Customize Failed Claim Payments.
Receivables Integration (PNC-2256)
The FS-CD Adapter now supports processing of receivables from ICS.
-
Listening to Kafka topic
de.faktorzehn.ics.event.receivable-transferred -
Supporting configurable mapping properties for different receivable types
For more customization and technical details see Customize Receivables.
Companies Configuration (PNC-1753
The company code mapping configuration for postings has been replaced by an adapter-wide configuration for companies, see Company Code Mapping.
As a result the following properties have been removed from individual listener mapping configurations:
| Removed Property | Affected Listener |
|---|---|
|
Reserve Change |
|
Reserve Change |
|
Policy Editing |
|
Policy Editing |
Read and Write SEPA Mandates (PNC-2452
The FS-CD Adapter now supports reading and writing SEPA mandates via Java and REST services, see Sepa Mandates Service and OpenAPI Documentation .
Standardized Return Types (PNC-2797)
The return types of RestController and all services from the business module have been standardized to use the new generic Result<T> type instead of domain-specific result classes.
Service Return Type Changes
The following service interfaces now return generic Result<T> types:
| Service | Old Return Type | New Return Type |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Helper Methods
The FscdAccountBalanceService interface now provides new default methods for reading open account balances:
-
readOpenAccountBalance(String partnerNo, String insuranceObjectNo)- returns the first open account balance ornullif none exists -
readOpenAccountBalances(String partnerNo)- returns all open account balances for a partner
These methods replace the removed helper methods AccountBalancesResult.getAccountBalanceBy and AccountBalancesResult.findOpenByInsuranceObjectNumber.
Additionally, the ResultHelper class has been removed.
Its utility methods are now available directly on the Result class.
REST API Compatibility
The REST API JSON responses remain unchanged. While the Java return types have been standardized, the serialization format stays the same, ensuring backward compatibility for REST API clients.
JcoTableMapper and JcoFunctionToObjectMapper
The JcoTableMapper.map method now returns Result<List<T>> instead of T.
Similarly, the JcoFunctionToObjectMapper.map method now returns Result<T> instead of T.