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.

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
African Bank 430000
Albaraka Bank 800000
Bank of Namibia 980172
Bidvest Bank 462005
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
Merchantile Bank 450105
MTN Banking 490991
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

Netcash may provide example/sample/demo ‘code snippets’ and/or external links in this Technical Document. Such are for guidance purposes only and may not function on every developer’s system/s. Netcash disclaims any and all liability for the usage of guidance resources provided -and you as the Developer; must accept full responsibility for the usage of such. While every possible effort has been taken to ensure compatibility across multiple system configurations, the contents of this document cannot be guaranteed to work on all systems, with all operating systems -and/or with all system configuration/s.