Currently set to No Index
Currently set to No Follow

Please note: It is highly advisable that developers implement NetAccess for risk reports requests due to the sensitive/confidential nature of some of the details received back from this web service. Refer to the Protection of Personal Information Act 4 of 2013, the Consumer Protection Act 68 of 2008 and the National Credit Act 34 of 2005.
When using NetAccess; Netcash will store all sensitive/confidential information in a secure and legally acceptable manner for the host system to access at any given time. By integrating the web service for any risk reports or as a stand alone service; both the Developer/s and the entity such development is done for/on behalf of; will be legally liable to ensure the proper secure storage of all the data as per the Protection of Personal Information Act 4 of 2013 and shall be held legally liable for any violation of consumer/privacy rights.
A signed disclaimer to use this specific web service – will be required prior to activation and usage of this service. Failure to comply / unauthorized usage will lead to immediate suspension of the service.
Netcash reserves the right to suspend the risk report section of the Verification web service, without any prior notice.

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.svcThis service enables a software developer to write code enabling a user to do South African Bank Account and South African Consumer ID Verification from the Netcash System without user interaction. It is a simple web service. Developers should familiarize themselves with calling a web service and processing the return in their chosen development language.

Please note the disclaimer required for the usage of any of this service.

Web Service Methods

The list of Netcash web service methods can be found here

QuickStart Guides

We have developed some Quick Start Guides to help you understand this service and to help you get started.

Programmers Guide

To start, refer our Programmers guide for more detail on how to apply the required methodology in this document.
Please ensure that the settings for Developers are correctly set before you proceed with the implementation below specification.

Account holder Verification Service (AVS) Bank Account Verification

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

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

Please note:

Netcash can currently only verify the above mentioned banks’ accounts. Do not submit AVS requests for any other banks as these cannot be processed; and will be charged for.

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 inquiries 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:

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    (see other instructions)
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)    (see other instructions)
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 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.

Mandatory field

The fields indicated by tick is mandatory for the specified instruction.

See the full API key legend for value requirements

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 C7XXX975-5429-XXXX-85FB-2A64CXXXB9EF 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

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

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

2.1 File structure

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

2.1.1 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

2.1.2 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

2.1.3 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

3. Response File

To retrieve the response file call:

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 Type 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 8 A ACCOUNTACTIVE
Field 5 A PERIODACTIVE
Field 6 A ACCEPTSDEBITS
Field 7 A ACCEPTSCREDITS
Field 8 A ACCOUNTDORMANT
Field 9 A ERRORMESSAGE
Field 10 AN EXTRA1
Field 11 AN EXTRA2
Field 12 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;
}

ZA Identity Number Verification

Credit Bureaus verify SA ID numbers against Home Affairs data where it exists.

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:

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 N GUID
Version N 1
Instruction N CD14    (see other instructions)
Batch name N Your identifier
Action date N CCYYMMDD
Software Vendor Key N 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 instructions)
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.

Mandatory field

The fields indicated by tick is mandatory for the specified instruction.

See the full API key legend for value requirements

Structure

Field Type Value Mandatory
Record Id A T required
101 AN Account reference required
111 N SA ID number required
113 A Surname required
114 N1 First name required
450 N2 Reason code* required
301 AN50 Extra 1
302 AN50 Extra 2
303 AN50 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 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 ZA 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-XXXX-4663-YYYY-2A64CA0FB9EF 1 CD14Test AVS Batch 20180730 24ade73c-98cf-47b3-99be-cc7b867b3080
K 101 111 113 114 450 301 302 303
T Ref001 199102191024089 NEL JOHAN 32 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

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

2. Load Report

To retrieve the load report call:

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.

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

2.1.1 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

2.1.2 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

2.1.3 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

3. Response file

To retrieve the response file call:

The response file is a base64-encoded PDF file.

(Contact your payments advisor regarding alternative response formats)

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.

Version 2020.1

Copyright © 2020 Netcash (PTY) Ltd