Currently set to Index
Currently set to Follow
  1. Home
  2. /
  3. Inbound Payments
  4. /
  5. Electronic Debit Order Mandates
  6. /
  7. Electronic Mandates Web Service...

Overview

e-Mandate download data is a web service that allows a remote system to send electronic requests to the Netcash system to download a file of electronic debit order mandates.

The service is asynchronous and comprises 2 method calls:

  • RequestMandateData (Returns a file token)
  • RetrieveMandateData (Returns a tab-delimited string of mandate data)

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

Input

Requests to the web service is sent as a string.

Example:

public string RequestMandateData(string ServiceKey, string FileToken)

Output

Successful request

The method returns a file token for successful requests
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
200 General code exception. Please contact Netcash Technical Support.

 

Retrieve Mandate data

 

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

Requests to the web service are sent as strings

Example:

public string RetrieveMandateData(string ServiceKey, string FileToken)

Output file

The file returned contains a record for every mandate held in the system

File structure

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

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

Header record (H)

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


Record Structure

Field Name Value
1 Record Identifier ###BEGIN
2 Date CCYYMMDD

 

Mandate records (occurs multiple times – once per mandate)

Field Field name Explanation
1 Status 1, 8 or 11 – Capturing
2 – Awaiting authorization
3 – Expire
4 – Failed
5 – Declined
6 – Accepted
7 – Details changed
9 – Verified
10 – Unverified
2 Account reference Your reference for the mandate
3 Mandate name Client name
4 Mandate amount Amount in decimal (EG: 123.45)
5 Is Consumer “0” Company
“1” Individual
6 First name Account holder first name
7 Surname Account holder surname
8 Trading name Business account name
9 Registration number Business account registration number
10 Registered name Business account registered name
11 Mobile number Account holder cell number EG: 27827822349
12 Debit Frequency 1 = Monthly
2 = Bi-monthly
3 = Three monthly
4 = Six monthly
5 = Annually
6 = Weekly
7 = Bi-weekly
13 Commencement month MM
14 Commencement day (debit day options) Debit day options
01 – 31 or Last day of month
Forward slash separated list
EG: 05/15/25/LDOM
15 Agreement date CCYYMMDD
16 Agreement reference number Your reference for this agreement
17 Cancellation notice period 01 – 60
18 Debit day on public holiday Alternate debit day if debit day if selected debit day falls on a non-business date
0 = Preceding ordinary business day
1 = Very next ordinary business day
19 Mandate active 0 = Inactive
1 = Active
20 Title 1 = Mr
2 = Mrs
3 = Ms
4 = Miss
5 = Dr
6 = Prof
21 Email address The email address of the account holder
22 Mandate type (Bank account or Credit card) 1 = Bank account
2 = Credit card
23 Bank account name/Name on Credit card The name of the bank account holder
24 Bank account type/Credit card type If Credit card:
1 = Mastercard
2 = VisaIf Bank account:
1 = Current
2 = Savings
3 = Transmission
25 Branch code/Expiry month If Credit card:
2 digit month (MM) include leading zeroIf Bank account:
The branch code of the account to be debited
26 Expiry year / filler If Credit card:
4 digit year (CCYY)If Bank account:
0 (Filler)
27 Account number/ Credit card token If Credit card:
PCI Token generated for Credit card processingIf Bank account:
The bank account number to be debited
28 Bank account verification number (ID number/Company registration number) The number linked to the bank account.
29 Is Id number 0 = Not an SA Id number
1 = SA Id number
30 Debit Order Masterfile group The Debit Order Masterfile group to which the mandate is linked
31 Field 1 Additional data supplied
32 Field 2 Additional data supplied
33 Field 3 Additional data supplied
34 Field 4 Additional data supplied
35 Field 5 Additional data supplied
36 Field 6 Additional data supplied
37 Field 7 Additional data supplied
38 Field 8 Additional data supplied
39 Field 9 Additional data supplied
40 December debit day 01 – 31 or Last day of month
Forward slash separated list
EG: 05/15/25/LDOM
41 Allow variable debit amounts 0 = Do not allow variable amounts
1= Allow variable amounts
43 Request AVS 0 = Do not run Bank account verification check
1= Run Bank account verification check
43 Additional clauses The ID of additional clauses included in the mandate (Comma separated list)

 

File trailer (occurs once – the last line in the file)

Field Name Value
1 Record identifier ###END

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 © 2022 Netcash (PTY) Ltd

Programmers Guide