Directories Web Services

Transcription

1 Messaging Directories Web Services These technical specifications provide detailed information about the Directories Web Services. It is intended for developers, IT operations, and architects.

2 Public Approved Table of contents 1 Preface Purpose of this guide Related publication Interface Overview Authentication and Authorization SWIFT.com Username restrictions Web Service Return Message Return Message List of result code Web Service for the BIC Directory WSDL file BICDirectoryWSService version GetStatus ValidateBic GetAddress GetListOfDeletedBic GetListOfAddedBic Web Service for the BICPlusIBAN Directory WSDL file IbanDirectoryWSService version GetStatus ValidateNationalId ValidateIban ValidateIbanBic GetDetailsFromBic GetDetailsFromNationalId... 21

3 2.5.9 GetDetailsFromChipsUid DeriveBicFromIban LinkBic LinkNationalId GetConnectedBic Cook Book Introduction Writing a Web Service Java Client HTTPS Protocol Code Client with Axis Code Client with JAX-WS Writing a Web Service PHP Client HTTPS Protocol WSDL PHP Code Writing a Web Service PERL Client WSDL PERL Code Writing a Web Service.NET Client HTTPS Protocol Code Client with.net Code... 41

4 1 Preface 1.1 Purpose of this guide SWIFT has made a new set of web resources (Web Services Technology), available from SWIFT website. These resources allow subscribers to the Directories Web Services service to use Web Services technologies to query the SWIFT Online Directories Data. This document describes how to use this new service, and how programmers can write code to invoke the service. 1.2 Related publication To ensure correct use of the service, it is mandatory that you read the user manual before using the information contained in this guide. The user manual provides valuable information about: Password policy Subscription to the services Account management 2 Interface 2.1 Overview The Directories Web Services service is available through a service accessible through HTTPS. The service base URL is The Directories Web Services service provides two Web Services: A Web Service for the BIC Directory: This service mapped name is: /bicdirectory. A Web Service for the BICPlusIBAN Directory: This service mapped name is: /ibandirectory. 2.2 Authentication and Authorization The Directories Web Services service imposes the basic authentication method, which mandates that client applications set the HTTPS header with a username and password pair for every request. There is cookie returned to the requestor, because there is application session maintained on the server. See the RFC-2617 for a full description of Basic HTTP Authentication framework. Specifically, if HTTP client libraries other than Apache are selected, particular attention must be paid to the way the HTTP challenge is managed as the Basic HTTP Authentication method used by SWIFT is non pre-emptive method and cookie based. Please note also that our SWIFT.com infrastructure does not allow the chunked encoding in the POST method.

5 2.2.1 SWIFT.com Username restrictions The SWIFT.com Username used for the basic authentication cannot be a multi-profile SWIFT.com Username. 2.3 Web Service Return Message All services in their return message have always a result attribute. This result attribute is the main information about the status of the service execution Return Message Return Message Object XML Object Name: Object Attributes result object result /result. /object List of result code Result Code VALID VALIDOTHER INVALID INVALIDLICENSE ERRORCONTEXT INVALIDCOUNTRY UNLISTEDCOUNTRY INVALIDIBANCOUNTRY ERRORIBANLENGTH If the service request is valid (See details below in each service description) If the service request is valid (See details below in each service description) If the service request is invalid (See details below in each service description) You do not have enough privileges to execute this service. To be allowed for this service, you must have a valid subscription to the directory product. (See details below in each service description) (See details below in each service description) (See details below in each service description) (See details below in each service description) (See details below in each service description)

6 ERRORCHECKDIGITS INVALIDNATIONALID INVALIDBIC INVALIDBIC1 INVALIDCOMBINATION NOMATCHING INVALIDDATE TOOMANYRECORDS OTHERERROR (See details below in each service description) (See details below in each service description) (See details below in each service description) (See details below in each service description) (See details below in each service description) (See details below in each service description) (See details below in each service description) (See details below in each service description) An unknown exception occurs (for example: inputing a parameter of length greater than characters). 2.4 Web Service for the BIC Directory All the queries access the Live SWIFT BIC Directory which is daily updated. This assumes that the queries get always the latest SWIFT BIC Directory data WSDL file The WSDL file is located in our SWIFT.com public site: ) BICDirectoryWSService version 1.1 Service GetStatus ValidateBic GetAddress GetListOfDeletedBic GetListOfAddedBic Returns the status of the Web Service. Validates the BIC from a BIC Directory and message validation context, and returns the validation result. Gets the address about a specific institution from a BIC, and returns the information result. Gets the list of deleted BICs for a period defined by a from date and a to date. Gets the list of added BICs for a period defined by a from date and a to date GetStatus GetStatus service performs the following functions Verifies if the BIC Directory Web Service is running

7 Returns a status message Parameter Format for GetStatus ReturnMessage = getstatus() Where ReturnMessage is a String: - RUNNING : the Web Service is up and running. - ERROR : the Web Service is up and running but cannot access the Database. - INVALIDLICENSE : the Web Service is up and running, but the user does not have the right license ValidateBic ValidateBic service performs the following functions Validates 11-character BICs. If an 8-character BIC is provided then XXX is automatically added as branch code. Note that the unpublished BICs are not considered as valid. Returns a validation message Parameter Format for ValidateBic ReturnMessage = validatebic(string arg0, String arg1) Where Input Parameters: Parameter arg0 arg1 <bic> is the BIC to be validated context specifies the context in which the user wants to validate the BIC. The following values can be used: FINHEADER Check that the BIC is valid for the header of a FIN message. FINBODY Check that the BIC is valid for the body of a FIN message. NONE Check that the BIC exists, the context has no importance. Return Message: Return Message Object Object Name: BicContext Attributes

