DebiCheck Amend Authentication

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.

Contract Types

1. Fixed: terms of the contract remain unchanged. For example, a gym contract.
2. Variable: contract terms may change. eg, a home loan may vary in line with the prevailing interest rates. ^*Note
3. Usage-based: terms of the contract change regularly. eg, a cellphone bill may vary monthly based on usage.

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:

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 explanations

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
Service Key			Debit order service key is required
102	Account name		AN50	The name of the Debit Order Master file account
111	SA ID Number		N13
127	Is ID number		N1	0 = Not an SA ID number 1 = is an SA ID
133	Bank account type		N1	1 = cheque 2 = savings
136	Bank Account Number			The bank account numbers can only be amended within the same branch. If the branch code changes the change will require re-authentication by the account holder
243	DebiCheck collection amount		N	In cents
604	Max Collection Amount		N	In cents
617	Contract Reference of DC authentication being amended		AN50

Example

H	59B81F94-7C38-XXXX-XXXX-ACA2E1517011	1	DebiCheckAmend	Batch2	20231010	24ade73c-98cf-47b3-99be-cc7b867b3080
K	617	102	243	604	111	127	133	136	602
T	NC000000012213	NEVILLE MCKENZIE	19700	19900	910330####081	1	1	6281###6918	0
T	NC000000012371	ELTON MAY	49800	50000	840717####088	1	1	126###8009	0
F	2	69500	9999

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 explanations

Example  F 2 0 9999

Postback option

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 header

(occurs once at the start of each load report)

Load report message

(occurs multiple times – once per error record)

Load report trailer

(occurs once – the last line in the report)

H	59B81F94-7C38-XXXX-XXXX-ACA2E1517011	1	DebiCheckAmend	Batch2	20231010	24ade73c-98cf-47b3-99be-cc7b867b3080
K	617	102	243	604	111	127	133	136	602
T	NC000000012213	NEVILLE MCKENZIE	19700	19900	910330####081	1	1	6281###6918	0
T	NC000000012371	ELTON MAY	49800	50000	840717####088	1	1	126###8009	0
F	2	69500	9999

XML

<BatchFileUpload>
  <MethodParameters>
    <ServiceKey>59B81F94-7C38-XXXX-XXXX-ACA2E1517011</ServiceKey>
    <File>H    59B81F94-7C38-XXXX-XXXX-ACA2E1517011    1    DebiCheckAmend    Batch2    20231010    24ade73c-98cf-47b3-99be-cc7b867b3080
K    617    102    243    604    111    127    133    136    602
T    NC000000012213    NEVILLE MCKENZIE    19700    19900    910330####081    1    1    62818###918    0
T    NC000000012371    ELTON MAY    49800    50000    840717####088    1    1    126###8009    0
F    2    69500    9999</File>
  </MethodParameters>
</BatchFileUpload>

Response

<BatchFileUpload>
  <MethodParameters>
    <String>10013792.1000831941.8519.31142.011</String>
  </MethodParameters>
</BatchFileUpload>

DebiCheckAmendAuthentication Single transaction

Technical Information

• Web service: https://ws.netcash.co.za/niws/niws_nif.svc
• Method: DebiCheckAmendAuthentication
• Service key: Debit order service key

Input

Submit the following parameters

Response

<DebiCheckAmendAuthentication>
  <MethodParameters>
    <DebiCheckAmendmentResponse>
      <ContractReference>NC000000012213</ContractReference>
      <Messages attr0="StringArray" isNull="false" />
      <ErrorCode>000</ErrorCode>
    </DebiCheckAmendmentResponse>
  </MethodParameters>
</DebiCheckAmendAuthentication>

Testing

See Testing section for more details. If you require any integration assistance contact our technical support team