SOAP Bankcoder API

SOAP Bankcoder API

The Hopewiser SOAPBankCoder API is a web service that can be used to check bank account numbers, with sort codes, over the internet. It has been tested as SOAP Basic Profile 1.1 compliant, using the WSI test tool.

The following sections complement the interface definition (WSDL), which can be obtained from the service.

https://cloud.hopewiser.com/soapbankcoder/soapbankcoder.wsdl

Intended Audience

This documentation is aimed at developers who wish to utilise the Hopewiser SOAPBankCoder service to embed bank account verification functionality within a client application.

The account numbers used in this page are examples only, and the sorting codes may not currently be in use.

Please refer to the Quickstart section for a step-by-step guide to validation an account number using SoapUI.

Authentication

Authentication is based on the WS-Security UsernameToken, where the default password type (PasswordText) is applied. Each request must be authenticated via a username/password combination, which is supplied in the SOAP header. To secure this information all requests should use the https:// protocol, in preference to http://.

<soapenv:Envelope
   xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:wss="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
  <soapenv:Header>
    <wss:Security>
    <wss:UsernameToken>
      <wss:Username>hpwuser</wss:Username>
      <wss:Password>password</wss:Password>
    </wss:UsernameToken>
    </wss:Security>
  </soapenv:Header>
  <soapenv:Body>
    .... etc ....
  </soapenv:Body>
</soapenv:Envelope>

This introduction will use SoapUI, which is a quick and easy tool to make SOAP calls. SOAP can be easily integrated into a wide range of languages.

You can download SoapUI free of charge from www.soapui.org. This introduction does not use any features of the Pro version.

Start a new project from the menu or toolbar, give the project a name and enter the WSDL:
https://cloud.hopewiser.com/soapbankcoder/soapbankcoder.wsdl

soapbankcoder new project

Expand the Status node in the project navigator and double-click on Request 1.

soapbankcoder navigator

In the template request, replace the ? placeholders with the username and password you used when registering with AddressServer in the Cloud.

soapbankcoder status request

Click the green run arrow and you will see the response from the server.

The Dataset tag within the response body contains the reference for the BankCoder plan (uk-vl-bankcode), which will be used in subsequent requests. You can also see the available plans within Your Account.

 

soapbankcoder status response

To validate a bank account number, expand the Validate node in the project navigator and double-click on Request 1. Replace the ? placeholders for the Username, Password, AccountNumber (full account number preceded by the sort code) and Dataset.

soapbankcoder validate request

Click the green run arrow and you will see the response from the server.

soapbankcoder validate response

The Status function is used to discover the BankCoder datasets (validation rules) that are configured for the authenticated user.

A Status request does not require any parameters.

<soapenv:Envelope
   xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:wss="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
   xmlns:hpw="http://hopewiser/soapbankcoder">
  <soapenv:Header>
    <wss:Security>
      <wss:UsernameToken>
        <wss:Username>hpwuser</wss:Username>
        <wss:Password>password</wss:Password>
      </wss:UsernameToken>
    </wss:Security>
  </soapenv:Header>
  <soapenv:Body>
    <hpw:StatusRequest/>
  </soapenv:Body>
</soapenv:Envelope>

The response will identify the default Bankcoder dataset and a list of alternate Bankcoder datasets for the authenticated user. Please note that both the Default and Alternate tags are optional, depending on the user's configuration.

Each dataset has attributes to specify its version and (optionally) a blocked reason. The presence of a blockedReason attribute indicates that access to that dataset has been disabled. Its value provides a textual description of the blocking reason, for example "No credit remaining".

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Header/>
  <soapenv:Body>
    <hpw:StatusResponse xmlns:hpw="http://hopewiser/soapbankcoder">
      <hpw:Alternate>
        <hpw:Dataset version="Sortcode data version: 29 (Built 02/05/2014 15:54:45)">
          uk-vl-bankcode
        </hpw:Dataset>
      </hpw:Alternate>
    </hpw:StatusResponse>
  </soapenv:Body>
</soapenv:Envelope>

The Validate function is used to verify bank account numbers, with sort codes.

A Validate request only requires an AccountNumber parameter. This should comprise the full account number, which is preceded by the sort code. The software strips all whitespace such as space and '-' characters.

It also takes a dataset reference parameter (optional) to specify the required validation rules. Available datasets are identified via the "Status" function as described in the "Discover my available BankCoder datasets" section above.