8 result biccode branchcode context XML bic result /result biccode /biccode branchcode /branchcode context /context /bic The attribute result code meanings: Result Code VALID INVALID INVALIDLICENSE ERRORCONTEXT The supplied BIC is valid for the specified context The supplied BIC does not exist or The supplied BIC exists but is not valid for the specified context. You do not have enough privileges to execute this service. To be allowed for this service, you must have a valid subscription to the Directory product. The specified context in the input parameters is not correct GetAddress GetAddress service performs the following functions Checks that the 11-character BIC exists in the BIC Directory and, if yes, it returns the address for the supplied BIC. If an 8-character BIC is provided then XXX is automatically added as branch code. Note that the unpublished BICs are not considered as valid. Returns a information message Parameter Format for GetAddress ReturnMessage = getaddress(string arg0) Where Input Parameters: Parameter arg0 <bic> is the BIC to be validated

9 Return Message: Return Message Object Object Name: BicDetails Attributes result biccode branchcode institutionname branchinformation cityheading countrycode subtype valueaddedservices extrainformation physicaladdress1 physicaladdress2 physicaladdress3 physicaladdress4 location countryname XML bicdetails result /result biccode /biccode branchcode /branchcode institutionname> /institutionname branchinformation /branchinformation cityheading /cityheading countrycode /countrycode subtype /subtype valueaddedservices /valueaddedservices extrainformation /extrainformation physicaladdress1 /physicaladdress1 physicaladdress2 /physicaladdress2 physicaladdress3 /physicaladdress3 physicaladdress4 /physicaladdress4 location /location countryname /countryname /bicdetails The attribute result code meanings:

10 Result Code VALID INVALID INVALIDLICENSE The supplied BIC exists in the BIC Directory. The supplied BIC does not exist in the BIC Directory. You do not have enough privileges to execute this service. To be allowed for this service, you must have a valid subscription to the Directory product GetListOfDeletedBic GetListOfDeletedBic service performs the following functions Checks if the period has been defined by a from date and a to date. The from date is mandatory. The to date is not mandatory. Returns the list of deleted BICs for the period defined by the from date and to date Parameter Format for GetListOfDeletedBic ReturnMessage = getlistofdeletedbic(date arg0, Date arg1) Where Input Parameters: Parameter arg0 arg1 <fromdate> is the from date. This parameter is mandatory. Date Format : YYYYMMDD <todate> is the to date. If this parameter is left empty (null), the to date will be the current date. Date Format : YYYYMMDD Return Message: Return Message List of Object Object List: BicActivationList Attributes result list (List Of BicActivation) Object Name: BicActivation Attributes biccode

11 branchcode institutionname activationdate (YYYYMMDD) XML <bicactivationlist> result /result <list> bicactivation biccode /biccode branchcode /branchcode InstitutionName> /institutionname activationdate /activationdate /bicactivation bicactivation...</bicactivation> <list> </bicactivationlist> The attribute result code meanings: Result Code VALID INVALID INVALIDDATE INVALIDLICENSE At least of one deleted BIC has been found in the BIC Directory. No result has been found. The from date or to date is invalid. You do not have enough privileges to execute this service. To be allowed for this service, you must have a valid subscription to the Directory product. TOOMANYRECORDS The query returns too many records. The WebService returns a list of BicActivation with a maximum of about 100 records GetListOfAddedBic GetListOfAddedBic service performs the following functions Checks if the period has been defined by a from date and a to date. The from date is mandatory. The to date is not mandatory. Returns the list of added BICs for the period defined by the from date and to date Parameter Format for GetListOfAddedBic ReturnMessage = getlistofaddedbic(date arg0, Date arg1) Where Input Parameters:

12 Parameter arg0 arg1 <fromdate> is the from date. This parameter is mandatory. Date Format : YYYYMMDD <todate> is the to date. If this parameter is left empty (null), the to date will be the current date of the day. Date Format : YYYYMMDD Return Message: Return Message List of Object Object List: BicActivationList Attributes result list (List Of BicActivation) Object Name: BicActivation Attributes biccode branchcode institutionname activationdate (YYYYMMDD) XML <bicactivationlist> result /result <list> bicactivation biccode /biccode branchcode /branchcode InstitutionName> /institutionname activationdate /activationdate /bicactivation bicactivation...</bicactivation> <list> </bicactivationlist> The attribute result code meanings: Result Code VALID INVALID At least of one deleted BIC has been found in the BIC Directory. No result has been found.

13 INVALIDDATE INVALIDLICENSE TOOMANYRECORDS The from date or to date is invalid. You do not have enough privileges to execute this service. To be allowed for this service, you must have a valid subscription to the Directory product. The query returns too many records. The WebService returns a list of BicActivation with a maximum of about 100 records. 2.5 Web Service for the BICPlusIBAN Directory All the queries access the Live SWIFT BICPlusIBAN Directory which is daily updated. This assumes that the queries get always the latest SWIFT BICPlusIBAN Directory data WSDL file The WSDL file is located in our SWIFT.com public site: ) IbanDirectoryWSService version 1.0 Service GetStatus ValidateNationalId ValidateIban ValidateIbanBic GetDetailsFromBic GetDetailsFromNationalId GetDetailsFromChipsUid DeriveBicFromIban LinkBic LinkNationalId Returns the status of the Web Service. Validates the National code from a National ID and a Country code, and returns the validation result. Validates the IBAN from an IBAN, and returns the validation result. Validates the combination of the IBAN and the BIC from an IBAN and a BIC, and returns the validation result. Gets details about a specific institution from a BIC, and returns the information result. Gets details about a specific institution from a National ID and a Country code, and returns the information result. Gets details about a specific institution from a Chips UID, and returns the information result. Looks up the BIC issued with the IBAN from an IBAN, and returns the information result. Provides the National ID linked to the BIC from a BIC, and returns the information result. Provides the BIC linked to the National ID and the Country code from a Country code and a National ID, and returns the

