ID / Bank Account Verification

Overview

The following document gives a basic guideline of using the Netcash Web Service for systems integration.
The Location for this web service is at: https://ws.netcash.co.za/NIWS/niws_nif.svc

This service enables a software developer to write code enabling a user to do South African Bank Account and Consumer ID Verification from the Netcash System without user interaction.

This document explains the bulk processing service. For the real-time service click here.

Developers should familiarize themselves with calling a web service and processing the return in their chosen development language.

Bank Account Verification (AVS)

Only the following banks support/offer bank account verification services:

<sup>* Standard Bank 11-digit account numbers can only be verified using the universal branch code 051001
* Standard Bank 10-digit account numbers can be verified using the actual branch code -or the universal branch code.</sup>

AVS Terms

• Consumer: The client’s identity number and bank account details are submitted to the issuing bank to verify that the account is open, active and associated with the ZA identity number supplied.
• Commercial: The company’s registration number and bank account details are submitted to the issuing bank to verify that the account is open, active and associated with the company registration number supplied.

Technical Information

Please ensure that the settings for Developers are correctly set before you proceed with the implementation below specification.

Process:

1. Build the standard input file (NIF) containing the AVS enquiries according to the spec in this document.
2. Submit the file to Netcash via the BatchFileUpload method.
3. Retrieve the load report using the RequestFileUploadReport method.
4. Retrieve the results of the enquiries using the RequestAVSReport method.

Call the required method in the service https://ws.netcash.co.za/NIWS/niws_nif.svc

Once you have built the file call:

• Web service: https://ws.netcash.co.za/NIWS/niws_nif.svc
• Method: BatchFileUpload
• Service Key: Risk Services Service Key
• Parameter: NIF file

Input File Structure

The file is a tab delimited text file and 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.

Structure

