- Home
- /
- Standard Integration
- /
- ZA Bank Account Validation
Bank Account Validation
Overview
Bank Account Validation is a web service that uses an algorithm see note to validate the bank account number, branch code, and account type combination. Any software that allows for the capture of bank account details this web service as it ensures valid data is sent to Netcash that will enhance the success of transactions processed. This service does not verify that the account is active or belongs to the individual or company (See Bank Account Verification)
We recommend that Universal Branch Codes are used for the validation to be optimized.
Click here for the quick start guides for:
A CDV validation is performed using a combination of the bank account number, account type, and branch code.
It is an algorithm supplied to Netcash and continuously updated by the banking system.
This does not guarantee the validity of the account number at any bank or branch, the account holder or if the account is active.
We suggest that you first validate and then verify the account holder details to ensure accuracy.
Programmers Guide
Refer to our Programmers guide for more detail on how to apply the required methodology in this document. Ensure that the settings for developers are adhered to before you proceed with implementation.
Universal Branch Code Processing
Most South African Banks use a Universal Branch Code (UBC) or a Central Branch Code (CBC) for transactional banking. Any software that allows for the capture of bank account details should as it ensure the banking detail will be valid even if the account holder’s branch closes. Payment failures are significantly reduced when using universal branch codes.
Technical Information – single line request
The below information is for single item Bank Account Validation. For single item RSA ID Validation click here
NIWS_Validation is an online, synchronous web service that allows an external system to request validation and receive an immediate response. This service permits only a single request per web service call.
From your application call:
Method: GetBankListWithDefaultBranchCode
Service key: Account Service Key
Web service: https://ws.netcash.co.za/NIWS/niws_validation.svc
Method: ValidateBankAccount
Service key: Account Service Key
Technical Information – bulk/file requests
The below information refers to Bulk/File requests for multiple Bank Account or RSA ID validations.
Web service:
- Web service:https://ws.netcash.co.za/NIWS/niws_nif.svc
- Method: BatchFileUpload
- Service key: Account Service Key
Input File Structure
The file is a tab-delimited text file and has the following mandatory records:
H – Header record identifies the upload and passes instructions to the Netcash server to determine the purpose of the file.
K – Key record must follow the header record. The key record describes the transaction records which follow. The format defined in the key record is used to validate the record structure and content.
T – Transactionrecordsfollow the key record. The fields in the transaction records must conform to the layout defined in the key.
F – Footer record must be the last record in the file and confirm that the file is complete.
Header record (H)
Every file must contain a header record as the first record in the file.
Field | Name | Type | Value |
---|---|---|---|
1 | Record Identifier | AN | H |
2 | Service Key | AN | Account Service Key |
3 | Version | AN | 1 |
4 | Instruction | AN | Purpose of the file |
5 | Batch name | AN | Your identifier |
6 | Action date | N | CCYYMMDD |
7 | Software Vendor Key | AN | The key issued by Netcash to identify the software origin of transactions. (only used by NetcashISV‘s else use the default value:24ade73c-98cf-47b3-99be-cc7b867b3080) |
Field explanations
Field | Explanation |
---|---|
Record Id | “H” – Identifies the record as a header |
Service key | Account Service key |
Version | “1” – This is the Netcash version of the file specification |
Instruction |
ValidateAcc or ValidateId |
Batch name | Use this field as an identifier of your batch. |
Action date | Today |
Software Vendor Key | The key issued by Netcash to identify the software origin of transactions. (only used by NetcashISV‘s else use the default value:24ade73c-98cf-47b3-99be-cc7b867b3080) |
Example – Bank Account Validation
H C74EXXX5-5499-4663-85FB-2A6XXXXFB9EF 1 ValidateAcc My Validation Batch 20100331 24ade73c-98cf-47b3-99be-cc7b867b3080
Example – ID Validation
H C74EXXX5-5499-4663-85FB-2A6XXXXFB9EF 1 ValidateId My Validation Batch 20100331 24ade73c-98cf-47b3-99be-cc7b867b3080
Key Record (K)
- The key record is mandatory and must appear in the file between the header record and the transaction records.
- The key defines the content, order and length of the transactions records in the file. It can be likened to the column headings in a spreadsheet.
- The key lists all the possible fields contained in the subsequent transaction records, even if not every transaction record contains data in all the fields.
- While the file is customizable, it is recommended that keys are listed in ascending numerical order for ease of debugging and support.
Example
K 101 111 131 133 134 135 136 301 302 303
Transaction Record (T)
- There must be at least one transaction record in the file.
- The transaction records must conform to the order of the fields as described in the key record.
(In the example above, the account reference (field id 101) is defined as the first field in the record therefore every transaction record MUST have the account reference as the first field or it will fail validation) - Every transaction record must have the same number of fields as defined in the key record (K).
- Empty fields should be replaced by a blank tab or a default value, where one has been defined. Where fields are left empty, the Netcash system will assume spaces or zeroes for fields defined in the key record.
Example (Bank Account Validation)
T Acc001 1 632005 0 1 9012347777
Example (ID Validation)
T Acc001 6612110000000
Mandatory field
The fields indicated by is mandatory for the specified instruction.
See the full API key legend for value requirements
Key | Field name | ValidateAcc | ValidateId |
101 | Account reference | ![]() |
![]() |
111 | Id number | ![]() |
|
131 | Banking detail type | ![]() |
|
133 | Bank account type | ![]() |
|
134 | Branch | ![]() |
|
135 | Filler | ![]() |
|
136 | Account number | ![]() |
|
301 | Extra 1 | ||
302 | Extra 2 | ||
303 | Extra 3 |
Examples
F 2 0 9999
Example of input file * Bank Account Validation
H C74EXXX5-5499-4663-85FB-2A6XXXXFB9EF 1 ValidateId ID Validation Batch 20100331 24ade73c-98cf-47b3-99be-cc7b867b3080 K 101 111 131 133 134 135 136 T Acc001 1 632005 0 1 9012347777 T Acc002 1 250544 0 1 87255629992 F 2 0 9999
Example of input file * ID Validation
H C74EXXX5-5499-4663-85FB-2A6XXXXFB9EF 1 ValidateId Account Validation Batch 20100331 24ade73c-98cf-47b3-99be-cc7b867b3080 K 101 111 T Acc001 8002315678987 T Acc002 6612316752345 F 2 0 9999
Participating Banks and Universal Branch Codes
Recommended User Experience
- Call the web service with method GetBankListWithDefaultBranchCode
or - Manually create a table in the application database with the bank branches and codes as indicated above.
The suggested method is to create a user experience whereby the user will in the application:
- Select a bank “Drop down” menu and prefill branch code text box or-
- Manually enter a branch code that is not a CBC.
- 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. Left-pad the input with “0” where data entered is less than 6 chars.
- Netcash will offer all blue and bold items above as “dropdown list” in our systems. We will accept black and italic 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).
- For all black and bold above; default account type in the database to 1 (cheque/current) except
- for Nedbank
- If a Nedbank account number starts with ‘2’ make type 2 (savings) else
- If Nedbank account number starts with ‘1’ leave type 1 and
- 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.
- for Postbank / Capitec
- Always use account type “2” (savings) for all Postbank and Capitec transactions
- for Nedbank
All non-listed (above) banks – user to select the actual account type (1 = Current/Cheque, 2 = Savings)
NIWS_Validation is an online, synchronous web service that allows an external system to request validation and receive an immediate response. This service permits only a single request per web service call.
Code Samples
<select id="accountType" name="accountType"> <option selected="selected" value="1">Cheque Account</option> <option value="2">Savings Account</option> </select>
See suggested account type configuration
<select id="bankName" name="bankName"> <option selected="selected" value="632005">Absa Bank</option> <option value="470010">Capitec Bank</option> <option value="250655">First National Bank (South Africa)</option> <option value="580105">Investec Bank</option> <option value="198765">Nedbank (South Africa)</option> <option value="720026">Nedbank Corporate Saver Account</option> <option value="460005">PostBank</option> <option value="051001">Standard Bank (South Africa)</option> <option value="430000">African Bank</option> <option value="800000">Albaraka Bank</option> <option value="980172">Bank Of Namibia</option> <option value="462005">Bidvest Bank</option> <option value="586611">Central Bank Of Lesotho</option> <option value="350005">Citi Bank</option> <option value="589000">Finbond Mutual Bank</option> <option value="280061">First National Bank Lesotho</option> <option value="282672">First National Bank Namibia</option> <option value="287364">First National Bank Swaziland</option> <option value="584000">Grinrod Bank</option> <option value="587000">HSBC Bank</option> <option value="432000">JP Morgan Chase Bank</option> <option value="450105">Mercantile Bank</option> <option value="490991">MTN Go Banking</option> <option value="087373">Standard Bank Namibia</option> <option value="801000">State Bank Of India</option> <option value="431010">UBank</option> <option value="790005">Unibank</option> <option value="588000">VBS Mutual Bank</option> </select>
<select id="debitFrequency" name="debitFrequency"> <option selected="selected" value="Monthly">Monthly</option> <option value="Weekly">Weekly</option> <option value="Bi-Weekly">Bi-Weekly</option> <option value="Annual">Annual</option> <option value="other">other</option> </select>
<select id="debitAccountType" name="debitAccountType"> <option selected="selected" value="1">Bank Account</option> <option value="2">Credit Card</option> </select>
<select id="ccardType" name="ccardType"> <option selected="selected" value="1">Master Card</option> <option value="2">Visa Card</option> </select>
The Service
Object | Name | Description |
---|---|---|
method | GetBankListWithDefaultBranchCode |
Parameter:
|
method | ValidateBankAccount |
Parameters:
|
Example
public ValidateBankAccount(string ServiceKey, string AccountNumber, string BranchCode, string AccountType) { //initialise client NIWS_Validation.NIWS_ValidationClient client = new NIWS_Validation.NIWS_ValidationClient(); //call the ValidateBankAccount method equal to a string variable string Request = client.ValidateBankAccount(ServiceKey, AccountNumber, BranchCode, AccountType); //close client after response is received client.Close(); //convert response received for request int response = Convert.ToInt32(Request); //if 0 save to system or do something else switch (response) { case 0: //do something break; case 1: //do something break; case 2: //do something break; case 3: //do something break; case 4: //do something break; case 100: //do something break; default: Web service error contact support@netcash.co.za"; break; } }
Getting Bank with Branch Code
private void GetBankListWithDefaultBranchCode (string ServiceKey) { //initialise client NIWS_Validation.NIWS_ValidationClient client = new NIWS_Validation.NIWS_ValidationClient(); //call the GetBankListWithDefaultBranchCode method equal to a string variable string BankListResult = client.GetBankListWithDefaultBranchCode(ServiceKey); //do something with xml file //for example File.WriteAllText("BankList.xml", BankListResult); XmlDocument XmlDoc = new XmlDocument(); XmlDoc.Load("BankList.xml"); XmlElement XmlEl = XmlDoc.DocumentElement; XmlNodeList XmlNode = XmlEl.SelectNodes("/BankListResponse/BankList/Bank"); foreach (XmlNode node in XmlNode) { //loop through file } }
Output
You will receive the following numeric code which you need to replace with the description in your application.
Numeric Response | Description |
---|---|
0 | Bank account details valid |
1 | Invalid branch code |
2 | Account number failed check digit validation |
3 | Invalid account type |
4 | Input data incorrect |
100 | Authentication failed |
200 | Web service error contact support@netcash.co.za |
Testing
See Testing section for more details. If you require any integration assistance contact our technical support team