SOAP Payment Validation API

Overview

SOAP Payment Validation API is a web service that can be integrated to check bank account numbers and sort codes within a client application.
Tested as SOAP Basic Profile 1.1 compliant, using the WSI test tool.
Each request must be authenticated via a token username/password combination, which is supplied in the SOAP header.
Please note that the service bundle referenced is different to that used in address searching, and that the validity of an account is not necessarily proof of existence.

Quick Start Guide

To use this functionality you will need to buy an Payment Validation click bundle from the Shop located in our Portal or by contacting us. Register for the Portal here.
Authentication, per service request, is via an http / https header using the Payment Validation user token credentials.
The interface definition (WSDL) can be downloaded from the service here. This can be used in a SOAPUI project in assessing service capability. Please see ‘SOAP Payment Validation API Introduction’ section within Basics for further details.

Basics

Authentication

Authentication is based on the WS-Security UsernameToken, where the default password type (PasswordText) is applied. Each request must be authenticated via a token 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

SOAP Payment Validation API Introduction

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

You can download SoapUI free of charge from www.soapui.org. This quick start guide 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

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

In the template request, replace the ? placeholders with the token username and password you created during registering with Payment Validation.

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 Payment Validation plan (uk-vl-bankcode), which will be used in subsequent requests. You can also see the available plans within Your Account.

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.

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

How do I validate an account number / sort code?

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 ‘How do I discover my available Payment Validation 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

How do I validate an account and return associated details?

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.

<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.

How do I get version information?

The Version function is used to obtain system information, identifying the version of the SOAP Payment Validation 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 SOAP Payment Validation service and the version of the underlying SortCodes library.

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <ns2:VersionResponse xmlns:ns2="http://hopewiser/soapbankcoder">
         <ns2:LibVersion>Sortcodes library version: 4.13.0</ns2:LibVersion>
         <ns2:SvrVersion>SOAP BankCoder version: 1.4.0 (201908271152)</ns2:SvrVersion>
      </ns2:VersionResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

How do I discover the status of my Payment Validation dataset?

The Status function is used to discover the Payment Validation 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 Payment Validation dataset 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”.

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <ns2:StatusResponse xmlns:ns2="http://hopewiser/soapbankcoder">
         <ns2:Default>
            <ns2:Dataset version="Sortcode data version: 97 (Built 02/10/2019 15:39:25)">uk-vl-bankcode</ns2:Dataset>
         </ns2:Default>
         <ns2:Alternate/>
      </ns2:StatusResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

SOAP Faults

The SOAP Payment Validation 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 token username/password
missing mandatory parameter
invalid parameter
dataset access has been blocked

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