Documentation for a newer release is available. View Latest

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.

Industry Reference Data

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

Industry Data	Purpose	Additional References
IBAN Structure Directory	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	The dynamic configuration provides	IBAN Plus Directory
IBAN Exclusion List	Column 2, row 3	Exclusion List Directory

Industry Data

Purpose

Additional References

IBAN Structure Directory

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

The dynamic configuration provides

IBAN Plus Directory

IBAN Exclusion List

Column 2, row 3

Exclusion List Directory

Usage

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.
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.
ibanCountry	Indicates the country that has issued the IBAN. This can be different from the entityCountry.
bankIdentifier	The bankIdentifier as defined on IBANPlus Directory.
ibanNationalId	ibanNationalId as defined on IBANPlus Directory.
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.

Response Property

Description

entityCountry

Indicates the country in which the entity that holds the IBAN is located.

ibanCountry

Indicates the country that has issued the IBAN. This can be different from the entityCountry.

bankIdentifier

The bankIdentifier as defined on IBANPlus Directory.

ibanNationalId

ibanNationalId as defined on IBANPlus Directory.

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.

The IBAN deconstruction relies on the industry data provided by SWIFTRef. Specifically, the IBAN Structure, IBAN Plus and IBAN Exclusion List. In case if the entities that have issued the IBANs have not registered themselves on IBAN Plus, IBAN Deconstruction will not be possible.
1. There is an exception, which is IBANs issued by Switzerland in which case IBAN Deconstruction is possible and reachability checks using deconstruction can be performed for domestic payment systems (Reachability checks for regional or international payment schemes that rely on BICs is not possible).

For all other countries, if the entities issuing IBANs are not registered on IBAN Plus, IBAN deconstruction and reachability checks to domestic, regional and international payment schemes will not be possible (Reason Code IPFRCH002).

Some countries do not issue NCCs as the account numbers are issued by the central banks, in these cases, NCCs will not be returned as they are not defined by the entities.
The subtype associated with the identifier of type BIC will be SCHEME_MEMBERSHIP_BIC as the BICs are used by entities for scheme membership purposes.
The Sub-Type for NCC type identifier is mapped to an ISO20022 aligned External Clearing System code where one is issued. If the NCC codes issued in the countries do not have an ISO20022 aligned code, a subtype will not be returned.
Below is a list of NCC subtypes that will be returned for given countries that issue IBANs. In future more countries can have the ISO20022 aligned subtypes returned (ES, GR, IT, PT, PL, SE).

IBAN Country Code

NCC SUbType (ISO20022 Aligned)

ATBLZ

CHBCC

DEBLZ

GBDSC

IENCC

MZBMO