eMandate – Download Mandate Data – .pdf format

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

The Netcash web service ‘NIWS_NIF’ used to send batched mandate account references to retrieve mandates electronically signed by the account holder.

The service is asynchronous and comprises 3 methods:

• BatchFileUpload (NIF file containing a list of Mandate account references)
• RequestFileUploadReport (Returns the result of the NIF file upload including any errors encountered)
• RetrieveMandatePDF (Returns a link to the Mandate PDF for the account references requested)

Request PDF by Account reference

NIWS_NIF is an asynchronous web service which exposes multiple methods. The method BatchFileUpload allows an external system to upload a batch file of mandate PDF requests.

Once you have built the file call:

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 are sent as strings

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)

Every file must contain a header record as the first record in the file.

Record Structure

Example

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

For RequestMandatePDF, only key 101 (Mandate reference) is required

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.
(As stipulated in the key, only the account reference of the mandate is required in the T record)

Record structure

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.

Record structure

Example

F 2 0 9999

Retrieve Load report

You will need to request the load report using the file token received from the BatchFileUpload method call.

Input

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

If the file submitted is in the correct format, the Load report header will contain “SUCCESSFUL”.

Any format errors detected in upload file will be reported.

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 Signed Mandates

You will need to retrieve the signed mandates using the file token received from the BatchFileUpload method call.

• Web service: https://ws.netcash.co.za/niws/niws_nif.svc
• Method: RetrieveMandatePDF
• Service key: Debit Order service key

Input

Requests to the web service are sent as strings

Example:  public string RetrieveMandatePDF(string ServiceKey, string FileToken)

Output

The file returned contains a record for each mandate reference requested

File structure

The report is tab delimited with a linefeed character as line terminator.

File header

(occurs once at the start of the file)

Mandate records

(occurs multiple times – once per mandate reference)

File trailer

(occurs once – the last line in the report)

** Note: To access the URL you will be required to supply your Debit Order service key

The format is {shortSurfURL}?PKey={DebitOrderServiceKey}

Example:  https://short.surf/SPDxxx?PKey=3a9be0d4-9999-8888-7777-05bf64cac464

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