Currently set to Index
Currently set to Follow

Overview

A web service that allows the approved ISV systems to send client leads directly into the Netcash system for the account activation process.

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.

Depending on the indicator in field 525, leads can be sent as:

  • Active: the data will be routed to the account activation process.
  • Marketing only: the data will be stored in the marketing database. (only used by Sage Software)

The normal procedure for the registration of a Netcash account is by means of an account activation web site. A Netcash account manager captures minimal account detail and sends an account activation email to the prospective client. The client is given a unique login to the site and captures the new account details on the web pages.

The purpose of the Lead Generator Web Service is to shorten the activation process by furnishing the Netcash system with as much data as possible in the initial step. The system will record the uploaded data and the activation web site will merely be used by the client to verify the data.

A unique Lead Generator Service Key (LGK) is required to use this service. Use the default Lead Generator Service Key 97f3a99c-1887-41e9-8351-015718fd8d5d or contact our Solutions Architect at Netcash for more information.

Technical Information

NIWS_PARTNER is an asynchronous web service which exposes multiple methods. The method BatchFileUpload allows an external system to submit a batch file of leads to the Netcash system

Once you have built the file, call:

NOTE: A unique Lead Generator Service Key (LGK) is required to use this service. Use the default Lead Generator Service Key 97f3a99c-1887-41e9-8351-015718fd8d5d or contact our Solutions Architect at Netcash for more information.

Input

Requests to the web service are sent as strings

Example

public string BatchFileUpload(string ServiceKey, string File)
        {
            //initialise client 
            NIWS_Partner.NIWS_PartnerClient client = new NIWS_Partner.NIWS_PartnerClient();

            //call the BatchFileUpload method equal to a string variable
            //lead generator service key requested by channel manager
            string Request = client.BatchFileUpload(ServiceKey, File);

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

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

            //use response to call RequestFileUploadReport method
            return Request;
        }

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

Unsuccessful request

If the method call fails, the web service will return an error code:

Code Description
100 Authentication failure. Ensure that the Lead generator key in the method call is correct
200 General code exception. Please contact Netcash Technical Support.

Input File Structure

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

Field Name Type Value
1 Record Identifier AN H
2 Partner Service Key AN Lead Generator Service Key
3 Version AN 1
4 Instruction AN Purpose of the file
5 Batch name AN Your identifier
6 Action date N CCYYMMDD
7 Filler AN 0

Field explanations

Field Explanation
Record Id “H” – Identifies the record as a header
Service key Lead Generator Service Key
Version “1” – This is the Netcash version of the file specification
Instruction This is the instruction to the Netcash system. It is used in conjunction with the service key in the previous field to determine what action is taken on receipt of the file.
Registration– Data submitted is for a new Netcash client account
Batch name Use this field as an identifier of your batch.
Action date The date on which the payments are to be made to the beneficiary.
Filler 0

Example

H 97f3a99c-1887-41e9-8351-015718fd8d5d 1 Registration My Test Batch 20100331 0

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. It can be likened 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, it is recommended that keys are listed in ascending numerical order for ease of debugging and support.

Example

K 101 113 114 121 201 441 524 525 528

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 above, 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).
  • Empty fields should be replaced by a blank tab or a default value, where one has been defined.
  • Where no default is defined, empty fields are indicated by two consecutive tabs
    (IE: the field delimiters preceding and following the empty field)
  • Where fields are left empty, the Netcash system will assume spaces or zeroes for fields defined in the key record.

Mandatory field

The more information correctly supplied in the request, the less the client will have to capture on the Netcash account activation web site. This will expedite the process from request to opening the account.

The following fields are mandatory. If these fields are not present and valid, the file will be rejected.

