Skip to main content

SOAP Payment Validation API

Overview

  • A web service that can be used to check bank account numbers and sort codes given an active Hopewiser Payment Validation click bundle.
  • Tested as SOAP Basic Profile 1.1 compliant, using the WSI test tool.
  • Please note that the service bundle referenced is different to that used in address searching, and that the validity of an account isn’t necessarily proof of existence.
  • Each request must be authenticated via 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://.
  • 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>

Quick Start Guide

  • A Payment Validation service account and a ‘live’ (Payment Validation) click bundle is required
  • 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.
  • Search submitted must draw upon a Payment Validation Master Address File (MAF) bundle included in the service account (see ‘How do I discover my available Payment Validation datasets?’ again within Basics).

Basics

SOAP Payment Validation API Quick Start Introduction

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

Soap Bankcoder New Project

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

Soap Bankcoder Navigator

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

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

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

Soap Bankcoder Validate Request

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

Soap Bankcoder Validate Response

 

 

How do I discover my available Payment Validation datasets?

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 and a list of alternate Payment Validation 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>

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

Customisations

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.

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

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.

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

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.