<soapenv:Envelope
   xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:wss="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
   xmlns:hpw="http://hopewiser/soapbankcoder">
  <soapenv:Header>
    <wss:Security>
      <wss:UsernameToken>
        <wss:Username>hpwuser</wss:Username>
        <wss:Password>password</wss:Password>
      </wss:UsernameToken>
    </wss:Security>
  </soapenv:Header>
  <soapenv:Body>
    <hpw:ValidateRequest>
      <hpw:AccountNumber>123456-12345678</hpw:AccountNumber>
      <hpw:Dataset>uk-vl-bankcode</hpw:Dataset>
    </hpw:ValidateRequest>
  </soapenv:Body>
</soapenv:Envelope>

The Validate response will return an overall validity status of either Y (Yes) or N (No), along with a status code and textual description of how that decision was reached.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Header/>
  <soapenv:Body>
    <hpw:ValidateResponse xmlns:hpw="http://hopewiser/soapbankcoder">
      <hpw:StatusCode>5</hpw:StatusCode>
      <hpw:StatusText>Sortcode not found.</hpw:StatusText>
      <hpw:ValidityFlag>Y</hpw:ValidityFlag>
    </hpw:ValidateResponse>
  </soapenv:Body>
</soapenv:Envelope>

All status codes, along with their description and overall validity flag, are listed below.

StatusCode StatusText ValidityFlag
2 Account valid. Y
3 Account number not valid. N
4 Sort code found, account could not be verified. Y
5 Sort code not found. Y
6 Bad account number or sort code format. N

The ValidateReturnDetail function is used to verify bank account numbers, with sort codes and return the bank details which will include bank name, address and contact numbers.

A ValidateReturnDetail request only requires an AccountNumber parameter. This should comprise the full account number, which is preceded by the sort code. The software strips all whitespace such as space and '-' characters.

It also takes a dataset reference parameter (optional) to specify the required validation rules. Available datasets are identified via the "Status" function as described in the "Discover my available BankCoder datasets" section above.

<soapenv:Envelope
   xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:wss="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
   xmlns:hpw="http://hopewiser/soapbankcoder">
  <soapenv:Header>
    <wss:Security>
      <wss:UsernameToken>
        <wss:Username>hpwuser</wss:Username>
        <wss:Password>password</wss:Password>
      </wss:UsernameToken>
    </wss:Security>
  </soapenv:Header>
  <soapenv:Body>
    <hpw:ValidateReturnDetailRequest>
      <hpw:AccountNumber>074456-12345112</hpw:AccountNumber>
      <hpw:Dataset>uk-vl-bankcode</hpw:Dataset>
    </hpw:ValidateReturnDetailRequest>
  </soapenv:Body>
</soapenv:Envelope>

The ValidateReturnDetail response will return an overall validity status of either Y (Yes) or N (No), along with a status code and textual description of how that decision was reached, followed by a "BankDetail" section which contains a list of bank field names and values.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Header/>
  <soapenv:Body>
    <hpw:ValidateReturnDetailResponse xmlns:hpw="http://hopewiser/soapbankcoder">
      <hpw:StatusCode>2</hpw:StatusCode>
      <hpw:StatusText>Account valid.</hpw:StatusText>
      <hpw:ValidityFlag>Y</hpw:ValidityFlag>
      <hpw:BankDetail>Y</hpw:BankDetail>
        <hpw:Item name="RecordType">1</hpw:Item>
        <hpw:Item name="Sortcode">074456</hpw:Item>
        <hpw:Item name="BICBank"/>
        <hpw:Item name="BICBranch"/>
        <hpw:Item name="SubBranchSuffix">00</hpw:Item>
        <hpw:Item name="ShortBranchTitle">FlexAccount (NGC)</hpw:Item>
        <hpw:Item name="ShortNameOfOwningBank">NATIONWIDE BLDG SCTY</hpw:Item>
        <hpw:Item name="FullNameOfOwningBank1">NATIONWIDE BUILDING SOCIETY</hpw:Item>
        <hpw:Item name="FullNameOfOwningBank2"/>
        <hpw:Item name="CHAPSStatus">I</hpw:Item>
        <hpw:Item name="FPSStatus">M</hpw:Item>
        <hpw:Item name="FullBranchTitle1">FlexAccount (NGC)</hpw:Item>
        <hpw:Item name="FullBranchTitle2"/>
        <hpw:Item name="FullBranchTitle3"/>
        <hpw:Item name="Address1">P.O. Box 8888</hpw:Item>
        <hpw:Item name="Address2">Nationwide Hse</hpw:Item>
        <hpw:Item name="Address3">Pipers Way</hpw:Item>
        <hpw:Item name="Address4"/>
        <hpw:Item name="AddressTown">Swindon L</hpw:Item>
        <hpw:Item name="AddressCounty">Wilts.</hpw:Item>
        <hpw:Item name="AddressOutcode">SN38</hpw:Item>
        <hpw:Item name="AddressIncode">1NW</hpw:Item>
        <hpw:Item name="Telephone1STD">0800</hpw:Item>
        <hpw:Item name="Telephone1">302011</hpw:Item>
        <hpw:Item name="Telephone2STD"/>
        <hpw:Item name="Telephone2"/>
      </hpw:BankDetail>
    </hpw:ValidateReturnDetailResponse>
  </soapenv:Body>