Key Field name Valid criteria
101 Account reference min2, max 22 Alpha-Numeric
113 Surname min2, max 15 Alpha
114 First name min1, max 10 Alpha
121 Trading name min2, max 25 Alpha-Numeric
201 Email address min 5 max 50 Alpha-Numeric
Format: {text}@{text}.{text}
Full-stop allowed in text fields.
301 Extra field min 5 max 999 Alpha-Numeric
302 Extra field min 5 max 50 Alpha-Numeric
303 Extra field min 5 max 50 Alpha-Numeric
441 Telephone number min 10; max12 Numeric
524 Notes ISV software name, contact person, contact number (person who referred this lead), lead comments ie. Plumbing company with 20 employees requiring payments service
525 Activate now Numeric
1 = Log active opportunity

Validation of optional fields

  • Any additional data supplied will be validated according to the table in Appendix 1.
  • Only valid data will be inserted into the database.
  • Any fields which fail content validation will not be inserted.
  • Any fields which do not meet the specified minimum length will fail validation.
  • Any fields which exceed the specified maximum length will be truncated.
  • Non-mandatory fields which fail validation will not cause the file to be rejected.

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.

Structure

Field Name Alpha/Numeric Value
1 Record Identifier AN F
2 No of transactions N A count of the transaction records
3 Sum of amounts N The sum of the monetary fields (in cents)
4 End-of-file indicator N 9999

Field explanations

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 This field must contain zero.
End-of-file indicator ‘9999’ – Indicates there are no more records.

Example

F 2 0 9999

Example of input file

H 97f3a99c-1887-41e9-8351-015718fd8d5d 1 Registration TestFile 20131202 0
K 101 113 114 121 201 441 524 525 301 302 303
T Test100 Soap Joe Test Co test@test.net 27821234567 My Name 123456789 0000001 1
T Test101 Bloggs Jane Janes Hardware   27113044000 Extra1 Extra2 Extra3  1
F 2 0 9999

Retrieving the Load Report

 

Postback option

If you have activated the postback option, the load report is automatically posted back to the URL you supplied.

Polling option

If you have not activated the postback option, you will need to request the load report using the file token received from the BatchFileUpload method call.

Using the file token, call:

Requests to the web service are sent as strings.

Example

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

            //call the RequestFileUploadReport method equal to a string variable
            //the same service key used in the batch upload
            string Request = client.RequestFileUploadReport(ServiceKey, FileToken);

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

            //check request
            switch (Request)
            {
                case "100"://Authentication failure
                    break;
                case "200"://General code exception
                    break;
                case "FILE NOT READY"://The requested statement has not yet been created. Retry later
                    break;
                case "NO CHANGE"://No new transactions are available for download
                    break;
                default://Successful, will contain the Netcash account number registered with us
                    break;
            }

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

Output file

File content

For each successful lead in the file, the load report will contain the Netcash account number for the lead. Where errors were detected, the load report will stipulate the line number and the error message

Load report structure:

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

Field Type Value
Record identifier AN8 ###BEGIN
Batch name AN {your batch name}
Result of upload A13 SUCCESSFUL / UNSUCCESSFUL / SUCCESSFUL WITH ERRORS
Start time of report AN8 HH:MM

Load report message (occurs multiple times – once per T record in the input file)

Field Type Value
Account reference AN58 Acc Ref :{your account reference}
Batch name AN Line :{line in your file where error was found}
Line number AN The Netcash account number or error message

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

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

Errors

The following is a list of the errors which could be returned:

Error message Meaning
A system error occurred. Please contact Netcash. A fatal error occurred and the file could not be processed
Invalid service key. Lead Generator Service Key could not be authenticated
Service key inactive. Lead Generator Service Key service key not activated on the Netcash system
Invalid instruction. Instruction should be “Registration”
File structure invalid. Transaction record fields do not match key record fields. Columns supplied in the transaction record(s) do not match the columns specified in the key record
Required key XXX was not provided. A mandatory key was omitted
File structure invalid. Please check header, key or footer records. One or more of the record types H,K or F is not present in the file.
File structure invalid. Please check transaction records. Record type T not found
Transaction field XXX has invalid characters.
Transaction field XXX has an invalid length. Minimum X characters.
Transaction field XXX has an invalid range. Only from {1} to {2} allowed.

Examples:
1. ###BEGIN key record UNSUCCESSFUL 16:03 ###ERROR A system error occurred. Please contact Netcash. ###END 16:03

