Programmers guide

To start, please refer our programmer’s guide for more detail on how to apply the required methodology.

Overview

Bank Account Validations is a web service that uses an algorithm to validate the bank account number, branch code and account type combination of an employee, debtor or creditor.  Any software that allows for the capture of bank account details should implement this web service as it is critical for the success of other Sage Pay services requiring bank details such as ID number, bank account verification, bank codes or payments. This service does NOT verify that the account is active or belong to the employee, debtor or creditor.

This service is to be used on input of data into the application to ensure that the Banking details supplied are valid. It is recommended that Central Branch Code processing is used for the validation to be effective

Click here for the quick start guides for:

  • Account Service
  • Sage Pay system permissions

Central Branch Code Processing

Most South African banks now use a Central Branch Code (CBC) for transactional banking (also known as Universal Branch Codes (UBC)). Any software that allows for the capture of bank account details should implement these as it reduces the risk of users entering incorrect branch codes or having to request additional information to complete bank details. Payment failures are significantly reduced when using central branch codes.

Technical Information

Bank NameCentral Branch Code (CBC)
Absa Bank632005
Capitec Bank470010
First National Bank (South Africa)250655
Investec Bank580105
Nedbank (South Africa)198765
Nedbank Corporate Saver Account720026
Postbank460005
Standard Bank (South Africa)051001
African Bank430000
Albaraka Bank800000
Bank Of Namibia980172
Bidvest Bank462005
Central Bank Of Lesotho586611
Citi Bank350005
Finbond Mutual Bank589000
First National Bank Lesotho280061
First National Bank Namibia282672
First National Bank Swaziland280164
Grinrod Bank584000
Hsbc Bank587000
Jp Morgan Chase Bank432000
Meeg Bank471001
Merchantile Bank450105
Mtn Banking490991
Standard Bank Namibia087373
State Bank Of India801000
Ubank431010
Unibank790005
Vbs Mutual Bank588000

The suggested method is to create a user experience whereby the user will in the application:

  1. Create a table in the application database with the bank branches and codes as indicated above.
  2. In the application: select a bank-
    1. “Drop down” menu which if a bank is selected -prefill branch code text box (where there is such a CBC) but
    2. Branch Code Text Box Field is to remain editable so that user can change it if so desired. Please note that the change might result in non-payment as the CBC is preferred.
    3. If the bank required is not in the dropdown – user to select “other bank” and type the six (6) digit numeric branch code in the text box.
    4. Sage Pay will offer all black and bold items above as “dropdown list” in our systems. We will accept black and italics items if entered by the user if “other bank” is selected in dropdown menu, together with any other valid branch codes not listed herein (for validation purposes).
  3. For all black and bold above; default account type in the database to 1 (cheque/current) except
    1. for Nedbank
      1. If a Nedbank account number starts with ‘2’ make type 2 (savings) else
      2. If Nedbank account number starts with ‘1’ leave type 1 and
      3. If a Nedbank account number starts with ‘9’/or is a Corporate Saver Account; make the account type 2 (savings) and only use branch code 720026.
    1. for Postbank
      1. Always use account type “2” (savings) for any Postbank transactions

All non-listed (above) banks – user to select the actual account type (1 = Current/Cheque, 2 = Savings, 3 Transmission, 4 = Bond/Mortgage)

NIWS_Validation is an online, synchronous web service which allows an external system to request a validation and receive an immediate response. This service permits only a single request per web service call.

The service

ObjectNameDescription
methodGetBankListWithDefaultBranchCodeParameter:

  • ServiceKey (Sage Pay account service key). Call the service to receive the list of all banks with their default branch code (XML file). Save the data to system as stated above.
methodValidateBankAccountParameters:

  • ServiceKey (Sage Pay account service key)
  • AccountNumber
  • BranchCode
  • AccountType

From your application call:

  • Web service: https://ws.sagepay.co.za/NIWS/niws_validation.svc
  • Method: ValidateBankAccount
  • Service key: Account service key

Input

Submit the following parameters.

Service keyAccount service key issued by Sage Pay
Account numberMust be greater than 3 digits
Branch code6 digit branch number
Account type1 = Current account
2 = Savings account
3 =Transmission account
4 = Bond/Mortgage

Output

You will receive the following numeric code which you need to replace with the description in your application.

Numeric ResponseDescription
0Bank account details valid
1Invalid branch code
2Account number failed check digit validation
3Invalid account type
4Input data incorrect
100Authentication failed
200Web service error contact support@sagepay.co.za

Please note:
Sage Pay may provide example/sample/demo code snippets in this technical document. Such snippets are for guidance purposes only and may not function on every developer’s system/s. Sage Pay disclaims any and all liability for the usage of any of the example/sample/demo code snippets provided -and you as the developer must accept full responsibility for the usage of any example/sample and/or demo code.

While every possible effort has been taken to ensure compatibility across multiple system configurations, the example/sample/demo code cannot be guaranteed to work on all systems, with all operating systems and
or with all system configuration/s.

Sage Pay Login