14 information result. GetConnectedBic Looks up the BIC connected to SWIFT for the non-connected BIC from a BIC, and returns the information result GetStatus GetStatus service performs the following functions Verifies if the BICPlusIBAN Directory Web Service is running Returns a status message Parameter Format for GetStatus ReturnMessage = getstatus() Where ReturnMessage is a String: - RUNNING : the Web Service is up and running. - ERROR : the Web Service is up and running but cannot access the Database. - INVALIDLICENSE : the Web Service is up and running, but the user does not have the right license ValidateNationalId ValidateNationalId service performs the following functions Checks that a national code from a specific country exists in the BICPlusIBAN Directory. Returns a validation message Parameter Format for ValidateNationalId ReturnMessage = validatenationalid(string arg0,string arg1) Where Input Parameters: Parameter arg0 arg1 <country> is the Country Code for which the national code has to be validated. nationalid is the National Code to be validated. Return Message: Return Message

15 Object XML Object Name: NationalId Attributes result countrycode uniquenationalid nationalid result /result countrycode /countrycode uniquenationalid /uniquenationalid /nationalid The attribute result code meanings: Result Code VALID INVALID INVALIDLICENSE INVALIDCOUNTRY UNLISTEDCOUNTRY The supplied NATIONAL ID exists in the BICPlusIBAN Directory for this country. The country is listed but the supplied NATIONAL ID does not exist in the BICPlusIBAN Directory for this country (it does not mean that the code does not exist in absolute). You do not have enough privileges to execute this service. To be allowed for this service, you must have a valid subscription to the Directory product.. The Country Code of the Country Code supplied is not valid (Example ZZ). Must be validated against the list of ISO country code (CT file). The national codes of this country are not listed in the BICPlusIBAN Directory (Example ZW). Indeed, the directory does not include the national codes of all world countries, so the system should first check if the country is valid or not (INVALIDCOUNTRY), and, if valid, then check if the country is a listed country of the directory ValidateIban ValidateIban service performs the following functions Validates any supplied IBAN according to the following criteria: Country code Check digits (they are calculated based on the scheme defined in ISO/IEC 7064 Modulo 97-10) IBAN NATIONAL ID contained in the IBAN IBAN total length

16 Please note that an IBAN must be provided in its electronic format: print format: CZ electronic format: CZ It will be up to the user to convert to the electronic format first (i.e. remove blank spaces) Returns a validation message Parameter Format for ValidateIban ReturnMessage = validateiban(string arg0) Where Input Parameters: Parameter arg0 iban is the IBAN to be validated. Note that IBANs have the same formats in a given country, but the formats can be different from country to country. These formats are defined in the IBAN Registry (SWIFT is the ISO registrar). The IS file of the BICPlusIBAN directory also provides a machine readable list of the IBAN formats. Return Message: Return Message Object Object Name: Iban Attributes result iban XML iban result /result iban /iban /iban The attribute result code meanings: Result Code VALID INVALIDLICENSE IBAN is valid (According to the 4 criteria! Note that we do not check the account number). You do not have enough privileges to execute this service.

17 To be allowed for this service, you must have a valid subscription to the Directory product.. INVALIDCOUNTRY INVALIDIBANCOUNTRY UNLISTEDCOUNTRY The Country Code within the supplied IBAN is not valid (Example ZZ). Is validated against the list of ISO country code (CT file). The Country Code exists but is not registered in the IBAN Registry (example ZW). Is validated against the field IBAN COUNTRY CODE in the BICPlusIBAN Directory (IS file) Previous condition (INVALIDCOUNTRY) is checked first The Country Code is registered in the IBAN Registry but the national codes of this country are not listed in the BICPlusIBAN Directory. ERRORCHECKDIGITS INVALIDNATIONALID ERRORIBANLENGTH The IBAN failed the modulus check (they are calculated based on the scheme defined in ISO/IEC 7064 Modulo 97-10). The country is listed but the supplied IBAN NATIONAL ID (retrieved from the IBAN) does not exist in the BICPlusIBAN Directory for this country (it does not mean that the code does not exist in absolute). The length of the supplied IBAN is not correct for this country ValidateIbanBic ValidateIbanBic service performs the following functions Validates any supplied IBAN according to the following criteria: Validate first if IBAN is correct Validate that the BIC is correct Derive (from the given IBAN) the BIC issued with this IBAN If the derived BIC is the same as BIC argument provided (If a 8-character BIC is provided then XXX is automatically added as BRANCH CODE), then the returned message is VALID If the derived BIC is not the same as BIC argument provided, then validate the IBAN/BIC combination. For how to validate the IBAN/BIC combination, see the BICPlusIBAN Directory Technical Specifications. Please note that an IBAN must be provided in its electronic format: print format: CZ electronic format: CZ It will be up to the user to convert to the electronic format first (i.e. remove blank spaces) Returns a validation message Parameter Format for ValidateIbanBic ReturnMessage = validateibanbic(string arg0, String arg1) Where Input Parameters:

