Currently set to Index
Currently set to Follow
  1. Home
  2. /
  3. Inbound Payments
  4. /
  5. DebiCheck Debit Orders

DebiCheck Debit Orders

Overview

The Netcash debit order service allows for automated uploading of debit order batches to Netcash accounts using the NIWS_NIF web service.

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. It does not replace Same-day and Dated debit orders but can be used as an alternative. By using DebiCheck you can obtain authentication, benefit from preferential presentation of the debit and track the bank account over a selected period.

Read more about DebiCheck contract types and authentication options here

Click here for information on the DebiCheck Authenticationwithout using the Netcash eMandates.

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

Programmers Guide

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

Technical Information

NIWS_NIF is an asynchronous web service which exposes multiple methods. The method BatchFileUpload allows an external system to submit a batch file of DebiCheck Debit Orders for processing.

Netcash is compliant with the Payment Card Industry Data Security Standards (PCI DSS) and does therefore not accept or store Credit Card numbers. Only tokens representing the card details and masked credit card numbers (for tracing purposes) may be submitted in this file. The system will reject any file which contains unmasked credit card numbers.

The Service

Object Name Description
method BatchFileUpload

Parameter:

  • ServiceKey (Debit order service key)
  • File (Built in external system)
method RequestFileUploadReport

Parameter:

  • ServiceKey (Debit order service key)
  • FileToken (received on file upload if successful)

Once you have built the file call:

  • 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 are sent as strings

The BatchFileUpload method requires two parameters: –

  • Service key (to authenticate the method call)
  • File (the batch file containing the debit order instructions)

Example

public string BatchFileUpload(string ServiceKey, string File)
        {
            //initialise client 
            NIWS_NIF.NIWS_NIFClient client = new NIWS_NIF.NIWS_NIFClient();

            //call the BatchFileUpload method equal to a string variable
            string Request = client.BatchFileUpload(ServiceKey, File);

            //close client after response is received
            client.Close();

            switch (Request)
            {
                case "100"://Authentication failure
                    break;
                case "102"://Parameter error
                    break;
                case "200"://General code exception. 
                    break;
                default: //successful
                    return Request;
            }

            //use response to call RequestFileUploadReport method
            return Request;
        }

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
101 Date format error. If the string contains a date, it should be in the format CCYYMMDD
102 Parameter error. One or more of the parameters in the string is incorrect
200 General code exception. Please contact Netcash Technical Support.

Unpaid reason codes

Click here for a complete list of unpaid transaction codes

Input File Structure

The file is a tab delimited text file and 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.

Field Name Type Value
1 Record Identifier AN H
2 Service Key AN Debit Order Service Key
3 Version AN 1
4 Instruction AN Purpose of the file
5 Batch name AN Your identifier
6 Action date N CCYYMMDD   TIP: See request action date web service
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 DebiCheck – upload a batch of DebiCheck debit orders to the Netcash system
Batch name Use this field as an identifier of your batch.
Action date The date the DebiCheck debits should start tracking on the client’s bank account.
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)

Example

H C74EXXX5-5499-4663-85FB-2A6XXXXFB9EF 1 DebiCheck My Test Batch 20100331 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 transactions 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.

Example

K 101 162 232 249 301 302 303

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 101) is defined as the first field in the record therefore every transaction record MUST have the account reference 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 field

The fields indicated by tick are mandatory for the specified instruction.

See the full API key legend for value requirements

Key Field name Mandatory
101 Account reference required
249 DebiCheck mandate reference required
232 DebiCheck tracking days required

Optional fields

Additional data pertinent to the Debit order.

If field 162 (Debit amount) is not specified, the amount stipulated in the mandate will be debited to the account.

Specify any optional fields included in the transaction records in the key record (K).

Key Field name Mandatory
162 Debit amount
301 Extra 1
302 Extra 2
303 Extra 3

Transaction fields

Field Name Type Value
101 Account reference AN22 The unique reference for this client in your debit order Masterfile.
232 DebiCheck tracking days N2 Specify the number of days to track against the client’s bank account (1 – 10)
249 DebiCheck mandate reference AN50 The unique DebiCheck reference associated with the approved mandate for this client
162 Debit amount N The amount of the debit (in cents)
301 Extra 1 AN999 Custom user-defined data (Extra data you want returned for your internal system use)
302 Extra 2 AN49 Custom user-defined data (Extra data you want returned for your internal system use)
303 Extra 3 AN49 Custom user-defined data (Extra data you want returned for your internal system use)

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.
If field 161 is not specified in the key record, this will be the sum of all the 162 fields.
End-of-file indicator 9999’ – Indicates there are no more records.

Examples

F 2 0 9999

Example of input file

Example of input file

H  C74EXXX5-5499-4663-85FB-2A6XXXXFB9EF 1  DebiCheck   My Test Batch  20131204  24ade73c-98cf-XXXX-XXXX-cc7b867b3080
K  101   162   232   249   301   302   303   
T  AB001123456   150000   9  NC00000021  Jones  Sept Inv123456    ajones@mweb.co.za 
T  CD001123457   17500  3  NC00000134  Brown  Sept Inv123457    No email 
F  2  167500  9999

Retrieving the Load Report

Postback option
If you have activated the postback option in your NetConnector profile, the load report is automatically posted back to the URL you supplied.

Polling option
If you have not activated the postback option, you will need to request the load report using the file token received from the BatchFileUpload method call.

Using the file token, call:

Requests to the web service are sent as strings

Example

public string RequestFileUploadReport(string ServiceKey, string FileToken)
        {
            //initialise client 
            NIWS_NIF.NIWS_NIFClient client = new NIWS_NIF.NIWS_NIFClient();

            //call the RequestFileUploadReport method equal to a string variable
            //the same service key used for the bactch file upload
            string Request = client.RequestFileUploadReport(ServiceKey, FileToken);

            //close client after response is received
            client.Close();

            //use response to output to UI
            //service will respond with the result of the file uploaded
            return Request;
        }

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 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
5 Batch Value AN15 TOTAL OF BATCH
6 Action Date AN8 CCYYMMDD

Load report message (occurs multiple times – once per error record)

Field Name Type Value
1 Account reference AN58 Acc Ref :{your account reference}
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

Upload report example (successful):

###BEGIN MY TEST BATCH SUCCESSFUL 01:59 PM R1.00 20160410
###END 01:59 PM

Upload report example (successful with errors):

###BEGIN MY TEST BATCH SUCCESSFUL WITH ERRORS 01:29 PM R1.00 20160410
Acc Ref :XI5 Line :3 Account details could not be validated. Please check the fields Bank account type, Branch code and Account number.
Acc Ref :XI5 Line :3 Bank account number has incorrect length (min 4, max 11 characters)
Acc Ref :HCOS1 Line :5 Beneficiary statement reference has incorrect length (min 4, max 20 characters)
Acc Ref :HCOZ1 Line :6 Beneficiary statement reference has incorrect length (min 4, max 20 characters)
###END 01:29 PM

Upload report example (unsuccessful):

###BEGIN MY TEST BATCH UNSUCCESSFUL 01:23 PM R1.00 20160410
###ERROR: A system error occurred. Please contact Netcash R0.00 20160410
###END 01:23 PM

Retrieve Batch Status

Click here for the Netcash Retrieve batch status file format. Retrieve Batch Status is a web service that allows a user to retrieve up to the last 10 (ten) batches uploaded to the Netcash (ZA) system. The web service will return all batches, whether they were uploaded via the web service -or manually created via the Netcash (ZA) web site.

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

Programmers Guide