Developers

GetBranchByLocation

Important note.

All BankVal web services are mirrored at two independent data centres. Using this configuration, the BankVal web service has been available continuously since launch in 2003.

In general:

  • Call the service at the primary data centre at www.unifiedservices.co.uk
  • In the unlikely event of a failure, call the service at the secondary data centre at www.unifiedsoftware.co.uk

1 GetBranchByLocation - REST


GetBranchByLocation functionality:

  • Lookup bank branches worldwide by bank name and city. Returns list of information for bank branches.

Follow these three steps:-

  • 1. Attempt to access the service on unifiedservices.co.uk
  • 2. Check the http response code
  • 3. If this is < 200 or > 399, access the backup service on unifiedsoftware.co.uk

URI for GetBranchByLocation

  • GET https://www.unifiedservices.co.uk/services/bankvalint/branchbylocation/userid/<userid>/pin/<pin>/name/<bank name>/city/<city>/<format>/
  • If http response code is < 200 or > 399 then call:-
  • GET https://www.unifiedsoftware.co.uk/services/bankvalint/branchbylocation/userid/<userid>/pin/<pin>/name/<bank name>/city/<city>/<format>/

where:

  • <userid> and <pin> are your user ID and 5 digit PIN obtained upon registration at:
    www.unifiedsoftware.co.uk/free-trial/free-trial-home.html
  • <bank name> is the name or partial name of the bank for which the branch list is to be returned.
  • <city> city for which the bank list is to be returned.
  • <format> specifies the format of the returned data. Valid formats are csv, xml and json. (csv uses the "|" delimiter)

Results (csv format)

If bank name and city are recognised, a list of branches is returned. Branch records are separated by "?". Each branch record has the following structure:

  • First field - contains word VALID
  • Remaining fields - contain data from SWIFT BIC directory, i.e. SWIFTBIC|branch|name|binfo|city|
    subtype|vas|extra|address1|address2|address3|address4|location|country|pob_number|pob_location|pob_country

Example Valid Results

Sample valid response in xml format :-

<branchlist>

<branchdets>

  • <result>VALID<result>
  • <bic>BARCGB22</bic>
  • <branch>XXX</branch>
  • <name>BARCLAYS BANK</name>
  • <binfo>(ALL U.K. OFFICES)</binfo>
  • etc...

</branchdets>

<branchdets>

  • <result>VALID<result>
  • <bic>BARCGB22</bic>
  • <branch>123</branch>
  • <name>BARCLAYS BANK</name>
  • <binfo>LONDON</binfo>
  • etc...

</branchdets>

</branchlist>


Sample valid response in json format :-

  • {"result":"VALID",
  • "bic":"BARCGB22",
  • "branch":"XXX",
  • "name":"BARCLAYS BANK",
  • "binfo":"(ALL U.K. OFFICES)",
  • etc...
  • }
  • {"result":"VALID",
  • "bic":"BARCGB22",
  • "branch":"123",
  • "name":"BARCLAYS BANK",
  • "binfo":"LONDON",
  • etc...
  • }

Sample valid response in csv format :-

  • VALID|BARCGB22|XXX|BARCLAYS BANK|(ALL U.K. OFFICES)|etc... |?VALID|BARCGB22|123|BARCLAYS BANK|...

Error messages :-

Error Messages

INVALID - Result Format - Problem, with format field in URI.

ERROR - Invalid User ID/PIN - The User ID or PIN has not been recognised.

ERROR - UserID Expired - Trial user ID has expired.

ERROR - Insecure Connection - An attempt was made to access BankVal's GetBankDetails2 method using insecure HTTP protocol instead of HTTPS.


<< Back to Top >>


2 GetBranchByLocation - SOAP


GetBranchByLocation functionality:

  • Lookup bank branches for a given bank in a given city. Returns list of bank branch information.

Choose SOAP style:

We provide two SOAP APIs - Document Literal and RPC. For help choosing the best solution for your implementation, please contact support@unifiedsoftware.co.uk.



<< Back to Top >>


2.1 GetBranchByLocation - SOAP Document Literal


GetBranchByLocation functionality:

  • Lookup branch information for a given bank in a given city. Returns list of bank branch information.

Request

Parameters

Description

userid

BankVal UK User ID.

pin

5 digit PIN.

bank name

Name of the owning bank.

city

Name of the city.


Response (multiple occurring records)

Field

Description

result

Result string contains on of the following messages:-
VALID - SWIFT BIC is valid.
ERROR - Invalid User ID/PIN - The User ID or PIN has not been recognised.
ERROR - UserID Expired - Trial user ID has expired.
ERROR - Insecure Connection - An attempt was made to access BankVal's getbranchbylocation method using insecure HTTP protocol instead of HTTPS.

bic

SWIFT Bank Identifier Code

branch

Branch code

name

Name of institution

binfo

Branch information

city

City

subtype

vas

extra

address1

address2

address3

address4

location

country

pob_number

pob_location

pob_country



<< Back to Top >>


2.2 GetBranchByLocation - SOAP RPC


GetBranchByLocation functionality:

  • Lookup SWIFT bank branches by bank name and city. Returns information for matching branches.

Parameter Format for GetBranchByLocation

ReturnMessage = getbranchbylocation(QueryString)

where

QueryString is a " | " delimited string of the format "userID|PIN|bank_name|city"

ReturnMessage Multiple occurrences of: a string of 17 variable length fields. Records are delimited by " ? " and fields are delimited by " | " character. Please note that some of these fields may be empty.

All possible ReturnMessage values are shown below

ReturnMessage meanings

17 variable length fields in a "|" delimited string. - The fields are :- bic|branch|name|binfo|city|subtype|vas|extra|address1|address2|... ...address3|address4|location|country|pob_number|pob_location|pob_country

ERROR - Invalid User ID/PIN - The User ID or PIN has not been recognised.

ERROR - UserID Expired - Trial user ID has expired.

ERROR - Insecure connection - An attempt was made to access BankVal International's GetBankDetails2 service using insecure HTTP protocol instead of HTTPS.


WSDL files

The WSDL file on the primary data centre is at https://www.unifiedservices.co.uk/bankvalint2.wsdl

The WSDL file on the backup data centre is at https://www.unifiedsoftware.co.uk/bankvalint2.wsdl


<< Back to Top >>