Electronic Mandates Web Service - Update - Netcash

Home
/
Inbound Payments
/
Electronic Debit Order Mandates
/
Electronic Mandates Web Service...

Overview

e-Mandate update is a web service that allows a remote system to send electronic updates to the Netcash system for electronic debit order mandates.

Web Service Methods

The list of Netcash web service methods can be found here

Quick Start 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.

Technical Information

Web service: https://ws.netcash.co.za/niws/niws_nif.svc
Method: BatchFileUpload
Service key: Debit order service key

Input

Requests to the web service is sent as a string.

Example:

public string BatchFileUpload(string ServiceKey, string File)

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

Input File Structure

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.

Record Structure

Field	Name	Type	Value
1	Record Identifier	AN	H
2	Service Key	AN	Service GUID
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	Debit order service key
Version	“1” – This is the Netcash version of the file specification
Instruction	MandateToMasterfile
Batch name	Use this field as an identifier of your batch.
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)

Example

H C74EF975-5429-4663-85FB-2A64CA0FB9EF 1 MandateToMasterfile My Test Batch 20100331 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 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

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 138) is defined as the first field in the record, therefore, every transaction record MUST have the Budget 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.

Field

Field name

Type

Value

101

Account reference

AN22

The unique reference used to identify the mandate.

(Existing Debit Order master file references will be updated. New references will be created where they do not exist in the Debit order master file)
Minimum 2 Maximum 22 characters

Mandatory fields

The fields indicated by are mandatory for the specified instruction.

Key	Field name	Mandatory ^{See key legend for value requirements}
101	Account reference

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

Example

F	2	0	9999

Retrieving the Load Report

Postback option

Postback has not been activated in this version of the service

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: Debit Order service key

Requests to the web service are sent as strings

Example:

public string RequestFileUploadReport(string ServiceKey, string FileToken)

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

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

Field	Name	Type	Value
1	Unique reference	AN25	The unique reference you supplied in (p2)
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

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