Sortcode and Bank Account Implementation Guide

This guide is to assist in the integration of the sorting code and bank account validator into a website or application.

Using either of our Bankcheck services, we recommend you perform a GetBank in order to get the bank details, name address etc. If you are performing bank account validation for direct debits, then you can check if a sortcode will allow direct debits by checking the flag 'PermitDebits'. This will be set to true if direct debits are allowed. It is also useful to allow the user to check their bank details. If you do not need or want to display the bank account details then performing a modulus check on its own is sufficient. It performs a Validate sortcode check on the fly as a modulus check is meaningless without knowing the sortcode is valid.

The following table displays details of the methods in both Bankcheck and Bankcheck v2.

Method Name Description Parameters Example Return Value
GetBank Gets the bank details from the ISCD. Requires a sortcode as a parameter. Sortcode 111111 Bank object
IsBankHoliday This method checks to see if the date provided is a Bacs bank holiday. If the date is a bank holiday then the value returns a true, otherwise a false. Date 25-Dec-2010 boolean
ModulusCheck Performs a modulus check on a sortcode and bank account number. Requires a sortcode and account number as parameters. Sortcode, Account Number 111111, 00000007 boolean
ModulusCheckBatch Performs a modulus check on an array of sortcodes and bank account numbers. The same array is returned, but with the error element set to true or false depending on whether the bank account validation was successful or failed respectively. Sortcode, Account Number 111111, 00000007 boolean
ModulusCheckX Performs a modulus check in the same way the ModulusCheck method does. However, the extended version of the method takes a third parameter, namely refValue. This value is not validated in any way but is logged in our database so you can retrieve it later. Where this may be useful would be to record the direct debit reference number if you are performing modulus checking for direct debits. Sortcode, Account Number, Reference 111111, 00000007, DD0012345 boolean
ValidateSortcode Checks the sortcode exists in the ISCD. Requires a sortcode as a parameter. Sortcode 111111 boolean

Bankcheck v2

The Bankcheck v2 Service can be viewed here, and a full service description is available here.

SOAP or REST service

Bankcheck v2 can be consumed in several different ways, either using SOAP with a SOAP authentication header, or simply by POSTing to the service with your authentication details using JSON or XML. The service can return SOAP, JSON or XML. Some reference guide samples can be found below.

SOAP

  • Bankcheck has been developed in .Net for easy interfacing for Visual basic and Visual C# developers.

  • Once you have created your project, in the Solution Explorer select "Add Service Reference". This will present you with the following dialog box to enter the URL. Once the URL has been entered the BankCheck interface will be displayed. https://services.mosaicsoftware.co.uk/bankcheck/v2/bankcheck.svc

    Bankcheck Service Image
  • To use the service add the namespace to your project:

    using BankCheckTest.Service;
  • Now create an authentication header with your details, and initialise a BankcheckClient:

    Authentication auth = new Authentication();
    auth.CustomerId = "YOURCUSTOMERID";
    auth.LicenceKey = "YOURLICENCEKEY";
    BankcheckClient client = new BankcheckClient();
  • You can now use this client to make calls to any of the Bankcheck methods. The most commonly used methods are GetBank and ModulusCheck, which return a BankResult and BooleanResult respectively

    BankResult result = client.GetBank(auth, "SORTCODE");
    Bank bank = result.Bank;

    BooleanResult booleanResult = client.ModulusCheck(auth, "SORTCODE", "ACCOUNTNUMBER", null);
    bool modulusCheck = booleanResult.Valid;

REST

  • Bankcheck has been developed in .Net for easy interfacing for Visual basic and Visual C# developers using SOAP, however it is also a REST service. Consuming a REST service is quite simple, and can be done in any language. You simply need to set up a request, and give it a URL and some data. Some samples can be found below. Each method of the Bankcheck API requires an auth object, which contains your CustomerID and LicenceKey. The request will also need a sortcode, and ModulusCheck also requires the account number to check.

  • To use the GetBank method, the request URL is as follows: https://services.mosaicsoftware.co.uk/bankcheck/v2/bankcheck.svc/GetBank. The request must also contain the following data:

    { "auth": { "CustomerId": "YOURCUSTOMERID", "LicenceKey": "YOURLICENCEKEY" }, "sortcode": "SORTCODE" }
  • To use the ModulusCheck method, request URL is as follows: https://services.mosaicsoftware.co.uk/bankcheck/v2/bankcheck.svc/ModulusCheck. The request must also contain the following data:

    { "auth": { "CustomerId": "YOURCUSTOMERID", "LicenceKey": "YOURLICENCEKEY" }, "sortcode": "SORTCODE", "account": "ACCOUNTNUMBER" }
  • You can define the return type (XML or JSON) by setting the dataType of the request. If this isn't included, the service will return JSON.

Bankcheck

The Bankcheck Service can be viewed here, and a full service description is available here.

SOAP Service

The web service is a SOAP service and SOAP headers are used to authenticate the user of the service. The SOAP headers require two parameters: userId and password. Each of the developers guides shows a sample of how to create SOAP Headers.

C# Windows Application

  • BankCheck has been developed in Dot Net for easy interfacing for Visual basic and Visual C# developers. To make use of the service add a Web Reference to your project. The following examples are all in C# however the same applies to VB.

  • Once you have created your project, in the solution explorer select “Add Web Reference”. This will present you with the following dialog box to enter the url. Once the url has been entered the BankCheck interface will be displayed. https://services.mosaicsoftware.co.uk/bankcheck/bankcheck.asmx

    Bankcheck Service Image
  • As BankCheck is provided as a web-based service, the Industry Sortcode Directory (ISCD) is updated automatically when we receive a new copy from Bacs.

  • Create a simple form with a TextBox for the sortcode and for the account. In our examples we have named the TextBoxes sortcode and account respectively. We have also placed a textbox on the form in which to display the results.

    Bankcheck App Sample

