Before you start
Please download the suggested API integration process flow document and use it as a reference when developing.
Kindly adhere to the Netcash brand guidelines when developing.
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 your implementation.
Web Service Methods
The list of Netcash web service methods can be found here.
Quick Start Guides
Quick Start Guides will help you understand this service and get you started.
Overview
Bank Account Validation is a web service that uses an algorithm 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 will enhance the success of transactions processed. This service does not verify that the account is active or belongs to the individual or company (Bank Account Verification).
We recommend that Universal Branch Codes are used for the validation to be optimized.
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 or existence of the account number at any bank or branch, the account holder -or if the account is active.
Technical Information
NIWS_Validation is an online, synchronous web service that allows an external system to request validation and receive an immediate response.
NB! This service permits bulk requests per web service call. For single item requests click here
From your application call:
- Web service: https://ws.netcash.co.za/niws/niws_nif.svc
- Method: RequestFileUpload
- Service key: Account service key
Requests to the web service are sent as strings
Example: public string BatchFileUpload(string ServiceKey, string File)
Participating Banks and Universal Branch Codes
Most banks make use of Universal Branch Codes (UBC) also known as Central Branch Codes (CBC)
It is always advisable to use the UBC when storing data unless a bank does not offer UBC
| Bank Name | Central Branch Code (CBC) |
| Absa Bank | 632005 |
| Capitec Bank | 470010 |
| First National Bank (South Africa) | 250655 |
| Investec Bank | 580105 |
| Nedbank (South Africa) | 198765 |
| Nedbank Corporate Saver Account | 720026 |
| Postbank | 460005 |
| Standard Bank (South Africa) | 051001 |
| Access Bank | 410105 |
| African Bank | 430000 |
| Albaraka Bank | 800000 |
| Bank of Namibia | 980172 |
| Bidvest Bank | 462005 |
| Capitec Business (Mercantile Bank) | 450105 |
| Central Bank of Lesotho | 586611 |
| Citi Bank | 350005 |
| Discovery Bank | 679000 |
| Finbond Mutual Bank | 589000 |
| First National Bank Lesotho | 280061 |
| First National Bank Namibia | 282672 |
| First National Bank Swaziland | 287364 |
| Grinrod Bank | 584000 |
| HSBC Bank | 587000 |
| JP Morgan Chase Bank | 432000 |
| Meeg Bank | 470010 |
| MTN Banking | 490991 |
| Sasfin | 683000 |
| Standard Bank Namibia | 087373 |
| State Bank of India | 801000 |
| Ubank | 431010 |
| Unibank | 790005 |
| VBS Mutual Bank | 588000 |
| Olympus Mobile Bank | 585001 |
| Tyme Bank | 678910 |
Output
Successful request
If the method call was successful and the file is being processed, the web service will return a file token which is used to retrieve the load report
Example: 20000000.2550236530.0483.2.2
Unsuccessful request
If the method call fails, the web service will return an error code:
|
Code |
Description |
|
100 |
Authentication failure. Ensure that the service key in the method call is correct |
|
102 |
Parameter error. One or more of the parameters in the string is incorrect |
|
200 |
General code exception. Please contact Netcash Technical Support. |
Input file structure
Each file 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 – Transaction records follow 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 confirms that the file is complete.
Header record (H)
Every file must contain a header record as the first record in the file.
Record Structure
|
Field |
Name |
Type |
Value |
|
1 |
Record Identifier |
AN |
“H” – Identifies the record as a header |
|
2 |
Service Key |
AN |
GUID (Account service key) |
|
3 |
Version |
AN |
1 |
|
4 |
Instruction |
AN |
ValidateAcc – Request CDV validation |
|
5 |
Batch name |
AN |
Your batch identifier |
|
6 |
Action date |
N |
CCYYMMDD Current date |
|
7 |
Software vendor code |
AN |
Your software vendor code issued by Netcash. |
Example
H C74EF975-5429-4663-85FB-2A64CA0FB9EF 1 ValidateAcc My Test Batch 20201030 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.
For ValidateAcc, the Account reference and bank account detail fields are required
Example
K 101 131 132 133 134 135 136
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.
Record structure
| Field | Name | Type | Value |
| 101 | Account reference | AN22 |
The unique reference used to identify the mandate. Minimum 2 Maximum 22 characters |
| 131 | Banking detail type | N1 | 1 (Only bank accounts are accepted) |
| 132 | Bank account name | The name of the holder of the account at the bank | |
| 133 | Bank account type | N1 |
1= Current 2 = Savings 3 = Transmission |
| 134 | Branch code | A6 |
The branch number (including leading zeroes) It is recommended that Universal branch codes are supplied |
| 135 | Filler | N1 | 0 |
| 136 | Account number | N11 | The bank account number to be validated |
Footer record (F)
The footer record indicates that the complete file has been received. It must be the last record in the file. If the record is not present, the system will fail the file without processing any transaction records.
Record structure
| Field | Explanation |
| Record Identifier | “F” – Identifies the record as a footer |
| No of transactions | This is the count of all the ‘T’ records in the file. |
| Sum of amounts | 0 |
| End-of-file indicator | ‘9999’ – Indicates there are no more records. |
Example
F 2 0 9999
Example of input file
H C74EXXX5-5499-4663-85FB-2A6XXXXFB9EF 1 ValidateAcc My Test Batch 20131204 24ade73c-98cf-XXXX-XXXX-cc7b867b3080 K 101 131 132 133 134 135 136 T AB3456 1 Jones 1 632005 0 1234567894 T CD0SX7 1 Brown 2 250655 0 9012348888 F 2 0 9999
Retrieve Load report
You will need to request the load report using the file token received from the BatchFileUpload method call.
Input
Using the file token, call:
- Web service: https://ws.netcash.co.za/niws/niws_nif.svc
- Method: RequestFileUploadReport
- Service key: Account service key
Requests to the web service are sent as strings
Example: public string RequestFileUploadReport(string ServiceKey, string FileToken)
Output
If the file submitted is in the correct format, the Load report header will contain “SUCCESSFUL”.
Any format errors detected in upload file will be reported.
File structure
The report is tab-delimited with a linefeed character as line terminator.
Note: Only rows which failed validation will be reported. Where the load report is empty and the result is SUCCESSFUL, this indicates that all rows passed the CDV check.
Load report header (occurs once at the start of each load report)
| Field | Name | Type | Value |
| 1 | Record identifier | AN8 | ###BEGIN |
| 2 | Batch name | AN | {your batch name} |
| 3 | Result of upload | A13 | SUCCESSFUL / UNSUCCESSFUL / SUCCESSFUL WITH ERRORS |
| 4 | Start time of report | AN8 | HH:MM AM/PM |
Load report message (occurs multiple times – once per error record)
| Field | Name | Type | Value |
| 1 | Record identifier | AN8 | ###ERROR |
| 2 | Error message | AN | The error message |
Load report trailer (occurs once – the last line in the report)
| Field | Name | Type | Value |
| 1 | Record identifier | AN6 | ###END |
| 2 | End time of report | AN8 | HH:MM AM/PM |
Netcash brand guidelines
Please refer to the Netcash brand guidelines here when using any logos, images, icons, labels, descriptions, and references to Netcash in your software.
Testing
See Testing section for more details. If you require any integration assistance contact our technical support team