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