18 Parameter arg0 arg1 iban is the IBAN to be validated. Note that IBANs have the same formats in a given country, but the formats can be different from country to country. These formats are defined in the IBAN Registry (SWIFT is the ISO registrar). The IS file of the BICPlusIBAN directory also provides a machine readable list of the IBAN formats. bic is the BIC to be validated. Return Message: Return Message Object XML Object Name: IbanBic Attributes result iban ibanbiccode ibanbranchcode ibanbic result /result iban /iban ibanbiccode /ibanbiccode ibanbranchcode /ibanbranchcode /ibanbic The attribute result code meanings: Result Code VALID VALIDOTHER INVALIDLICENSE INVALIDBIC INVALIDCOMBINATION IBAN is valid (Note that we do not check the account number) and the returned message will provide the BIC in its answer. IBAN is valid (Note that we do not check the account number) and the returned message will provide the BIC of the user and the BIC of the BICPlusIBAN Directory in its answer. You do not have enough privileges to execute this service. To be allowed for this service, you must have a valid subscription to the Directory product.. The supplied BIC does not exist. The supplied IBAN/BIC combination is not valid.

19 INVALIDCOUNTRY The Country Code within the supplied IBAN does not exist (example ZZ). Is validated against the list of ISO country code (CT file). INVALIDIBANCOUNTRY The Country Code exists but is not registered in the IBAN Registry (example ZW). Is validated against the field IBAN COUNTRY CODE in the BICPlusIBAN Directory (IS file) Previous condition (INVALIDCOUNTRY) is checked first UNLISTEDCOUNTRY The Country Code is registered in the IBAN Registry but the national codes of this country are not listed in the BICPlusIBAN Directory. ERRORCHECKDIGITS INVALIDNATIONALID ERRORIBANLENGTH The IBAN failed the modulus check (they are calculated based on the scheme defined in ISO/IEC 7064 Modulo 97-10). The country is listed but the supplied IBAN NATIONAL ID (retrieved from the IBAN) does not exist in the BICPlusIBAN Directory for this country (it does not mean that the code does not exist in absolute). The length of the supplied IBAN is not correct for this country GetDetailsFromBic GetDetailsFromBic service performs the following functions Checks that the 11-character BIC exists in the BICPlusIBAN Directory and, if yes, it returns specific info for the supplied BIC. If an 8-character BIC is provided then XXX is automatically added as branch code. Note that the unpublished BICs are not considered as valid Returns a information message Parameter Format for GetDetailsFromBic ReturnMessage = getdetailsfrombic(string arg0) Where Input Parameters: Parameter arg0 bic is the BIC to be validated. Return Message: Return Message Object Object Name: BicIbanDetails

20 Attributes result biccode branchcode institutionname branchinformation cityheading countrycode nationalid specialcode chipsuid physicaladdress1 physicaladdress2 physicaladdress3 physicaladdress4 zipcode location countryname XML bicibandetails result /result biccode /biccode banchcode /branchcode institutionname /institutionname branchinformation /branchinformation cityheading /cityheading countrycode /countrycode nationalid /nationalid specialcode /specialcode chipsuid /chipsuid physicaladdress1 /physicaladdress1 physicaladdress2 /physicaladdress2 physicaladdress3 /physicaladdress3 physicaladdress4 /physicaladdress4 zipcode /zipcode location /location countryname /countryname /bicibandetails The attribute result code meanings: Result Code VALID INVALID INVALIDLICENSE The supplied BIC exists in the BICPlusIBAN Directory. The supplied BIC does not exist in the BICPlusIBAN Directory. You do not have enough privileges to execute this service.

21 To be allowed for this service, you must have a valid subscription to the Directory product GetDetailsFromNationalId GetDetailsFromNationalId service performs the following functions Checks that the NATIONAL ID exists in the BICPlusIBAN Directory and, if yes, it returns specific info for the supplied code. Returns a information message Parameter Format for GetDetailsFromNationalId ReturnMessage = getdetailsfromnationalid(string arg0, String arg1) Where Input Parameters: Parameter arg0 arg1 country is the Country Code for which the national code has to be validated (corresponds to field COUNTRY CODE in BICPlusIBAN). nationalid is the National Code to be validated (corresponds to field UNIQUE NATIONAL ID in BICPlusIBAN). Return Message: Return Message Object Object Name: NationalIdDetails Attributes result countrycode uniquenationalid specialcode institutionname cityheading branchinformation biccode branchcode chipsuid physicaladdress1 physicaladdress2 physicaladdress3 physicaladdress4

22 zipcode location countryname XML nationaliddetails result /result countrycode /countrycode uniquenationalid /uniquenationalid specialcode /specialcode institutionname /institutionname branchinformation /branchinformation cityheading /cityheading biccode /biccode branchcode /branchcode chipsuid /chipsuid physicaladdress1 /physicaladdress1 physicaladdress2 /physicaladdress2 physicaladdress3 /physicaladdress3 physicaladdress4 /physicaladdress4 zipcode /zipcode location /location countryname /countryname / nationaliddetails The attribute result code meanings: Result Code VALID INVALID INVALIDLICENSE INVALIDCOUNTRY UNLISTEDCOUNTRY The supplied NATIONAL ID exists in the BICPlusIBAN Directory for this country. The country is listed but the supplied NATIONAL ID does not exist in the BICPlusIBAN Directory for this country (it does not mean that the code does not exist in absolute). You do not have enough privileges to execute this service. To be allowed for this service, you must have a valid subscription to the Directory product.. The Country Code of the supplied Country Code argument is not valid (Example ZZ). Is validated against the list of ISO country code (CT file). The national codes of this country are not listed in the BICPlusIBAN Directory (Example ZW).

