CSM Reachability - Changes & Fixes

This page covers the changes and fixes provided to CSM Reachability IPF Release 2025.3.0

CSM Reachability API

Changed

  • Added optional boolean field rMessage with default value false in the request to endpoints:

    • /v2/select-csm-agent

    • /v2/validate-csm-reachability

  • R-messages are specific transaction types like returns, reversals, recalls and rejects.

  • Some participants in the system are configured with the 'rMessageOnly' flag, meaning they are available for processing R-message transactions.

  • The rMessage flag in requests controls how participants are evaluated during the participation check.

  • When the rMessage flag is set to TRUE in the request:

    • The validation will accept both regular participants and rMessageOnly participants.

    • All participants can proceed through the reachability validation steps.

  • When the rMessage flag is set to FALSE or not provided in the request:

    • The validation will only accept regular participants.

    • Participants marked as rMessageOnly will not pass the participation check.

    • No route will be returned for rMessageOnly participants.

  • The validation process does not throw failures or exceptions when participants are not reachable. Instead, the response will indicate that no route is available, and the reachability criteria in the response will show which validation step was not met.

This change is backward compatible, so it will work without sending rMessage in the request and even without having the field rMessageOnly in the database. The default values will be false for both fields.

CSM Reachability

New

  • CSM Reachability Service now introduces a new configuration option for both IBAN Deconstruction and BIC Validation (PartyEntity lookup). By default, the service continues to use the old SWIFTRef source for IBAN Deconstruction (IBAN Plus, IBAN Structure and Exclusion List) and BIC Validation (BicDir2018).

  • To switch to the new source of industry data (SWIFTRef_Identifiers_All), set the following:

# Two possible modes:
#   "legacyPortfolio"        → Old option - uses ExclusionList + IBAN Plus only for IBAN Deconstruction and BicDir2018 for Bic Validation
#   "evolvedPortfolio"       → New option - uses PartyEntity lookup for both IBAN Deconstruction & BIC Validation
#
# Default is the old way ("legacyPortfolio")
ipf.csm-reachability.swift-ref-version = "evolvedPortfolio"

  • It is important to note that all services (endpoints) that call IBAN Deconstruction will be impacted with this switch as well.

Before enabling the new option it is required to ingest all necessary SWIFTRef_Identifiers_All data (IDENTIFIERS-ALL and FORMATS-CTRY/FORMATS-ALL files described under Data Ingestion part below).

IBAN deconstruction should work as expected in most cases but an incorrect IBAN BIC may be derived when the IBAN National Id value matches across more than one clearing system / country. This is a known issue and will be fixed in the next release. Client implementations can use evolved SWIFTRef portfolio for testing purposes but should wait for the bug PAY-15778 to be fixed and released before the evolved SWIFTRef portfolio is used in LIVE environments.

  • Added new searchable fields and indexes for Party Entity collection:

    • entityUniqueId

    • ibanId

ipf.dps.mongodb.index-config.partyentity {
    index-14 = ["values.payload.entityUniqueId:ASC"]
    index-15 = ["values.payload.ibanIdentifiers.ibanId:ASC"]
}

  • Added lastUpdatedAt as default index on all settings collections.

ipf.dps.mongodb.index-config.<setting-type> {
    index-x = ["lastUpdatedAt:ASC"]
}

Processing Entity Support

An optional processingEntity parameter is now supported across all relevant Dynamic Processing Settings (DPS) endpoints. Callers can pass this parameter to ensure that:

  • Only data belonging to the specified PE is read or updated.

  • Data belonging to other PEs is invisible (the API behaves as if those records do not exist).

If the parameter is omitted, APIs behave exactly as before.

The parameter can be supplied either in the request body or as a query/path parameter, depending on the specific endpoint.

For more details on processing entity handling on DPS endpoints used by dynamic configurations on CSM reachability service, please refer to IPF-2025.3.0 - DPS Release Notes for the functionality.

Changed