2. ###BEGIN UNSUCCESSFUL 16:02 Acc Ref :NA Line :2 Required key 101 was not provided ###END 16:02

3. ###BEGIN My test batch SUCCESSFUL 15:45 Acc Ref : 001 Line :3 51002977916 ###END 15:45

4. ###BEGIN My test batch SUCCESSFUL WITH ERRORS 11:45 Acc Ref : 001 Line :3 51002977916 Acc Ref : 002 Line :4 INVALID EMAIL ADDRESS ###END 11:45

 

Appendix 1 Transaction fields

IMPORTANT : Refer to mandatory fields

 

Account reference

Key Name Type Value
101 Account reference AN22 001 for the first account in the file.
002 for the second account
Etc.

Company contact details

Key Name Type Value
203 Company web address AN50 The “//:” and “.” symbols are allowed in this field
341 Company phone number N11 Include dialing codes EG: 27117822349
min:10, max:12
342 Company fax number N11 Include dialing codes EG: 27117822349
min:10, max:12

Company details

Key Name Type Value
121 Trading name AN25 The name of the business to be checked.
122 Registration number N20 The number of a registered business
123 Registered name AN25 The name of a registered business
124 VAT number N10 The VAT number of a registered business
125 Legal entity N1 1 = Registered company (Pty Ltd)
2 = Close corporation
3 = Section 21 company
4 = Non-profit organisation
5 = Trust
6 = Co-operative
7 = Sole proprietor
8 = Partnership
9 = Educational institution
10 = Unknown
11 = Association
12 = Incorporation

Company physical address

Key Name Type Value
321 Physical address line 1 AN50 min:2, max:50
322 Physical address line 2 AN50 min:2, max:50
323 Physical address line 3 AN50 min:2, max:50
324 Physical suburb AN50 min:2, max:50
325 Physical city AN50 min:2, max:50
326 Physical postal code N4 Must be 4 digits
327 Physical province N1 1 = Western Cape
2 = Gauteng
3 = Eastern Cape
4 = Free State
5 = Kwazulu Natal
6 = Limpopo
7 = Mpumalanga
8 = Northern Cape
9 = North West

Company postal address

Key Name Type Value
331 Postal address line 1 AN50 min:2, max:50
332 Postal address line 2 AN50 min:2, max:50
333 Postal address line 3 AN50 min:2, max:50
334 Postal suburb AN50 min:2, max:50
335 Postal city AN50 min:2, max:50
336 Postal code N4 Must be 4 digits
337 Postal province N1 1 = Western Cape
2 = Gauteng
3 = Eastern Cape
4 = Free State
5 = Kwazulu Natal
6 = Limpopo
7 = Mpumalanga
8 = Northern Cape
9 = North West

Account user details

Key Name Type Value
111 Id number N13 South African identity number. Must be 13 digits.
113 Surname A15 Details to be used for Consumer enquiry
114 First name A10 Details to be used for Consumer enquiry
119 Title N1 1 = Mr
2 = Mrs
3 = Ms
4 = Miss
5 = Dr
6 = Prof
128 Designation A25 Director, Member, Trustee, Sole proprietor, etc
129 Job description A25 Manager, Owner, Bookkeeper, etc.
201 Email address AN50 The “@” and “.” symbols are allowed in this field
441 Telephone number N11 Include dialing codes EG: 27117822349
min:10, max:12
442 Mobile number N11 Include dialing codes EG: 27827822123
min:10, max:12

Bank account details

Key Name Type Value
132 Bank account holder AN50 The name linked to the bank account
133 Bank account type N1 1 = Current / Checking
2 = Savings
3 = Transmission
134 Bank account branch N6 The branch code of the homing account. This field MUST be 6 digits. Pre-fill with zeroes if less than 6.
136 Bank account number N11 The homing bank account number.

Software vendor information

 

Key Name Type Value
524 Notes AN399 ISV software name, contact person, contact number (person who referred this lead), lead comments ie. Plumbing company with 20 employees requiring payments service
525 Activate now N 1 = Log active opportunity

 

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