Field explanations

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 (similar 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, Netcash recommends listing keys in ascending numerical order for ease of debugging and support.

Structure

K 101 126 127 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.
(In the example, 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). A blank tab (or the default value defined for the field) should replace empty fields.

Structure

Field	Type	Value	Mandatory
Record Id	A	T
101	AN	Account reference
126	AN	AVS check number
127	N1	Is ID number
131	N1	Banking detail type
132	AN	Bank account name
133	N1	Bank account type
134	AN6	Branch code
135	N1	Filler
136	N11	Bank account number
301	AN	Extra 1
302	AN	Extra 2
303	AN	Extra 3

Field explanations

• The content of the “Extra” fields will be included in downloaded statement data.

Footer record (F)

The footer record indicates that the file is complete. 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.

Structure

Input file example

H C74EF975-5429-4663-85FB-2A64CA0FB9EF 1 CD35 Test AVS Batch 20180730 24ade73c-98cf-47b3-99be-cc7b867b3080
K 101 126 127 131 132 133 134 135 136 301 302 303
T Ref001 199102191024089 1 1 NEL 2 051001 0 10011234099 Extra data 1 Extra 2 Extra 3
F 1 0 9999

Output

The web service has a 3-tiered output:

• The method call is validated
• The file content is validated and a load report is produced
• The results of the enquiries are returned in a response file

Method call output

Successful request

If the method call was successful, the web service will process the file and return a file token. Use the file token returned 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:

Load Report

To retrieve the load report call:

• Web service: https://ws.netcash.co.za/NIWS/niws_nif.svc
• Method: RequestFileUploadReport
• Service Key: Risk Services Service Key
• Parameter: File token

Only errors are reported in the file. If all the entries in the file are successfully validated, the Load report header will contain “SUCCESSFUL” and there will be no detail messages.

File structure

The report is tab-delimited with a linefeed character as line terminator.

Load report header (occurs once at the start of each load report)

Load report message (occurs multiple times – once per error record)

Load report trailer (occurs once – the last line in the report)

Response File

To retrieve the response file call:

• Web service: https://ws.netcash.co.za/NIWS/niws_nif.svc
• Method: RequestAVSReport
• Service Key: Risk Services Service Key
• Parameter: File token

The response file contains a record per enquiry as it is returned from the bank.

File structure
The report is tab delimited with a linefeed character as line terminator.

AVS report header (occurs once at the start of the AVS report)

Key record (occurs once between header and transaction records)

AVS transaction (occurs multiple times – once per account number)

* : Not all banks are able to supply all the data fields. Where fields cannot be populated by the participating bank, they are returned as N/A.

AVS report trailer (occurs once – the last line in the report)

AVS Submit Example

call the BatchFileUpload method equal to a string variable string Request =
    client.BatchFileUpload(ServiceKey, File);

// close client after response is received
client.Close();

switch (Request) {
  case "100":  // Authentication failure
    break;
  case "102":  // Parameter error
    break;
  case "200":  // General code exception.
    break;
  default:  // successfull
    return Request;
}

Request File Upload Report Example

    public string RequestFileUploadReport(string ServiceKey, string FileToken) {
  // initialise client
  NIWS_NIF.NIWS_NIFClient client = new NIWS_NIF.NIWS_NIFClient();

  // call the RequestFileUploadReport method equal to a string variable
  // the same Service Key used for the bactch file upload
  string Request = client.RequestFileUploadReport(ServiceKey, FileToken);

  // close client after response is received
  client.Close();

  // use response to output to UI
  // service will respond with the result of the file upload
  return Request;
}

Request AVS Response Example

public string RequestAVSReport(string pServiceKey, string pFileToken) {
  // initialise client
  NIWS_NIF.NIWS_NIFClient client = new NIWS_NIF.NIWS_NIFClient();

  // call the RequestAVSReport method equal to a string variable
  // the same Service Key used for the bactch file upload
  string Request = client.RequestAVSReport(pServiceKey, pFileToken);

  // close client after response is received
  client.Close();

  // use response to output to UI
  // service will respond with the result of the file upload
  return Request;
}

Identity Number Verification & Risk Reports

Credit Bureaus verify SA ID numbers against Home Affairs data where it exists.
Risk reports are available from a number of different credit bureaus – see reports available here

Process:
Build the standard input file (NIF) containing the IDV enquiries according to the spec in this document.
Submit the file to Netcash via the BatchFileUpload method.
Retrieve the load report using the RequestFileUploadReport method.
Retrieve the results of the enquiries using the RequestCreditDataReport method.

Accessing the service:

Call the required method in the service https://ws.netcash.co.za/NIWS/niws_nif.svc

Once you have built the file call:

• Web service: https://ws.netcash.co.za/NIWS/niws_nif.svc
• Method: BatchFileUpload
• Service Key: Risk Services Service Key
• Parameter: NIF file

Input File Structure

The file is a tab delimited text file and 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.

Structure

Field explanations

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 (similar 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, Netcash recommends listing keys in ascending numerical order for ease of debugging and support.

Structure

K 101 111 113 114 450

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, 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). A blank tab (or the default value defined for the field) should replace empty fields.

Structure

Field	Type	Value	Mandatory
Record Id	A	T
101	AN	Account reference
111	N	SA ID number
113	A	Surname
114	N1	First name
450	N2	Reason code*
301		Extra 1
302		Extra 2
303		Extra 3

Field explanations

* The content of the “Extra” fields will be included in the downloaded statement data.
This is a list of the reason codes for use in Field 450 when requesting a Risk Services enquiry. The reason code is a mandatory field required by the Credit Bureaus and must be included in every request.

Footer record (F)

The footer record indicates that the file is complete. 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.

Structure

Input file example

H	C74EF975-5429-4663-85FB-2A64CA0FB9EF	1	CD35	Test	AVS	Batch	20180730	24ade73c-98cf-47b3-99be-cc7b867b3080
K	101	126	127	131	132	133	134	135	136	301	302	303
T	Ref001	199102191024089	1	1	NEL	2	051001	0	10011234099	Extra	data	1	Extra	2	Extra	3
F	1	0	9999

Output

The web service has a 3-tiered output:

• The method call is validated
• The file content is validated and a load report is produced
• The results of the enquiries are returned in a response file

Method call output

Successful request

If the method call was successful, the web service will process the file and return a file token. Use the file token returned 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:

Load Report

To retrieve the load report call:

• Web service: https://ws.netcash.co.za/NIWS/niws_nif.svc
• Method: RequestFileUploadReport
• Service Key: Risk Services Service Key
• Parameter: File token

Only errors are reported in the file. If all the entries in the file are successfully validated, the Load report header will contain “SUCCESSFUL” and there will be no detail messages.

File structure

The report is tab delimited with a linefeed character as line terminator.

Load report header (occurs once at the start of each load report)

Load report message (occurs multiple times – once per error record)

Load report trailer (occurs once – the last line in the report)

Response file

To retrieve the response file call:

• Web service: https://ws.netcash.co.za/NIWS/niws_nif.svc
• Method: RequestCreditDataReport
• Service Key: Risk Service – Service Key
• Parameter: File token

The response file is a base64-encoded PDF file.

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 the Testing section for more details. If you require any integration assistance contact our technical support team