Party Entity model updated

  • New fields on Party Entity

    • parentEntityId

    • groupEntityId

    • routingIdentifiers (swiftFinPlusBic & swiftFinPlusDn)

    • ibanIdentifiers (ibanId & ibanBic)

  • PartyEntity setting logicalUnique key is different depending on the source from where the data is coming from. If the data is coming from an IDENTIFIERS-ALL file, then the logical unique key is the combination of data source, identifier value, identifier type and entity unique id. If the data is coming from other sources, then the logical unique key is the combination of data source, country and entity unique id.

IbanStructure model updated

  • New fields on Iban Structure

    • ibanNationalIdType

    • ibanNationalIdPosition

CSM Participant model updated

  • field routingBIC marked as Deprecated, but still mapped for some CSM Directories for backward compatibility purposes

  • new field csmMemberId - The Id of the member as specified by the CSM. This may not be an industry identifier used on the payments but a code that CSM assigns to identify a member that participates in the CSM using multiple industry identifiers. This can be a common member code assigned by the CSM to a member while the member can have multiple participant Identifiers under it.

  • new field directParticipantDetails - Details of the participant that owns the settlement account. For indirect participants, this attribute can hold the details of the direct participants.

  • new field routingDetails - The identifiers that can be used for different purposes: Standard - for routing the payments to the participant; Return - for routing returns to the participant; Redirection - for routing the payments or returns where "Redirection" routing identifiers are available

    • csmMemberId added to searchable fields, so it’s recommended that index is created for this field

  • new boolean field rMessageOnly - The value of true indicates a participant can ONLY receive Rmessages (returns, reversals, recalls, rejects); a false value means any/all transactions can be received by the participant. Default value is false.

Get Party Entities and Party Entity LookUp logic

  • Updated the logic to get Party Entity details:

    • HeadOffice Party Entity is picked primarily if it exists.

    • For SWIFTRef_Identifiers_All data source, identifiers are joined together from all Party Entity records with the same entityUniqueId.

Determine Processing Entity Participant Identifier

Participant Identifiers extraction logic for Processing Entity lookup:

  • for direct Participants - Participant Identifier value, with Agent Setting Type and Subtype is returned

  • for indirect Participant - Participant Identifiers are sourced from their Direct Participant Details.

  • for legacy Participants - routing BIC is used, with Identifier BIC, Identifier Subtype SCHEME_MEMBERSHIP_BIC

Data Ingestion

New

  • Ingestion of SWIFTRef IDENTIFIERS-ALL file to Party Entity collection. Each entry from file represents one Party Entity record with one entity identifier. Entity Data Source for this type of ingestion is SWIFTRef_IDENTIFIERS-ALL.

  • Ingestion of SwiftRef FORMATS-ALL and FORMATS-CTRY files to Iban Structure collection. There are two new fields being mapped on the Iban Structure data from these files, ibanNationalIdType and ibanNationalIdPosition.

  • Important configuration regarding these new files ingestion is provided below:

ipf.csm-reachability.party-entity.identifiers {
    enabled = true
    file-ingestion {
      directory-id = "party-entity-identifiers"
      files-directory = "import/party-entity-directory/party-entity-identifiers/"
    }
}
ipf.csm-reachability.iban-structure.formats {
    enabled = true
    file-ingestion {
      directory-id = "iban-structure-formats"
      files-directory = "import/iban-plus-directory/iban-structure-formats/"
    }
}
ipf.file-ingestion.directory-mappings += {
  "directory-id": "party-entity-identifiers",
  "job-name": "PartyEntity Identifiers All Import"
}
ipf.file-ingestion.directory-mappings += {
  "directory-id": "iban-structure-formats",
  "job-name": "IbanStructure Formats Import"
}

  • These new SwiftRef files can come as Full, Daily Delta and Monthly Delta files with modifications flags of A/M/D. They can also have future records with start date in future which will be interpreted as scheduled settings.

It is recommended that client implementations carry out testing with evolved SWIFTRef functionality (Party entity look up, IBAN deconstrution) using Full versions of files from SWIFT. Icon do not have access to full files. While confidence level of the feature development done using sample files are high, testing using sample files does not put the product through all possible data variabilities offered by full files. Any issues seen during full file testing should be raised with Icon so they can be addressed ahead of evolved SWIFTRef use being enabled in LIVE by client implementations.