23 2.5.9 GetDetailsFromChipsUid GetDetailsFromChipsUid service performs the following functions Checks that the NATIONAL ID exists in the BICPlusIBAN Directory and, if yes, it returns specific info for the supplied code. Returns a information message Parameter Format for GetDetailsFromChipsUid ReturnMessage = getdetailsfromchipsuid(string arg0) Where Input Parameters: Parameter arg0 chips is the CHIPS UID to be validated. Return Message: Return Message Object XML Object Name: NationalIdDetails Attributes result countrycode uniquenationalid specialcode institutionname cityheading branchinformation biccode branchcode chipsuid physicaladdress1 physicaladdress2 physicaladdress3 physicaladdress4 zipcode location countryname nationaliddetails result /result countrycode /countrycode uniquenationalid /uniquenationalid specialcode /specialcode

24 institutionname /institutionname branchinformation /branchinformation cityheading /cityheading biccode /biccode branchcode /branchcode chipsuid /chipsuid physicaladdress1 /physicaladdress1 physicaladdress2 /physicaladdress2 physicaladdress3 /physicaladdress3 physicaladdress4 /physicaladdress4 zipcode /zipcode location /location countryname /countryname / nationaliddetails The attribute result code meanings: Result Code VALID INVALID INVALIDLICENSE The supplied CHIPS UID exists in the BICPlusIBAN Directory. The supplied CHIPS UID does not exist in the BICPlusIBAN Directory. You do not have enough privileges to execute this service. To be allowed for this service, you must have a valid subscription to the Directory product DeriveBicFromIban DeriveBicFromIban service performs the following functions Validates any supplied IBAN according to the following criteria: Validate first if IBAN is correct Validate that the BIC is correct Derive (from the given IBAN) the BIC issued with this IBAN. For how to derive the BIC from an IBAN, see the BICPlusIBAN Directory Technical Specifications. Please note that an IBAN must be provided in its electronic format: print format: CZ electronic format: CZ It will be up to the user to convert to the electronic format first (i.e. remove blank spaces) Returns a information message Parameter Format for DeriveBicFromIban ReturnMessage = derivebicfromiban(string arg0) Where

25 Input Parameters: Parameter arg0 iban is the IBAN to be validated. Note that IBANs have the same formats in a given country, but the formats can be different from country to country. These formats are defined in the IBAN Registry (SWIFT is the ISO registrar). The IS file of the BICPlusIBAN directory also provides a machine readable list of the IBAN formats. Return Message: Return Message Object Object Name: IbanBic Attributes result iban ibanbiccode ibanbranchcode XML ibanbic result /result iban /iban ibanbiccode /ibanbiccode ibanbranchcode /ibanbranchcode /ibanbic The attribute result code meanings: Result Code VALID INVALIDLICENSE INVALIDCOUNTRY INVALIDIBANCOUNTRY IBAN is valid (Note that we do not check the account number) and the returned message will provide the BIC in its answer. You do not have enough privileges to execute this service. To be allowed for this service, you must have a valid subscription to the Directory product.. The Country Code within the supplied IBAN does not exist (example ZZ). Is validated against the list of ISO country code (CT file). The Country Code exists but is not registered in the IBAN Registry (example ZW).

26 Is validated against the field IBAN COUNTRY CODE in the BICPlusIBAN Directory (IS file) Previous condition (INVALIDCOUNTRY) is checked first UNLISTEDCOUNTRY The Country Code is registered in the IBAN Registry but the national codes of this country are not listed in the BICPlusIBAN Directory. ERRORCHECKDIGITS INVALIDNATIONALID ERRORIBANLENGTH The IBAN failed the modulus check (they are calculated based on the scheme defined in ISO/IEC 7064 Modulo 97-10). The country is listed but the supplied IBAN NATIONAL ID (retrieved from the IBAN) does not exist in the BICPlusIBAN Directory for this country (it does not mean that the code does not exist in absolute). The length of the supplied IBAN is not correct for this country LinkBic LinkBic service performs the following functions Checks that the 11-character BIC exists in the BICPlusIBAN Directory and, if yes, it returns the NATIONAL ID for the supplied BIC. If an 8-character BIC is provided then XXX is automatically added as branch code. Note that the unpublished BICs are not considered as valid. Makes a search on the field UNIQUE BIC CODE / UNIQUE BRANCH CODE Returns a information message Parameter Format for LinkBic ReturnMessage = linkbic(string arg0) Where Input Parameters: Parameter arg0 bic is the BIC to be validated. Return Message: Return Message Object Object Name: LinkBic Attributes result biccode branchcode

27 countrycode nationalid specialcode XML linkbic result /result biccode /biccode branchcode /branchcode countrycode /countrycode nationalid /nationalid specialcode/ /specialcode /linkbic The attribute result code meanings: Result Code VALID INVALID INVALIDLICENSE NOMATCHING The supplied BIC exists in the BICPlusIBAN Directory and a match to a national ID is found. The supplied BIC does not exist in the BICPlusIBAN Directory. You do not have enough privileges to execute this service. To be allowed for this service, you must have a valid subscription to the Directory product.. The supplied BIC exists but it does not match to a NATIONAL ID in the BICPlusIBAN Directory LinkNationalId LinkNationalId service performs the following functions Checks that the NATIONAL ID from a specific country exists in the BICPlusIBAN Directory and, if yes, it returns the 11-character BIC for the supplied code. Make a search on the fields COUNTRY CODE and UNIQUE NATIONAL ID Returns a information message Parameter Format for LinkNationalId ReturnMessage = linknationalid(string arg0, String arg1) Where Input Parameters: Parameter

