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:

PARTICIPATING BANK	SEMI-REALTIME
ABSA	YES
African Bank	YES
Bank of Athens	NO
Bidvest Bank	NO
Capitec Bank	YES
Discovery Bank	YES
First National Bank	YES
Investec Bank	YES
Mercantile Bank	NO
Nedbank	YES
Sasfin Bank	YES
Standard Bank*	YES

<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

Method Name	Parameters
BatchFileUpload	ServiceKey (Risk Services Service Key) File
RequestFileUploadReport	ServiceKey (Risk Services Service Key) FileToken (received on file upload if successful)
RequestAVSReport	ServiceKey (Risk Services Service Key) FileToken (the same file token received)

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 Name	Type	Value
Record ID	A	H
Service Key	AN	GUID
Version	N	1
Instruction	AN	CD35
Batch name	AN	Your identifier
Action date	N	CCYYMMDD
Software Vendor Key	AN	GUID

Field explanations

Field Name	Explanation
Record Id	“H” – Identifies the record as a header
Service Key	The Risk Service Key issued to the account by Netcash
Version	“1” – This is the Netcash version of the file specification
Instruction	Purpose of the file (CD35 – AVS enquiry)
Batch name	The Batch name will be returned in the Load report header to identify the batch result
Action date	Current date
Software Vendor Key	The key issued by Netcash to identify the software origin of transactions. (only used by Netcash ISV‘s else use the default value: 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 (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

Key	Field Name	Explanation
101	Account reference	The unique reference for this record
126	AVS check number	SA ID number / Passport number/ Company registration
127	Is ID number	1 = This is an SA ID number. The system will validate the AVS check number supplied in 126 before submitting for verification 0 = company registration or passport number
131	Banking detail type	1 = Bank account
132	Bank account name	Account holder surname or company name. The bank will verify that the account name is as it appears in their records
133	Bank account type	1 = Current 2 = Savings 3 – Transmission
134	Branch code	6-digit branch code. Prefill with zeroes if less than 6
135	Filler	0
136	Bank account number	Bank account number
301	Extra 1	Custom user-defined data*
302	Extra 2	Custom user-defined data*
303	Extra 3	Custom user-defined data*

• 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

Field Name	Type	Value
Record Identifier	A	F
No of transactions	N	A count of the transaction records
Sum of amounts	N	0
End-of-file indicator	N	9999

 

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:

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

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)

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
5	Batch Value	AN15	TOTAL OF BATCH
6	Action Date	AN8	CCYYMMDD

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

Field	Name	Type	Value
1	Account reference	AN58	Acc Ref :{your account reference}
2	Line number	AN	Line :{line in your file where error was found}
3	Error message	AN	The error message
		OR
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

 

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)

Field	Field name	CD35
Record identifier	AN8	###BEGIN
File Token	N	The polling id returned in the original response
Type	A6	REPORT
Start time of report	AN8	HH:MM AM / PM

Key record (occurs once between header and transaction records)

Field	Type	Value
Record identifier	AN6	###KEY
Field 1	A	ACCOUNTREFERENCE
Field 2	A	BANKACCOUNTNUMBERVALID
Field 3	A	IDNUMBERVALID
Field 4	A	LASTNAMEMATCH
Field 5	A	ACCOUNTACTIVE
Field 6	A	PERIODACTIVE
Field 7	A	ACCEPTSDEBITS
Field 8	A	ACCEPTSCREDITS
Field 9	A	ACCOUNTDORMANT
Field 10	A	ERRORMESSAGE
Field 11	AN	EXTRA1
Field 12	AN	EXTRA2
Field 13	AN	EXTRA3

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

Field	Type	Value
Account reference	A	Acc Ref :{your account reference}
Bank account number	A	VALID / INVALID
AVS check number	A	VALID / INVALID (AVS check number matches account number)
Last name match *	A	VALID / INVALID or N/A
Account active *	A	VALID / INVALID or N/A
Period active *	A	Y = account active for longer than 6 months N = account not active N/A
Accepts debits *	A	VALID / INVALID or N/A
Accepts credits *	A	VALID / INVALID or N/A
Account dormant *	A	VALID / INVALID or N/A
Error message	A	Any error message received from the bank
Extra 1	A	User defined data which was sent in the request file
Extra 2	A	User defined data which was sent in the request file
Extra 3	A	User defined data which was sent in the request file

