- Home
- /
- Inbound Payments
- /
- Electronic Debit Order Mandates
- /
- 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)
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: RequestMandateData
- Service key: Debit order service key
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
Version 2020.1
Copyright © 2022 Netcash (PTY) Ltd