</soapenv:Envelope>

The status codes returned from ValidateReturnDetail are identical to those returned from the Validate responses. For the list of status codes, please refer to the status code table as described in the "Validate an account number" section above.

"BankDetail" fields are given in the table below:

Fieldname Description
• RecordType This is a Hopewiser field which is reserved for future use.
The value is currently set to 1.
• Sortcode This is a 6 digit bank sorting code.
• BICBank
• BICBranch
These two fields form the Bank Identifier Code.
• SubBranchSuffix This is a 2 digit subbranch number.
• ShortBranchTitle This is the official title of the branch, as appears on the cheque book.
• ShortNameOfOwningBank The short name which is formally approved by Payments Council.
• FullNameOfOwningBank1
• FullNameOfOwningBank2
The full name which is formally approved by Payments Council.
• CHAPSStatus This is the Clearing House Automated Payment System status.
Value will either be D, I or N.

D - Bank office is a direct office of a CHAPS member that accepts CHAPS payments.

I - Bank office is an indirect office of a CHAPS member or agency bank that accepts CHAPS payments.

N - Bank office does not accept CHAPS payments.
• FPSStatus This is the Faster Payments Service status.
Value will either be M, A or N.

M - Bank office of FPS member, accepts FPS payments.

A - Bank office of FPS agency bank, accepts FPS payments.

N - Bank office does not accept FPS payments.
• FullBranchTitle1
• FullBranchTitle2
• FullBranchTitle3
This is an extended title for the bank office.
• Address1
• Address2
• Address3
• Address4
• AddressTown
• AddressCounty
• AddressOutcode
• AddressIncode
The address of the bank office.
• Telephone1STD
• Telephone1
Telephone number1.
• Telephone2STD
• Telephone2
Telephone number2.

The Version function is used to obtain system information, identifying the version of the SOAPBankCoder service and the version of the underlying native SortCodes library.

A Version request does not require any parameters.

<soapenv:Envelope
   xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:wss="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
   xmlns:hpw="http://hopewiser/soapbankcoder">
  <soapenv:Header>
    <wss:Security>
      <wss:UsernameToken>
        <wss:Username>hpwuser</wss:Username>
        <wss:Password>password</wss:Password>
      </wss:UsernameToken>
    </wss:Security>
  </soapenv:Header>
  <soapenv:Body>
    <hpw:VersionRequest/>
  </soapenv:Body>
</soapenv:Envelope>

The Version response will contain the version of the SOAPBankCoder service and the version of the underlying SortCodes library.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Header/>
  <soapenv:Body>
    <hpw:VersionResponse xmlns:hpw="http://hopewiser/soapbankcoder">
      <hpw:LibVersion>Sortcodes library version: 3.0</hpw:LibVersion>
      <hpw:SvrVersion>SOAP BankCoder version: 1.0.12</hpw:SvrVersion>
    </hpw:VersionResponse>
  </soapenv:Body>
</soapenv:Envelope>

The SOAPBankCoder service will return client SOAP faults (i.e. faultcode value Client) when the requesting message is badly formed or contains incorrect information. The faultstring will identify the reason for the failure.

Possible causes are:

  • invalid username/password
  • missing mandatory parameter
  • invalid parameter
  • dataset access has been blocked

The SOAPBankCoder service will return a server SOAP fault (i.e. faultcode value Server) if it encounters an internal software error.