Changed

  • Logical Unique Key for CSM Participant records is updated to below:

    • CSMAgentId

    • CSMParticipantIdentifier

    • ParticipantType (if present)

  • Mapping for TIPS File - Participant Fields:

    • routingBIC → mapped from accountOwnerBIC (instead of partyBIC)

    • csmMemberId → mapped from partyBIC

    • routingDetails → mapped from accountOwnerBIC

    • directParticipantDetails → mapped from accountOwnerBIC, when the participant is INDIRECT

  • RT1 and STEP2 Full file ingestion - Records with statuses CHANGED and R-ONLY are being processed in addition to the currently processed records with ENABLED status.

    • if record has status ENABLED, then Participant will have field rMessageOnly set to false

    • if record has status CHANGED or R-ONLY, then Participant will have field rMessageOnly set to true

    • rMessageOnly value of true indicates a participant can ONLY receive Rmessages (returns, reversals, recalls, rejects)

  • Local file ingestion now has a new configuration property timestamp-archived-and-failed-files with default value set to true. This means that we now, by default add timestamps to files that end up in /archive and /failed directories. (e.g., file_20251020_143530.xml). This can be disabled by setting the property to false. Default file ingestion configuration now looks like this:

      default-file-ingestion {
        files-directory = "/import"
        initial-delay = 5s
        interval = 30s
        timestamp-archived-and-failed-files = true
      }
This change for RT1 and STEP2 Full file ingestion is backward compatible. There is no need for any migration script for database, since Mongo/CosmosDB are used documents will be saved without issues with or without this new field rMessageOnly. Absence of this field will be treated as if it had value false.

Breaking Changes

  • It is strongly recommended that the next set of files that are ingested into CSM Participant after taking on the release 2025.3 are FULL files. Any delta files can be resumed after ingesting full files but the first set of files to be ingested after this release must be full files.

  • It is strongly recommended that all SwiftRef file ingestion processes (IDENTIFIERS-ALL & FORMATS-ALL/FORMATS-CTRY) should be primarily done as FULL file ingestion to have all relevant data structures updated properly.

  • BDD Tests configuration class com.iconsolutions.ipf.dynamicsettings.test.SharedSteps constructor changed

    • Added new parameter: List of Request Types, to SharedSteps constructor.

    • This was done in order to support testing of future API versions.

    • If you are using this class, or extending it, please update your code accordingly, eg:

      public E2ESteps e2ESteps(CommonTransportSteps commonTransportSteps, DynamicProcessingSettingsBaseSteps baseSteps, SettingApiClient settingApiClient) {
    List<RequestTypeInterface> requestTypes = new ArrayList<>();
    requestTypes.addAll(Arrays.stream(SettingManagementApiRequestType.values()).toList());
    requestTypes.addAll(Arrays.stream(ReachabilityApiRequestType.values()).toList());
    return new E2ESteps(commonTransportSteps, baseSteps, settingApiClient, requestTypes);
} ...

Performance

Recommended settings for Party Entity ingestion:

  • Throughput: 30000 RUs (Cosmos DB schema)

  • Parallelism: 16 (ipf.csm-reachability.settings-api.direct.parallelism in ConfigMap)

These values were determined through performance testing. They are important for ingesting a BANKDIRECTORYPLUS full file (~1.5 million records), reducing ingestion time from about 175 minutes to about 45 minutes.

Recommended Throughput for Party Entity ingestion for IDENTIFIERS-ALL full file:

Size of the file: ~4.9 million records, but after some filtering operations, 3 115 384 records are ingested.

  • Throughput: 30000 RUs (Cosmos DB schema)

  • Parallelism:

  • Direct parallelism: 8 (ipf.csm-reachability.settings-api.direct.parallelism in ConfigMap)

  • Party entity identifiers parallelism: 5 (ipf.csm-reachability.settings-api.party-entity-identifiers.parallelism in ConfigMap)

  • Party entity parallelism: 8 (ipf.csm-reachability.settings-api.party-entity.parallelism in ConfigMap)

These values were determined through performance testing, with ingestion time ~160 minutes .

For both Bank_Directory_Plus and SWIFTRef_IDENTIFIERS-ALL data sources, adjust as needed, according to future load testing and business requirements.