Netcash Account Transfer

Before you start

Please download the suggested API integration process flow document and use it as a reference when developing.
Kindly adhere to the Netcash brand guidelines when developing.

Programmers Guide

Refer to our Programmers guide for more detail on how to apply the required methodology in this document.
Ensure that the settings for developers are adhered to before you proceed with your implementation.

Web Service Methods

The list of Netcash web service methods can be found here.

Quick Start Guides

Quick Start Guides will help you understand this service and get you started.

Service Overview

This service allows for the transfer of available balance between two Netcash accounts which are not registered as the same legal entity.

Overview

NetcashTransfer is a file instruction that is submitted in the Header record of the NIF file.

The service allows a remote system to submit a batch of transfers to selected Netcash accounts.

The transfer of funds is done internally by Netcash and does not require submission to external service providers.

The Service

Object	Name	Description
Method	BatchFileUpload	Parameter: ServiceKey (Account) File
Method	RequestFileUploadReport	Parameter: ServiceKey (account) FileToken (received on file upload if successful)

Once you have built the file call:

• Web service: https://ws.Netcash .co.za/NIWS/niws_nif.svc
• Method: NetcashTransfer
• Service key: Account service key

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	Service Key	AN	Account 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	Software Vendor Key	AN	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)

Field explanations

Field	Explanation
Record Id	“H” – Identifies the record as a header
Service key	Account service key
Version	“1” – This is the Netcash version of the file specification
Instruction	NetcashTransfer – Transfer funds to an existing Netcash account
Batch name	Use this field as an identifier of your batch.
Action date	The date on which the transfers are to be made (normally 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)

Example

H C74EXXX5 5499-4663-85FB-2A6XXXXFB9EF 1 NetcashTransfer My IAT Batch 20210430 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 transaction (T) records in the file. It can be likened to the column headings in a spreadsheet.
• The key lists allthe 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 139 162 252 301 302 303

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 139) 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 fields are left empty, the Netcash system will assume spaces or zeroes for fields defined in the key record.

Key	Field name	Mandatory	Type	Explanation
139	Transfer to account number		String	The Netcash account number to which the funds will be transferred Must be a valid netcash account
162	Transfer Amount		Int32	The value of the transfer in cents
252	Beneficiary reference		String	The reference which will appear on the beneficiary’s Netcash statement
301	Extra1		String	Custom User defined data (Extra data you want returned for your internal system use) Max 999 characters
302	Extra2		String	Custom User defined data (Extra data you want returned for your internal system use) Max 49 characters
303	Extra3		String	Custom User defined data (Extra data you want returned for your internal system use) Max 49 characters

Example

T 51000136353 210000 Transfer-ABCShoes Leather Industry Invoice1234 GLcode-INV9876 Sarah

Input

The fields indicated by are mandatory for this method

Optional fields

If the optional fields are to be included in the transaction records, they must be specified in the key record (K).

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	Type	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 is the sum of all the values in the 161 fields. If field 161 is not specified in the key record, this will be the sum of all the 162 fields.
End-of-file indicator	‘9999’ – Indicates there are no more records.

Examples

F 2 0 9999

Example of input file

H	C74EXXX5-5499-4663-85FB-2A6XXXXFB9EF	1	NetcashTransfer	My IAT Batch	20210505	24ade73c-98cf-47b3-99be-cc7b867b3080
K	139	162	252	301	302	303
T	51000136353	210000	Transfer-ABCShoes	Leather Industry Invoice1234	GLcode-INV9876	Sarah
T	51008236274	10000	Payment100	PettyCash 	Joan
F	2	220000	9999

Retrieving the Load Report

• Postback optionIf you have activated the postback option in your NetConnector profile, 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:

• Web service: https://ws.netcash.co.za/NIWS/niws_nif.svc
• Method: RequestFileUploadReport
• Service key: Account service key
• File token: As returned by the file upload

Requests to the web service are sent as strings

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 uploaded

return Request;
}

Output file

File content

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

Authorise transfer

In order to complete the transfer a user needs to log in to the Netcash Account and select

1. Services
2. Account
3. Netcash Account Transfer
4. Authorise Transfer

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