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
DebiCheck is a preferential debit order system requiring the bank account holder to give specific electronic permission (via their bank) prior to any debit order being processed.
- Fixed: terms of the contract remain unchanged. For example, a gym contract.
- Variable: contract terms may change. eg, a home loan may vary in line with the prevailing interest rates. *Note
- Usage-based: terms of the contract change regularly. eg, a cellphone bill may vary monthly based on usage.
Authentication Options
Registered Mandate Service (RMS)
When a request from the bank to the customer to approve a mandate is not actioned by the customer, and the request expires, you can register a “RMS Mandate” against the customers’ account with the same detail as agreed in the underlying contract. When an RMS Mandate is registered, the customer will not be required to authenticate the mandate, however they will be able to dispute or suspend (place a stop payment) against the mandate.
RMS must be requested in the DebiCheck authentication process and must be registered within 10 days of the original authentication.
Important
A new record must be added to the Debit Order master file where the Account Reference does not already exist. DebiCkeck Authentication can only be processed if the Debit Order master file entry exists.
Disputability
This service allows a remote system to request DebiCheck authentication on an existing mandate not initiated via the Netcash electronic mandate service.
The Debit order Master file entry will be updated with the DebiCheck mandate authentication where the Account Reference (101) supplied exists.
Technical Information
- 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 is sent as a string.
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:
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. |
203 | Collection day frequency code is invalid for the Installment occurrence selected |
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
Field | Name | Type | Value |
1 | Record Identifier | AN | H |
2 | Service Key | AN | Service GUID |
3 | Version | AN | 1 |
4 | Instruction | AN | Purpose of the file |
5 | Batch name | AN | Your identifier |
6 | Action date | N | CCYYMMDD |
7 | Software vendor key | AN | The key issued by Netcash to identify the software origin of transactions. (only used by Netcash ISV‘s else use the default value: 24ade73c-98cf-47b3-99be-cc7b867b3080) |
Field explanations
Field | Explanation |
Record Id | “H” – Identifies the record as a header |
Service key | Debit order service key |
Version | “1” – This is the Netcash version of the file specification |
Instruction | DebiCheckAuthentication |
Batch name | Use this field as an identifier of your batch. |
Action date | Current date |
Software Vendor Key | The key issued by Netcash to identify the software origin of transactions. (only used by Netcash ISV‘s else use the default value: 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.
- The key defines the content, order and length of the transaction records in the file. It can be likened to the column headings in a spreadsheet.
- The key lists all the possible fields contained in the subsequent transaction records, even if not every transaction record contains data in all the fields.
- While the file is customizable, it is recommended that keys are listed in ascending numerical order for ease of debugging and support.
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.
(In the example above, the account reference (field id 138) is defined as the first field in the record, therefore, every transaction record MUST have the Budget as the first field or it will fail validation) - Every transaction record must have the same number of fields as defined in the key record (K).
- Empty fields should be replaced by a blank tab or a default value, where one has been defined.
Where fields are left empty, the Netcash system will assume spaces or zeroes for fields defined in the key record.
Mandatory fields
The fields indicated by are mandatory for the specified instruction.
Key | Field name | Mandatory See key legend for value requirements |
Type | Description |
101 | Account reference | AN32 | The reference of the Debit order Master file account | |
102 | Account name | AN50 | The name of the Debit order Master file account | |
111 | ID number | AN13 | SA ID number | |
127 | Is ID number | N1 | 0 = Not an SA ID number 1 = is an SA ID (CDV validation applied before submission to the bank) |
|
132 | Bank account name | AN30 | The name of the account holder | |
133 | Bank account type | N1 | 1 = cheque 2 = savings |
|
134 | Branch code | N6 | The six digit branch code | |
136 | Account number | N16 | The bank account number | |
201 | Email address | AN50 | Email address of account holder | |
202 | Mobile number | N11 | Mobile number of account holder | |
242 | DebiCheck template identifier | AN14 | The reference of your pre-defined DC template as created on the Netcash system EG: NCDCT000000003 *See important note | |
243 | DebiCheck collection amount | N | In cents | |
246 | DebiCheck first collection differs | N1 | 0 = first collection amount is the same as field 243 1 = first collection amount is different to field 243 |
|
247 | DebiCheck first collection amount | N | In cents | |
248 | DebiCheck first collection date | N8 | CCYYMMDD | |
250 | Collection frequency day code | AN7 | Collection day code *See codes here |
NOTE: These fields are not required in the input file as they are hard-coded in the Netcash system
131 | Banking detail type | Only bank accounts are permitted (assume 1) |
135 | Expiry year / Filler | Pertains to credit cards only (assume 0) |
241 | Include DebiCheck authentication | Assume 1 (True) |
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.
Structure
Field | Name | Type | Value |
1 | Record Identifier | AN | F |
2 | No of transactions | N | A count of the transaction records |
3 | Sum of amounts | N | The sum of the monetary fields (in cents) |
4 | End-of-file indicator | N | 9999 |
Field explanations
Field | Explanation |
Record Identifier | “F” – Identifies the record as a footer |
No of transactions | This is the count of all the ‘T’ records in the file. |
Sum of amounts | This is the sum of all the values in the 161 fields. |
End-of-file indicator | ‘9999’ – Indicates there are no more records. |
Example F 2 0 9999
Postback option
A postback feature has been activated for this service.
Data regarding each DebiCheck authentication will be sent to the postback URL when received from the account holders’ bank.
The data received will be sent to the postback URL as setup in the NetConnector profile settings of the Netcash account.
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 file
File content
Only errors are reported in the file. If all the entries in the file are successfully validated, the Load report header will contain “SUCCESSFUL” and there will be no detail messages.
File structure
The report is tab delimited with a linefeed character as line terminator.
Load Report
Output file
File content
Only errors are reported in the file. If all the entries in the file are successfully validated, the Load report header will contain “SUCCESSFUL” and there will be no detail messages.
File structure
The report is tab-delimited with a linefeed character as a line terminator.
Load report header
(occurs once at the start of each load report)
Field |
Name |
Type |
Value |
1 |
Record identifier |
AN8 |
###BEGIN |
2 |
Batch name |
AN |
{your batch name} |
3 |
Result of upload |
A13 |
SUCCESSFUL / UNSUCCESSFUL / SUCCESSFUL WITH ERRORS |
4 |
Start time of report |
AN8 |
HH:MM AM/PM |
Load report message
(occurs multiple times – once per error record)
Field |
Name |
Type |
Value |
1 |
Unique reference |
AN25 |
The unique reference you supplied in (p2) |
2 |
Line number |
AN |
Line :{line in your file where error was found} |
3 |
Error message |
AN |
The error message |
OR |
|||
1 |
Record identifier |
AN8 |
###ERROR |
2 |
Error message |
AN |
The error message |
Load report trailer
(occurs once – the last line in the report)
Field |
Name |
Type |
Value |
1 |
Record identifier |
AN6 |
###END |
2 |
End time of report |
AN8 |
HH:MM AM/PM |
Response
Netcash receives the file of DebiCheck authentication requests and processes them via the sponsoring bank. Requests are sent to the issuing bank via Bankserv for authentication by the account holder. Responses are returned via the same channels.
Once received by Netcash, the responses are posted back to the URL configured under the Debit order section of the Netconnector menu.
"AccountReference": <merchant account reference> "ContractReference": <contract reference> "Process": Initiation "Status": Accepted / Rejected "RMS": true/ false "Timestamp": yyyy-MM-ddTHH:mm:ss.fffK "type": DEBICHECKRESULT
Examples
Status: Accepted
Client response: Accepted
Status: Cancelled
Client response: Accepted
Status: Rejected
Client response: Rejected
Status: Rejected
Client response: No response
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