3. /iban/deconstruct

Purpose

IBAN Deconstruct API enables an IBAN to be deconstructed to provide details of the entity that has issued the IBAN. The details provided on the response include 'Scheme Membership BIC' associated with the IBAN, national clearing code, the country where the issuing entity is located as well as IBAN National ID and Bank Identifier as registered on industry files.

Configuration

IBAN deconstruction can be performed using dynamic configurations populated using both legacy SWIFTRef portfolio and with evolved SWIFTRef portfolio. Client implementations who wish to switch from legacy portfolio to the evolved portfolio can do so using the configuration ipf.csm-reachability.swift-ref-version. Refer the configuration on application.conf

Configuration Value Portfolio Dynamic Configurations Used Industry Files Used

legacyPortfolio

SWIFTRef legacy portfolio

IBAN Plus, IBAN Structure, Exclusion List

IBAN Plus, IBAN Structure, Exclusion List

evolvedPortfolio

SWIFTRef evolved portfolio

Party Entity Directory (Source - Identifiers All), IBAN Structure

SWIFTRef Identifiers All, SWIFTReg FORMATS-ALL/SWIFTReg FORMATS-CTRY
Default value of the configuration is set to legacyPortfolio for backward compatibility purposes for clients who already use IBAN deconstruction using legacy portfolio.

Dynamic Configurations Used

IBAN Deconstruct uses the industry data dynamic configurations to deconstruct the IBANs. The dynamic configurations are required to be populated through ingestion of relevant industry files provided

Based on the configuration value used, IBAN Deconstruct uses below dynamic configurations.

Industry Data Used with SWIFTRef portfolio Purpose Additional References

IBAN Structure Directory

legacyPortfolio, evolvedPortfolio

The dynamic configuration provides the structure of IBANs across different countries including position and length of relevant identifiers that are embedded on the IBANs issued in those countries.

IBAN Structure Directory

IBANPlus Directory

legacyPortfolio

The dynamic configuration provides IBAN Plus entries to facilitate the IBAN deconstruction

IBAN Plus Directory

IBAN Exclusion List

legacyPortfolio

The dynamic configuration provides the exclusion list to verify if the provided IBAN is on the exclusion list provided by the industry source.

Exclusion List Directory

Party Entity Directory

evolvedPortfolio

Provides IBAN identifiers associated with the entities to help with IBAN deconstruction.

Identifiers All to Party Entity Directory mapping

Usage

  1. Client implementations can call the endpoint /iban-deconstruct to deconstruct an IBAN and to get the details of the entity that has issued the IBAN.

  2. IBAN Deconstruct implementation is also used internally by different CSM Reachability services to deconstruct the IBAN and use the entity details to perform reachability checks or party entity look-ups. Below CSM Reachability endpoints use IBAN deconstruct internally (Refer CSM Reachability Operations)

    1. Validate Intra Entity Reachability

    2. Validate CSM Reachability

    3. Select CSM Agent

    4. Party Entities

    5. Determine Processing Entity

Request and Response

IBAN Deconstruct follows below request and response structure. This section provides information on the request and response properties, for detailed API specs, please refer CSM Reachability Service API

API Version 2

Request

Request Property Description

IBAN

The IBAN to be validated and deconstructed

Response

Response Property Description

entityCountry

Indicates the country in which the entity that holds the IBAN is located. In evolvedPortfolio mode, this is derived from Party Entity. In legacyPortfolio mode, this is derived from IBAN Plus.

ibanCountry

The country that has issued the IBAN.

bankIdentifier

The bankIdentifier as defined on the industry source

ibanNationalId

IBAN National Id associated with the IBAN

entityIdentifiers (*)

1. A list of identifiers derived from the IBAN using IBANPlus and IBAN Structure dynamic configurations. The identifier types returned are of type BIC and NCC.

2. Refer Party Identifiers Explained for more details on identifier types supported on CSM Reachability Service.

+identifier

The identifier value for the entity associated with the IBAN.

+IdentifierType

The type value associated with the entity identifier.

+identifierSubType

Subtype of the identifier type returned.

Notes

  1. The IBAN deconstruction relies on the industry data provided by SWIFTRef.

    • In legacyPortfolio mode: IBAN Structure, IBAN Plus and Exclusion List are required.

    • In evolvedPortfolio mode: IBAN Structure and Party Entity Directory are required, with IBAN Plus used only as fallback.

  2. If the entities associated with the IBAN are not present on the dynamic configurations, IBAN BIC derivation may not be possible, though NCC can be derived. (When using legacyPortfolio, if the entries are not present on IBAN Plus, IBAN deconstruction is only possible for Swiss IBANs).

  3. Some countries do not issue NCCs as account numbers are assigned by central banks. In these cases, NCCs will not be returned.

  4. NCC subtype mapping (ISO20022 aligned codes):

IBAN Country Code NCC SUbType (ISO20022 Aligned)

AT

ATBLZ

CH

CHBCC

DE

DEBLZ

GB

GBDSC

IE

IENCC

MZ

MZBMO