28 arg0 arg1 country is the Country Code for which the national code has to be validated (corresponds to field COUNTRY CODE in BICPlusIBAN). nationalid is the National Code to be validated (corresponds to field UNIQUE NATIONAL ID in BICPlusIBAN). Return Message: Return Message Object Object Name: LinkBic Attributes result biccode branchcode countrycode nationalid specialcode XML linkbic result /result biccode /biccode branchcode /branchcode countrycode /countrycode nationalid /nationalid specialcode/ /specialcode /linkbic The attribute result code meanings: Result Code VALID INVALID INVALIDLICENSE INVALIDCOUNTRY UNLISTEDCOUNTRY National ID for the country is found and a BIC is matched (the field BIC CODE is not empty). The supplied National ID does not exist in the BICPlusIBAN Directory for this country. You do not have enough privileges to execute this service. To be allowed for this service, you must have a valid subscription to the Directory product.. The Country Code of the supplied Country Code does not exist (example ZZ). Must be validated against the list of ISO country code (CT file). The national codes of this country are not listed in the BICPlusIBAN Directory.

29 NOMATCHING The supplied NATIONAL ID exists for this country but it does not match to a BIC in the BICPlusIBAN Directory GetConnectedBic GetConnectedBic service performs the following functions Checks that the 11-character BIC exists in the BICPlusIBAN Directory and, if yes, it returns the ROUTING BIC CODE for the supplied BIC1. Checks that the proposed BIC is a BIC1 Check if the BIC1 is present in the IBAN BIC CODE/IBAN BRANCH CODE fields. If yes, then take the value of the ROUTING BIC CODE/ROUTING BRANCH CODE if they exist. If an 8-character BIC is provided then XXX is automatically added as branch code. Note that the unpublished BICs are not considered as valid. Make a search on the field IBAN BIC CODE / IBAN BRANCH CODE Returns a information message Parameter Format for GetConnectedBic ReturnMessage = getconnectedbic(string arg0) Where Input Parameters: Parameter arg0 bic is the BIC to be checked. Return Message: Return Message Object Object Name: ConnectedBic Attributes result ibanbiccode ibanbranchcode routingbiccode routingbranchcode XML connectedbic result /result ibanbiccode /ibanbiccode ibanbranchcode /ibanbranchcode

