Developers

GenerateRTIHash

1. REST

2.1 SOAP - Document Literal

2.2 SOAP - RPC

Important note.

All BankVal web services are available on both the main and backup servers at our primary data centre. This configuration is mirrored at our secondary data centre. The two data centres are geographically independent. 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 GenerateRTIHash - REST


GenerateRTIHash functionality:

  • The generatertihash method generates hash keys for HMRC RTI purposes using the SHA-256 algorithm.

To make sure you utilise our backup system, 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 GenerateRTIHash

  • GET https://www.unifiedservices.co.uk/services/bankvaluk/rtigenerate/userid/<userid>/pin/<pin>
    /origsortcode/<sortcode>/destsortcode/<sortcode>/amountpence/<ampence>/randomstr/<randstr>/<format>/
  • If http response code is < 200 or > 399 then call:-
  • GET https://www.unifiedsoftware.co.uk/services/bankvaluk/rtigenerate/userid/<userid>/pin/<pin>
    /origsortcode/<sortcode>/destsortcode/<sortcode>/amountpence/<ampence>/randomstr/<randstr>/<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
  • <origsortcode> > originating sort code.
  • <destsortcode> > destination sort code.
  • <amountpence> > amount in pence, 11 digits with leading zeros.
  • <randstr> > random string, 4 characters long prefixed by '/', e.g. '/ABC'. Can be left blank and a random string will be generated for you.
  • <format> specifies the format of the returned data. Valid formats are csv, xml and json. (csv uses the "|" delimiter)

Results

If parameters are valid:-

  • A string is returned in the format 'randstr|hash', e.g. '/D2C|169ed1ba29c1fd7fd229151c282f1fb254f004ffc3d278e4b3b866fa75dcc830'

Sample valid response in xml format :-

<rtigenerate>

  • <result>/TW0|db6f9d7f35aca05c5d09577127012fcf9305b2c3a548e92e0e3143b398c31a04<result>

</rtigenerate>


Sample valid response in json format :-

  • {"result":"/TW0|db6f9d7f35aca05c5d09577127012fcf9305b2c3a548e92e0e3143b398c31a04",
  • }

Sample valid response in csv format :-

  • /TW0|db6f9d7f35aca05c5d09577127012fcf9305b2c3a548e92e0e3143b398c31a04

If an error occurs:-

  • Result field - contains an error message
  • Remaining fields are empty

Error messages :-

Error Messages

INVALID - Random String - Random string not in correct format ('/ABC').

INVALID - Result Format - format parameter was not ‘xml’, ‘json’ or ‘csv’.


<< Back to Top >>


2 GenerateRTIHash - SOAP


GenerateRTIHash functionality:

  • BankVal UK‘s generatertihash method can be used generate RTI hashes.

Choose SOAP style:

There are two main ways of implementing SOAP, Document Literal and RPC. For help choosing the best solution for your implementation, please contact support@unifiedsoftware.co.uk.


2.1 GenerateRTIHash SOAP - Document Literal

2.2 GenerateRTIHash SOAP - RPC


<< Back to Top >>


2.1 GenerateRTIHash - SOAP Document Literal


GenerateRTIHash functionality:

  • GenerateRTIHash may be used to create RTI hashes using the SHA-256 algorithm.

WSDL files

The WSDL file on the primary data centre is at https://www.unifiedservices.co.uk/services/bankvaluk/rtigenerate.php?wsdl

The WSDL file on the backup data centre is at https://www.unifiedsoftware.co.uk/services/bankvaluk/rtigenerate.php?wsdl


Request

Parameters

Description

userid

BankVal UK User ID.

pin

5 digit PIN.

origsortcode

Originating Sort Code.

destsortcode

Destination Sort Code.

amountpence

Amount in pence, 11 digits with leading zeros.

randomstr

Random String.

Response

Field

Description

result

Result string contains one of the following messages:-
/TW0|db6f9d7f35aca05c5d09577127012fcf9305b2c3a548e92e0e3143b398c31a04 - (Example) Random string and hash returned.
ERROR - Invalid User ID/PIN - The User ID or PIN has not been recognised.
ERROR - UserID Expired - Trial user ID has expired.
ERROR - Invalid Random String Format - Random string must be 4 chars starting with '/' e.g. '/ABC'.


<< Back to Top >>


2.2 GenerateRTIHash - SOAP RPC


GenerateRTIHash functionality:

  • BankVal UK‘s generatertihash method can be used to generate RTI hashes using the SHA-256 algorithm.

Parameter Format for GenerateRTIHash

ReturnMessage = generatertihash(QueryString)

where:-

QueryString = userID|PIN|originating sort code|destination sort code|amount pence|random string

All possible ReturnMessage values are shown below

ReturnMessage example

/TW0|db6f9d7f35aca05c5d09577127012fcf9305b2c3a548e92e0e3143b398c31a04

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

ERROR - UserID Expired||||| - Trial user ID has expired

ERROR - Invalid Random String Format||||| - Random string must be 4 characters starting with '/', e.g. '/ABC'


WSDL files

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

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


<< Back to Top >>