ID / Bank Account Verification (Real-Time) – Netcash Developers Documentation

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

AVS Realtime Query is a service that allows a remote system to send a single bank account and receive an immediate response in the session without polling. 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 real-time processing service. For the bulk 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

^{* 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 abovementioned banks’ accounts. AVS requests for any other banks are charged for and will not produce results.

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.

From your application call:

Web service: https://ws.netcash.co.za/NIWS/NIWS_NIF.svc
Method: AVSRealtimeQuery
Service key: Risk Reports service key

Input

The following mandatory parameters must be submitted with your query.

Mandatory fields

Field	Description
Service key	Risk Reports service key issued by Netcash
AccountReference	The reference assigned to this client/enquiry
BankAccountNumber	The bank account number to be verified
BranchCode	The branch code
BankAccountType	Current/Savings/Transmission
EnquiryName	The bank account name (individual name & surname/business name) associated with the bank account
IDNumber	SA ID/Passport/Business registration number
IsIdNumber	True/False

The following parameters are optional and can be submitted with the query:

Optional fields

Field	Description
Extra 1	Additional, custom data to be returned in the response
Extra 2	Additional, custom data to be returned in the response
Extra 3	Additional, custom data to be returned in the response
Initials	The initials associated with the bank account
PhoneNumber	Phone number to be verified (with country dialing code)
Email	Email address to be verified

Output

The service responds synchronously with the information returned from the bank or with one of the error codes listed below:

Numeric Response	Description
000	Enquiry Successful
100	Authentication failed
200	General service error. Contact support
203	SA ID number, Bank account number, Branch code or Bank account type invalid. Error description is returned in the <Messages/> tag

XML response example

Where the query is successful (000) the following data will be returned

<AVSRealtimeQuery>
  <MethodParameters>
    <AVSRealtimeQueryResponse>
      <AcceptsCredits>Valid</AcceptsCredits>
      <AcceptsDebits>Valid</AcceptsDebits>
      <AccountActive>Valid</AccountActive>
      <AccountDormant>NotApplicable</AccountDormant>
      <BankAccountNumberValid>Valid</BankAccountNumberValid>
      <EmailMatch>Valid</EmailMatch>
      <FileToken>RT.10029177.1000807447.0254.63430</FileToken>
      <IdNumberMatch>Valid</IdNumberMatch>
      <InitialMatch>Invalid</InitialMatch>
      <LastNameMatch>Valid</LastNameMatch>
      <Messages attr0="StringArray" isNull="false" />
      <OfflineRequest>False</OfflineRequest>
      <PeriodActive>Valid</PeriodActive>
      <PhoneNumberMatch>Valid</PhoneNumberMatch>
      <TaxRefMatch>NotApplicable</TaxRefMatch>
      <ErrorCode>000</ErrorCode>
    </AVSRealtimeQueryResponse>
  </MethodParameters>
</AVSRealtimeQuery>

Optional polling for result file

Included in the synchronous response is the FileToken. This can be used to extract the same file which is currently returned by the RequestAVSReport Method.

(Polling is not required when using the AVSRealtimeQuery service. It has been added for backward compatibility if required by the remote system).

Example

<String>###BEGIN RT.10028582.1000808136.8026.63430 REPORT 08:50 AM### KEY ACCOUNTREFERENCE BANKACCOUNTNUMBERVALID IDNUMBERVALID LASTNAMEMATCH ACCOUNTACTIVE PERIODACTIVE ACCEPTSDEBITS ACCEPTSCREDITS ACCOUNTDORMANT ERRORMESSAGE EXTRA1 EXTRA2 EXTRA3Acc Ref:Netcash RealT SKey VALID VALID VALID VALID VALID VALID VALID N\A Successful ###END 8:50 AM</String>

.PDF result on the web

As is the case with the existing AVS service included in the BatchFileUpload method, a PDF result can be downloaded from the Netcash website.

Error message examples

Account number CDV fails

<AVSRealtimeQuery>
  <MethodParameters>
    <AVSRealtimeQueryResponse>
      <AcceptsCredits isNull="true" />
      <AcceptsDebits isNull="true" />
      <AccountActive isNull="true" />
      <AccountDormant isNull="true" />
      <BankAccountNumberValid isNull="true" />
      <EmailMatch isNull="true" />
      <FileToken isNull="true" />
      <IdNumberMatch isNull="true" />
      <InitialMatch isNull="true" />
      <LastNameMatch isNull="true" />
      <Messages attr0="StringArray" isNull="false">
        <StringArray0>Account Number Invalid</StringArray0>
        <StringArray1>CDV Failure</StringArray1>
      </Messages>
      <OfflineRequest>False</OfflineRequest>
      <PeriodActive isNull="true" />
      <PhoneNumberMatch isNull="true" />
      <TaxRefMatch isNull="true" />
      <ErrorCode>203</ErrorCode>
    </AVSRealtimeQueryResponse>
  </MethodParameters>
</AVSRealtimeQuery>

Invalid branch code

<AVSRealtimeQuery>
  <MethodParameters>
    <AVSRealtimeQueryResponse>
      <AcceptsCredits isNull="true" />
      <AcceptsDebits isNull="true" />
      <AccountActive isNull="true" />
      <AccountDormant isNull="true" />
      <BankAccountNumberValid isNull="true" />
      <EmailMatch isNull="true" />
      <FileToken isNull="true" />
      <IdNumberMatch isNull="true" />
      <InitialMatch isNull="true" />
      <LastNameMatch isNull="true" />
      <Messages attr0="StringArray" isNull="false">
        <StringArray0>Branch Code Invalid</StringArray0>
        <StringArray1>CDV Failure</StringArray1>
      </Messages>
      <OfflineRequest>False</OfflineRequest>
      <PeriodActive isNull="true" />
      <PhoneNumberMatch isNull="true" />
      <TaxRefMatch isNull="true" />
      <ErrorCode>203</ErrorCode>
    </AVSRealtimeQueryResponse>
  </MethodParameters>
</AVSRealtimeQuery>

ID number invalid

<AVSRealtimeQuery>
  <MethodParameters>
    <AVSRealtimeQueryResponse>
      <AcceptsCredits isNull="true" />
      <AcceptsDebits isNull="true" />
      <AccountActive isNull="true" />
      <AccountDormant isNull="true" />
      <BankAccountNumberValid isNull="true" />
      <EmailMatch isNull="true" />
      <FileToken isNull="true" />
      <IdNumberMatch isNull="true" />
      <InitialMatch isNull="true" />
      <LastNameMatch isNull="true" />
      <Messages attr0="StringArray" isNull="false">
        <StringArray0>CDV Failure</StringArray0>
        <StringArray1>ID Number Invalid</StringArray1>
      </Messages>
      <OfflineRequest>False</OfflineRequest>
      <PeriodActive isNull="true" />
      <PhoneNumberMatch isNull="true" />
      <TaxRefMatch isNull="true" />
      <ErrorCode>203</ErrorCode>
    </AVSRealtimeQueryResponse>
  </MethodParameters>
</AVSRealtimeQuery>

Multiple validation failures (Bank account and ID number)

<AVSRealtimeQuery>
  <MethodParameters>
    <AVSRealtimeQueryResponse>
      <AcceptsCredits isNull="true" />
      <AcceptsDebits isNull="true" />
      <AccountActive isNull="true" />
      <AccountDormant isNull="true" />
      <BankAccountNumberValid isNull="true" />
      <EmailMatch isNull="true" />
      <FileToken isNull="true" />
      <IdNumberMatch isNull="true" />
      <InitialMatch isNull="true" />
      <LastNameMatch isNull="true" />
      <Messages attr0="StringArray" isNull="false">
        <StringArray0>CDV Failure</StringArray0>
        <StringArray1>ID Number Invalid</StringArray1>
      </Messages>
      <OfflineRequest>False</OfflineRequest>
      <PeriodActive isNull="true" />
      <PhoneNumberMatch isNull="true" />
      <TaxRefMatch isNull="true" />
      <ErrorCode>203</ErrorCode>
    </AVSRealtimeQueryResponse>
  </MethodParameters>
</AVSRealtimeQuery>

Enquiry name fails the minimum length (3 chars) check

<AVSRealtimeQuery>
  <MethodParameters>
    <AVSRealtimeQueryResponse>
      <AcceptsCredits isNull="true" />
      <AcceptsDebits isNull="true" />
      <AccountActive isNull="true" />
      <AccountDormant isNull="true" />
      <BankAccountNumberValid isNull="true" />
      <EmailMatch isNull="true" />
      <FileToken isNull="true" />
      <IdNumberMatch isNull="true" />
      <InitialMatch isNull="true" />
      <LastNameMatch isNull="true" />
      <Messages attr0="StringArray" isNull="false">
        <StringArray0>CDV Failure</StringArray0>
        <StringArray1>Enquiry Name Invalid</StringArray1>
      </Messages>
      <OfflineRequest>False</OfflineRequest>
      <PeriodActive isNull="true" />
      <PhoneNumberMatch isNull="true" />
   </AVSRealtimeQuery>
  </MethodParameters>
</AVSRealtimeQueryResponse>

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

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.