Overview
A web service ‘NIWS_NIF’ used to request mandate data
The service is asynchronous and comprises 2 method calls:
- RequestMandateData (Returns a file token)
- RetrieveMandateData (Returns a tab-delimited file of mandate data)
Technical Information
NIWS_NIF is an asynchronous web service which exposes multiple methods. The method RequestMandateData and RetrieveMandateData allow an external system to download a file of all mandates currently in the system.
Request Mandate data
- Web service: https://ws.netcash.co.za/niws/niws_nif.svc
- Method: RequestMandateData
- Service key: Debit order service key
Requests to the web service are sent as strings
Example: public string RequestMandateData(string ServiceKey)
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 NetcashTechnical 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.
File header
(occurs once at the start of the file)
|
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 authorisation 3 – Expired 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-monthly3 = Three monthly4 = Six monthly5 = 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 = Visa
If Bank account: 1 = Current 2 = Savings 3 = Transmission |
|
| 25 | Branch code/Expiry month |
If Credit card: 2 digit month (MM) include leading zero
If 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 processing
If 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 Masterfile group | The group to which the mandate is linked | |
| 31 | Field 1 | Additional data supplied | |
| 32 | Field 2 | ||
| 33 | Field 3 | ||
| 34 | Field 4 | ||
| 35 | Field 5 | ||
| 36 | Field 6 | ||
| 37 | Field 7 | ||
| 38 | Field 8 | ||
| 39 | Field 9 | ||
| 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 |