A UserId and Password will be provided by Mosaic after a click block has been purchased

 
                                     
private void checkButton_Click(object sender, EventArgs e)
{
    try {
        Service.BankCheck bankcheck = new Service.BankCheck();
        bankcheck.BankcheckHeaderValue = new Service.BankcheckHeader();
        bankcheck.BankcheckHeaderValue.UserId = "youruserid";
        bankcheck.BankcheckHeaderValue.Password = "yourpassword";
        Service.Bank bank = bankcheck.GetBank(sortcode.Text);
        results.Text = string.Format("{0}\r\n{1}\r\n{2}\r\n{3}\r\n{4}\r\n{5}",
        bank.FullBranchTitle, bank.Address1, bank.Address2, bank.Address3, bank.Address4, bank.City);

        if (bankcheck.ModulusCheck(sortcode.Text, account.Text))
            MessageBox.Show("The sortcode and account IS valid");
        else
            MessageBox.Show("The sortcode and account IS NOT valid");  
    }
    catch (Exception ex)      
    {  
        MessageBox.Show(ex.ToString());        
    }
}
                                        
                                    

C# Asp.net

  • BankCheck has been developed in Dot Net for easy interfacing for Visual basic and Visual C# developers. To make use of the service add a Web Reference to your project. The following examples are all in C# however the same applies to VB.

  • Once you have created your project, in the solution explorer select “Add Web Reference”. This will present you with the following dialog box to enter the url. Once the url has been entered the BankCheck interface will be displayed. https://services.mosaicsoftware.co.uk/bankcheck/bankcheck.asmx

    Bankcheck Service Image
  • As BankCheck is provided as a web-based service, the Industry Sortcode Directory (ISCD) is updated automatically when we receive a new copy from Bacs.

  • Create a simple form with an asp:TextBox for the sortcode and for the account. In our examples we have named the TextBoxes sortcode and account respectively. We have also placed a multiline textbox on the form in which to display the results.

  • To instantiate the service and instantiate the header the following code can be used. A UserId and Password will be provided by Mosaic after a click block has been purchased

     
                                                
    bankCheck = new BankcheckService.BankCheck();
    bankCheck.BankcheckHeaderValue = new BankcheckService.BankcheckHeader();
    bankCheck.BankcheckHeaderValue.UserId = "youruserid";
    bankCheck.BankcheckHeaderValue.Password = "yourpassword";
                                                    
                                                
  • We then need to create a method to handle the sortcode TextChanged event. Thes method calls GetBank of the service. If the Bank object returned is a null then the sortcode is not valid. Otherwise the Bank object can be used to get populate the resuts field.

     
                                                
    protected void sortcode_TextChanged(object sender, EventArgs e)
    {
        BankcheckService.Bank bank = bankCheck.GetBank(sortcode.Text);
        if (bank != null)
        {
            bankDetails.Text = string.Format(@"{0}\n{1}\n{2}\n{3}\n{4}\n{5}\n", bank.ShortNameOfOwningBank, bank.ShortBranchTitle, bank.Address1, bank.Address2, bank.City, bank.Postcode);
            messageLabel.Text = "The sortcode exists in the ISCD";
            if (bank.PermitDebits)
                ddAllowed.Text = "Direct Debits Allowed";
            else
                ddAllowed.Text = "Direct Debits NOT Allowed";
    
            if (bank.PermitCredits)
                dcAllowed.Text = "Direct Credits Allowed";
            else
                dcAllowed.Text = "Direct Credits NOT Allowed";
        }
        else
        {
            messageLabel.Text = "The sortcode does not exist in the ISCD";
        }
    }
                                                    
                                                
  • We also need to create a method to handle the accountNumber TextChanged event. Thes method calls ModulusCheck of the service and returns a true or false on a pass or fail respectively.

     
                                                
    protected void accountNumber_TextChanged(object sender, EventArgs e)
    {
        if (bankCheck.ModulusCheck(sortcode.Text, accountNumber.Text))
        {
            messageLabel.Text = "The sortcode and account PASSED modulus check";
        }
        else
        {
            messageLabel.Text = "The sortcode and account FAILED modulus check";
        }
    }
                                                    
                                                

PHP

  • Bank account validation is very straightforward using the PHP SoapClient object. The code sample below demonstrates two functions of the bank account and sortcode validation methods of the API, namely the GetBank and ModulusCheck. The userId and password will be provided by Mosaic after the purchase of a block of clicks

  • Generally on a website we recommend you perform a GetBank in order to get the bank details, name address etc. If you are performing bank account validation for direct debits then you can check if a sortcode will allow direct debits by checking the flag 'PermitDebits'. This will be set to true if direct debits are allowed. It is also useful to allow the user to check thier bank details. If you do not need or want to display the bank account details then performing a modulus check on it's own is sufficient. It performs a Validate sortcode check on the fly as a modulus check is meaningless without knowing the sortcode is valid.

Mosaic Software logo
Support is available 9am-5pm, Monday to Friday excluding bank holidays. We also have out of hours support available in case of emergency.
Contact Us
Support
Glossary