eMandate

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.

Overview

e-Mandate request is a web service that allows a remote system to send batched electronic requests for electronic debit order mandates to account holders for authorization.

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:

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)

files must contain a header record being the first record in the file.

Record Structure

Field explanations

Example  H C74EF975-5429-4663-85FB-2A64CA0FB9EF 1 Mandates My Test Batch 20100331 24ade73c-98cf-47b3-99be-cc7b867b3080

Key record (K)

• The key record is mandatory and appears in the file between the header record and the transaction records.
• The key record is mandatory and appears 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 102 161 110 114 113 121 122 123 202 530 531 532 534 535 536 540 541 202 311

Transaction record (T)

• There must be at least one transaction record in the file.
• 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.

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
102	Mandate name
103	Mandate active
110	Is Consumer
113	Surname
114	First name
117	Date of Birth
119	Title
121	Trading name
122	Registration number
123	Registered name
126	Bank account verification number (ID number/Company registration number)
127	Is ID number
131#	Mandate type (Bank account or Credit card)
132#	Bank account name/Name on Credit card
133#	Bank account type/Credit card type
134#	Branch code/Expiry month
135#	Filler/Expiry year
136#	Bank Account number / Credit card token
161	Default mandate amount
201	Email address
202	Account holder mobile number (N10) eg. 0801234567
241	Include DebiCheck authentication
242	DebiCheck mandate template Identifier
243	DebiCheck collection amount
246	DebiCheck first collection differs
247	DebiCheck first collection amount
248	DebiCheck first collection date
250	Collection frequency day code
281	Debit Masterfile group
311	Field 1
312	Field 2
313	Field 3
314	Field 4
315	Field 5
316	Field 6
317	Field 7
318	Field 8
319	Field 9
341	Phone number
530	Debit Frequency
531	Commencement month
532	Commencement day (debit day options)
533	December debit day
534	Agreement date
535	Agreement reference number
536	Cancellation notice period
537	Allow variable debit amounts
538	Request AVS
539	Additional clauses
540	Send mandate
541	Debit day on a public holiday
542	Add to Masterfile

If one or more of the banking/card detail fields indicated by a “#“ above is included in the transaction line; all the banking/card detail fields indicated by # above become mandatory. Although not mandatory for using this web service; fields 131 – 136 must all be present in the request if one or more of the fields (131-136) are sent,

Field explanations

NOTE: 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 explanations

Example

F 2 0 9999

Retrieving the Load Report

Postback option

Where the postback option in your NetConnector profile is utilised, the load report is automatically posted back to the URL specified.

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

Requests to the web service are sent as strings

Example:

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)

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

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

Retrieve Batch Status

Click here for the Netcash Retrieve batch status file format. Retrieve Batch Status is a web service that allows a user to retrieve up to the last 10 (ten) batches uploaded to the Netcash system. The web service will return all batches, whether they were uploaded via the web service or manually created via the Netcash web site.

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