30 routingbiccode /routingbiccode routingbranchcode /routingbranchcode /connectedbic The attribute result code meanings: Result Code VALID INVALIDLICENSE NOMATCHING INVALIDBIC INVALIDBIC1 BIC1 is valid and a ROUTING BIC CODE is found. You do not have enough privileges to execute this service. To be allowed for this service, you must have a valid subscription to the Directory product.. The supplied BIC1 exists but it does not find a ROUTING BIC CODE in the BICPlusIBAN Directory. The supplied BIC does not exist. The supplied BIC exists but is not a BIC1. 3 Cook Book 3.1 Introduction In this cook book section we provided samples only for set of the most popular languages and implementations. But it does not mean that the Directories Web Services are not supported by other language or other implementation. Here worked examples showing how to access Directories Web Services from: JAVA language: JAX-WS and AXIS2. PERL language: Active Perl with SOAP Lite package PHP language: PHP with PEAR SOAP package.net language:.net 2.0 with Visual Studio For more information: see the Axis2 Apache website ( see JAX-WS Reference Implementation ( see the PEAR site ( see the.net site (

31 3.2 Writing a Web Service Java Client HTTPS Protocol As our Directories Web Services is accessible through HTTPS protocol, the virtual machine of your JAVA client should trust the SWIFT.com certificate and thus you should import the SWIFT.com certificate in your JRE. In the following example, SWIFT CA is used as the root certificate. keytool -import -keystore $JAVA_HOME/jre/lib/security/cacerts" storepass $PASS - alias "SWIFT CA" -file $CERTFILE Code Client with Axis2 First you have to generate the code client based on the Directories Web Services WSDL: dl (for BIC Directory Web Service) sdl (for BICPlusIBAN Directory Web Service) Code /****************************************************************************** * Copyright (C) S.W.I.F.T. sc All rights reserved. * *****************************************************************************/ import org.apache.axis2.axisfault; import org.apache.axis2.client.options; import org.apache.axis2.transport.http.httptransportproperties; import com.swift.ws.ibandirectorywsservicestub; import com.swift.ws.ibandirectorywsservicestub.getdetailsfromnationalid; import com.swift.ws.ibandirectorywsservicestub.getdetailsfromnationalide; import com.swift.ws.ibandirectorywsservicestub.getdetailsfromnationalidresponse; import com.swift.ws.ibandirectorywsservicestub.getdetailsfromnationalidresponsee; import com.swift.ws.ibandirectorywsservicestub.nationaliddetails; /** * Class to test the SWIFT.com BicPlusIBAN Directory WebServices.

32 * * This is to test the AXIS2 client implementation to access the SWIFT.com * Directories WebServices. * As the AXIS2 implementation uses Common HTTP * Client of apache, you have to set parameters to be compliant with the * SWIFT.com security policy The POST method encoding cannot use the chunked * encoding and the BASIC authentication must be re-active * wjoiris * */ public class BicWebServiceTest { public static void main(string[] args) throws Exception { try { String username = "your user name"; String password = "your password"; IbanDirectoryWSServiceStub stub = new IbanDirectoryWSServiceStub(); addhttpbasicauthentication(stub, username, password); /* * This sample check the IbanDirectory WebService : * getdetailsfromnationalid(string countrycode, String nationalid) */ GetDetailsFromNationalId nationalid = new GetDetailsFromNationalId(); nationalid.setarg0("ru"); // Country Code nationalid.setarg1(" "); // National Id GetDetailsFromNationalIdE nationalide = new GetDetailsFromNationalIdE(); nationalide.setgetdetailsfromnationalid(nationalid); GetDetailsFromNationalIdResponseE responsee = stub.getdetailsfromnationalid(nationalide); if (responsee!= null) { GetDetailsFromNationalIdResponse response = responsee

33 .getgetdetailsfromnationalidresponse(); NationalIdDetails nationaliddetails = response.get_return(); if (nationaliddetails!= null { && "VALID".equals(nationalIdDetails.getResult())) System.out.println("Institution Name : " + nationaliddetails.getinstitutionname()); System.out.println("City Heading : " + nationaliddetails.getcityheading()); System.out.println("Bic Code : " + nationaliddetails.getbiccode()); System.out.println("Branch Code : " + nationaliddetails.getbranchcode()); } } } catch (AxisFault fault) { fault.printstacktrace(); } } /** * Sets the BasicAuthentication object and the chunked_property in the * header. * IbanDirectoryWSServiceStub */ private static void addhttpbasicauthentication( IbanDirectoryWSServiceStub stub, String username, String password) { HttpTransportProperties.Authenticator basicauthentication = new HttpTransportProperties.Authenticator(); basicauthentication.setusername(username); basicauthentication.setpassword(password); // // Reactive basic authentication //

34 basicauthentication.setpreemptiveauthentication(false); Options options = stub._getserviceclient().getoptions(); options.setproperty( org.apache.axis2.transport.http.httpconstants.authenticate, basicauthentication); // // SWIFT Does not allow CHUNKED Encoding in the POST method // options.setproperty( org.apache.axis2.transport.http.httpconstants.chunked, false); } } Code Client with JAX-WS First you have to generate the code client based on the Directories Web Services WSDL: dl (for BIC Directory Web Service) sdl (for BICPlusIBAN Directory Web Service) Code /****************************************************************************** * Copyright (C) S.W.I.F.T. sc All rights reserved. * *****************************************************************************/ import java.util.map; import javax.xml.ws.bindingprovider; import com.sun.xml.ws.client.clienttransportexception; import com.swift.ws.bicdirectory.client.bicdetails;

35 import com.swift.ws.bicdirectory.client.bicdirectoryws; import com.swift.ws.bicdirectory.client.bicdirectorywsservice; import com.swift.ws.ibandirectory.client.ibandirectoryws; import com.swift.ws.ibandirectory.client.ibandirectorywsservice; /** * Class to test the SWIFT.com BicDirectory WebServices. * * This is to test the JAX-WS client implementation to access the SWIFT.com * Directories WebServices. * * As the HTTP Client of the JAX-WS implementation uses the pre-emptive method * for Basic Authentication, the client application needs to simulate it-self * re-active basic authentication to be compliant with the SWIFT security * policy. * * To simulate the re-active basic authentication, the * BindingProvider.SESSION_MAINTAIN_PROPERTY must be true, and a first call to * the WebService must be done to initiate the Basic Authenticatuion challenge. * wjoiris * */ public class BicWebServiceTest { public static void main(string[] args) throws Exception { /* * Instantiates the BicDirectoryWSService by passing the WSDL public url * and QNAME */ String username = "your user name"; String password = "your password"; BicDirectoryWSService s = new BicDirectoryWSService(); BicDirectoryWS bicdirectoryws = s.getbicdirectorywsport();

36 addhttpbasicauthentication(bicdirectoryws, username, password); try { /* * Initiates the authentication challenge by a first call. This will * throw automatically a ClientTransportException */ System.out.println(bicDirectoryWS.getStatus()); } catch (ClientTransportException ex) { /* * Eats the exception and checks if it is a real Unauthorized * exception */ if ("The server sent HTTP status code 401: Unauthorized".equals(ex.getLocalizedMessage())) { /* * At this stage you can start your Web Service calls */ /* * This sample check the BicDirectory WebService : * getaddress(string bic) */ BicDetails details = bicdirectoryws.getaddress("sogefrpp"); if (details!= null && "VALID".equals(details.getResult())) { System.out.println("Bic Code : " + details.getbiccode()); System.out.println("Branch Code : " + details.getbranchcode()); System.out.println("Institution Name : " + details.getinstitutionname()); } } else { throw ex; } } finally {

37 } } /** * Sets the username,the password and the session_maintain_property in the * header. * bicdirectoryws */ private static void addhttpbasicauthentication( BicDirectoryWS bicdirectoryws, String username, String password) { Map<String, Object> request = ((BindingProvider) bicdirectoryws).getrequestcontext(); // // Must be true to re-inject the cookies // request.put(bindingprovider.session_maintain_property, true); request.put(bindingprovider.username_property, username); request.put(bindingprovider.password_property, password); } } 3.3 Writing a Web Service PHP Client This sample is written with the following version: - PHP PEAR PEAR:SOAP PEAR:HTTP_Request PEAR:Net_URL PEAR:Net_Socket

38 3.3.1 HTTPS Protocol As our Directories Web Services is accessible through HTTPS protocol, the PHP client can verify the certificate or can bypass the verification. In the following example, we choose to bypass the verification WSDL The Directories Web Services WSDL: BIC Directory Web Service: dl IBAN Directory Web Service: sdl But in the following example, as the PEAR:SOAP WSDL version is not compatible with our WSDL, the example uses the ENDPOINT and the NAMESPACE Directories Web Services NAMESPACE - BIC Directory Web Service : - IBAN Directory Web Service : Directories Web Services ENDPOINT - BIC Directory Web Service : - IBAN Directory Web Service : PHP Code <html> <head><title>php - Web Services Directories - BICDIRECTORY</title></head> <body> <h2>php - Web Services Directories - BICDIRECTORY</h2> <?php require_once 'SOAP/Client.php'; $endpoint = ' $namespace = ' $proxy = array('user'=>'yourusername', 'pass' =>'YourPassWord'); $soapclient = new SOAP_Client($endPoint, false, false, $proxy); // $soapclient->setopt('curl', CURLOPT_SSL_VERIFYPEER, FALSE); // First call to enable the Basic Authentication challenge $soapclient->call('getstatus', array(), $namespace); $ret = $soapclient->call('getstatus', array(), $namespace); printf('<br>the BICDIRECTORY is <b>%s</b>', $ret);

39 echo '<br><br>'; // First call to enable the Basic Authentication challenge $soapclient->call('getstatus', array(), $namespace); $param = array('arg0' => 'SOGEFRPP'); $ret = $soapclient->call('getaddress', $param, $namespace); if (PEAR::isError($ret)) { print("<br>an error #". $ret->getcode(). " occurred!<br>"); print(" Error: ". $ret->getmessage(). "<br>\n"); } else { echo '<br>funtion : getaddress("sogefrpp"); result is : <b>'; print_r($ret); echo '</b>'; }?> </body> </html> 3.4 Writing a Web Service PERL Client This sample is written with the following version: - ACTIVEPERL SOAP-Lite 0.55-r WSDL The Directories Web Services WSDL: BIC Directory Web Service: dl IBAN Directory Web Service: sdl But in the following example, as the SOAP-Lite WSDL version is not compatible with our WSDL, the example uses the PROXY and the URI Directories Web Services URI - BIC Directory Web Service : - IBAN Directory Web Service : Directories Web Services PROXY - BIC Directory Web Service : - IBAN Directory Web Service :

40 3.4.2 PERL Code #!perl -w use use SOAP::Lite; sub SOAP::Transport:: { return 'YourUserName' => 'YourPassWord'; } print "BICDIRECTORY Service is : ", SOAP::Lite -> proxy(' cookie_jar => => 1)) -> uri(' -> getstatus() -> result; print "\n";print "\n"; my $biccode = SOAP::Data->type('string')->name( arg0 => 'ABNANL2A' ); my $service = SOAP::Lite -> proxy(' cookie_jar => => 1)) -> uri(' my $result = $service->getaddress($biccode)->result; foreach my $key (keys %{$result}) { print "$key :". $result->{$key}. "\n"; } 3.5 Writing a Web Service.NET Client This sample is written with the following version: - Visual Studio NET HTTPS Protocol Directories Web Services is accessible through HTTPS protocol, but as the.net client is running in a WEB Application, there is no specific setting to do Code Client with.net First you have to generate the code client based on the Directories Web Services WSDL: dl (for BIC Directory Web Service)

41 sdl (for BICPlusIBAN Directory Web Service) Code using System; using System.Collections.Generic; using System.Web; using System.Web.UI; using System.Web.UI.WebControls; using System.Net; using SWIFTWS; public partial class _Default : System.Web.UI.Page { protected void Page_Load(object sender, EventArgs ea) { try { // Setup cookie container CookieContainer cookiecontainer = new CookieContainer(); // Setup network credentials NetworkCredential networkcredential = new NetworkCredential("username", "password"); // Instantiate the IbanDirectory Web Service IbanDirectoryWSService ibandirectorywsservice = new IbanDirectoryWSService(); ibandirectorywsservice.cookiecontainer = cookiecontainer; ibandirectorywsservice.credentials = networkcredential; // Check if IbanDirectory Web Service is running string ibandirectorystatus = ibandirectorywsservice.getstatus(); Response.Write(string.Format("IbanDirectoryWSService Status: {0}<br/>", ibandirectorystatus)); Response.Write("<br/>"); if (ibandirectorystatus.equals("running")) { nationaliddetails nationaliddtls = null;

42 // Example of getdetailsfromnationalid nationaliddtls = ibandirectorywsservice.getdetailsfromnationalid("be", "000"); if (nationaliddtls!= null && nationaliddtls.result.equals("valid")) { Response.Write(string.Format("BIC: {0}<br/>", nationaliddtls.biccode)); Response.Write(string.Format("Branch Code: {0}<br/>", nationaliddtls.branchcode)); Response.Write(string.Format("City Heading: {0}<br/>", nationaliddtls.cityheading)); Response.Write(string.Format("Institution Name: {0}<br/>", nationaliddtls.institutionname)); } Response.Write("<br/>"); // Example of getdetailsfromnationalid nationaliddtls = ibandirectorywsservice.getdetailsfromnationalid("ru", " "); if (nationaliddtls!= null && nationaliddtls.result.equals("valid")) { Response.Write(string.Format("BIC: {0}<br/>", nationaliddtls.biccode)); Response.Write(string.Format("Branch Code: {0}<br/>", nationaliddtls.branchcode)); Response.Write(string.Format("City Heading: {0}<br/>", nationaliddtls.cityheading)); Response.Write(string.Format("Institution Name: {0}<br/>", nationaliddtls.institutionname)); } } } } else { } Response.Write("Not all web services are running!"); } catch (Exception e) { } Response.Write(e.StackTrace);