* : 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)

Field	Type	Value
Record identifier	AN6	###END
End time of report	AN8	HH:MM AM / PM

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

Method Name	Parameters
BatchFileUpload	ServiceKey (Risk Services Service Key) File
RequestFileUploadReport	ServiceKey (Risk Services Service Key) FileToken (received on file upload if successful)
RequestCreditDataReport	ServiceKey (risk service – Service Key) FileToken (the same file token received)

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 Name	Type	Value
Record ID	A	H
Service Key	AN	GUID
Version	N	1
Instruction	AN	CD14 or other report type
Batch name	AN	Your identifier
Action date	N	CCYYMMDD
Software Vendor Key	AN	GUID

Field explanations

Field Name	Explanation
Record Id	“H” – Identifies the record as a header
Service Key	The Risk Service – Service Key issued to the account by Netcash
Version	“1” – This is the Netcash version of the file specification
Instruction	Purpose of the file (CD14 – IDV enquiry) See other types available here
Batch name	The Batch name will be returned in the Load report header to identify the batch result
Action date	Today’s date
Software Vendor Key	The key issued by Netcash to identify the software origin of transactions. (only used by Netcash ISV‘s else use the default value: 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 (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

Key	Field Name	Explanation
101	Account reference	The unique reference for this record
111	SA ID number	13-digit ID number.
113	Surname	No special characters permitted
114	First name	No special characters permitted
450	Reason code*	Required by the credit bureau. See the table below
301	Extra 1	Custom user-defined data*
302	Extra 2	Custom user-defined data*
303	Extra 3	Custom user-defined data*

* 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.

Code	Reason name	Explanation
32	Credit application	Undertaking a credit assessment in respect of a consumer, as required by Section 81 (2) of the Act;
33	Credit limit management	Undertaking a credit assessment in respect of a consumer, as required by Section 81 (2) of the Act;
34	Insurance application	Assessing an application for insurance, provided that the consent of the consumer has been obtained prior to the report being requested; (Regulation 18(4)(f) of the National Credit Act Regulations)
35	Employment check	Considering a candidate for employment in a position that requires trust and honesty and entails the handling of cash or finances, provided that the consent of the consumer has been obtained prior to the report being requested; OR Verifying educational qualifications and employment provided that the consent of the consumer has been obtained prior to the report being requested; (Regulation 18(4)(g) of the National Credit Act Regulations)
38	Fraud, corruption, or theft investigation	An investigation into fraud, corruption or theft, provided that the South African Police Service or any other statutory enforcement agency conducts such an investigation; (Regulation 18(4)(a) of the National Credit Act Regulations)
39	Fraud detection and prevention	Fraud detection and fraud prevention services; (Regulation 18(4)(b) of the National Credit Act Regulations)
40	Continuous service provision limit	Setting a limit in respect of the supply of goods, services or utilities, provided that the consent of the consumer has been obtained prior to the report being requested; (Regulation 18(4)(e) of the National Credit Act Regulations)
42	Unclaimed funds distribution	Obtaining consumer information to distribute unclaimed funds, including pension funds and insurance claims; (Regulation 18(4)(h) of the National Credit Acts Regulations)
43	Financial means assessment	Undertaking a credit assessment in respect of a consumer, as required by Section 81 (2) of the Act;
44	Propensity to repay	Undertaking an affordability assessment in respect of a consumer, as required by Section 79 of the Act;
48	Debt Counseling

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

Field Name	Type	Value
Record Identifier	A	F
No of transactions	N	A count of the transaction records
Sum of amounts	N	0
End-of-file indicator	N	9999

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:

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

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)

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
5	Batch Value	AN15	TOTAL OF BATCH
6	Action Date	AN8	CCYYMMDD

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

Field	Name	Type	Value
1	Account reference	AN58	Acc Ref :{your account reference}
2	Line number	AN	Line :{line in your file where error was found}
3	Error message	AN	The error message
		OR
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

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