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

Standard Debit Orders


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

See the service overview here.

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 that exposes multiple methods. The method BatchFileUpload allows an external system to submit a batch file of Debit orders (Same day / Two day) for processing.


Netcash is compliant with the Payment Card Industry Data Security Standards (PCI DSS) and will not accept Credit Card numbers. Tokens representing the card detail and masked credit card numbers (for tracing purposes) may be submitted. any file containing unmasked credit card numbers will be rejected.

Credit Card Tokenization File Specification

Click here for the Netcash Credit Card Debit Order Tokenization format. This format is used to encrypt credit card details so that your host system may store PCI compliant credit card information for recurring billing.

Electronic Debit Order Mandates

Click here for the Netcash Electronic Debit Order upload file format. e-Mandate request is a web service that allows a remote system to send batched requests to Netcash  that create and send e-Mandates  to account holders for approval

The Service

Object Name Description
method BatchFileUpload


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


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

Once you have built the file call:

  • Web service:
  • Method: BatchFileUpload
  • Service key: Debit order service key


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)


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

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

            //use response to call RequestFileUploadReport method
            return Request;


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 requires 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 match the order defined in the Key Record.
F – Footer record is 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 Update – update the master file without loading a batch
Sameday – Sameday batch upload (ideal for once off collection where the time the recipient is debited)
TwoDay – Dated debit order batch upload
Refer to service cutoff times below
Batch name Use this field as an identifier of your batch.
Action date The date on which the payments are debited to the payers 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)


H C74EXXX5-5499-4663-85FB-2A6XXXXFB9EF 1 TwoDay 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 and transaction records.
  • It defines the content, order and length of the transactions records in the file. It can be likened to the column headings in a spreadsheet.
  • All the possible fields contained in the subsequent transaction records are listed, even if not every transaction record contains data in all the fields listed.
  • It is good practice to list keys in ascending order to assist where debugging and support are required.


K 101 102 131 132 133 134 135 136 162

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.


T Acc001 AccName001 1 BankAccountName001 1 470010 0 25000000000 100

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 Update SameDay/TwoDay
101 Account reference required required
102 Account name required required
103 Account active
104 Delete this account
131 Banking detail type required required
132 Bank account name/Credit card holder name as it appears on the front of the card required required
133 Bank account type/Credit card type required required
134 Branch code/Expiry month required required
135 Filler/Expiry year required required
136 Bank account number/Credit card token required required
137 Masked credit card number required *
161 Default debit amount required
162 Amount required
201 Email address
202 Mobile number *
281 Debit masterfile group
301 Extra 1
302 Extra 2
303 Extra 3
509 Resubmit unpaids via Pay Now **



  • * Field 137 is mandatory for any file that contains debits against credit cards. The field should be present but left blank for records containing normal bank account numbers.
  • **Field 509 is not a mandatory field.
    If the 509 key record is included in a file (Batch upload or Master file update) the field content will be validated and MUST contain 0 or 1..
    The debit order Masterfile will be updated with the value in the field. If the 509 key record is not included in an upload file, no action will be taken

Any masterfile records included in a batch file upload instruction will automatically be marked as “Active” on the relevant masterfile.


Optional fields

If the optional fields can be included in the transaction records, they are to be specified in the key record (K).

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.


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


F 2 0 9999

Example of input file

Example of input file

H  C74EXXX5-5499-4663-85FB-2A6XXXXFB9EF 1  TwoDay   My Test Batch  20131204  24ade73c-98cf-XXXX-XXXX-cc7b867b3080
K  101   102   131   132   133   134   135   136   162
T  CUS001    A Customer  1  AB Customer    1  632005  0    40600000004 110200
T  CUS002    X Customer  1  X Customer  2  198765  0    2060000001   200000
F  2  310200  9999

Example of string file (C#)

string fl = "H\tC74EXXX5-5499-4663-85FB-2A6XXXXFB9EF\t1\tTwoDay\tMy Test Batch\t20131204\t24ade73c-98cf-XXXX-XXXX-cc7b867b3080" + Environment.NewLine +
"K\t101\t102\t103\t104\t131\t132\t133\t134\t135\t136\t161\t162\t302" + Environment.NewLine +
"T\tUniqueRef1\tAccountName\t1\t0\t1\tJoe Bloggs\t2\t632005\t0\t9091111334\t10000\t10000\tExtra2" + Environment.NewLine +
"T\tUniqueRef2\tAccountName2\t1\t0\t1\tSam Smith\t1\t250655\t0\t4011111193\t10000\t10000\tExtra2" + Environment.NewLine +
"T\tUniqueRef3\tAccountName3\t1\t0\t1\ John Jones \t2\t03\t2017\t25ayz73c-98cf-47b3-99be-cc7b867b3121 /t4208000000003456\t10000\t10000\tExtra2" + Environment.NewLine +
string FileToken = BatchFileUpload("xx34x5802-xxxx-abcd-c7xxxxz1ad9q", fl);

Processing deadlines

  • All times in 24HR format.
  • The action date is the date the transaction is processed to the debtors bank account.

TIP: See request action date web service

  • Business days are the days between -and including Monday to Friday but does not include public holidays and/or weekends.
Same day debit orders Two day debit orders
Must be loaded -and authorized
on Netcash before
10:59 on the action date (Mon-Fri) -or
23:59 one (1) business day prior
to the action date for Saturday service
23:59 two (2) business days prior to action date
Debits processed by banks
(as a general rule but might
differ from bank to bank)
usually after 16h00 on the action date usually 00h02 on the action date
Availability of collected value
less retentions and fees as available balance
in the Netcash merchant account
One (1) business day after the action date. On the action date.
Processing days
(excluding public holidays)
Monday to Saturday Monday to Friday

Retrieving the Load Report

Postback option
Where the postback option in your NetConnector profile is utilised, the load report is automatically posted back to the URL specified.

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


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

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


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

###END 01:59 PM

Upload report example (successful with errors):

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

###ERROR: A system error occurred. Please contact Netcash R0.00 20160410
###END 01:23 PM

Credit Card Vault Tokenization Web Service

Technical Information

The Netcash vault web service is provided for the secure storage of credit card numbers in terms of the Payment Card Industry Data Security Standard (PCI DSS). The service accepts credit card details into a secure PCI DSS compliant environment and returns a credit card token together with a masked version of the credit card number.

The credit card token is used in all transactions performed against the account in place of the credit card number. It is not necessary to request a new token each time a transaction is performed against the card. The token remains valid for the life of the card. (A new token should only be requested if the card details change or expire). a Tokenization web service is also available to update card details.

Netcash Vault is a synchronous web service. The credit card token and masked credit card number will be returned to the calling system without the need for polling or postback.



Open the page in an iFrame first, and test using Safari on Apple devices. Depending on the Mac OS/iOS version the call should work with the iFrame (it is Google Chrome and Microsoft Edge is compliant).

If the call to a OS/iOS Safari browser poses a problem; use cross site scripting errors in Safari where you may need to explicitly add the lines below to the web.config file:

            <remove name="X-Powered-By"/>
                <add name="Access-Control-Allow-Origin" value="*" />
                <add name="Access-Control-Allow-Headers" value="Content-Type, Accept, SOAPAction"/>
                <add name="Access-Control-Allow-Methods" value="GET,POST,PUT,DELETE,OPTIONS" />
                <add name="Access-Control-Allow-Credentials" value="true" />
                <add name="p3p" value="CP=&quot;IDC DSP COR ADM DEVi TAIi PSA PSD IVAi IVDi CONi HIS OUR IND CNT&quot;"/>
                <add name="X-UA-Compatible" value="IE=Edge" />

Creating the call

You must be sure to add a postback URL PCI Vault screen on your system frontend, otherwise you will get a message stating that they do not have access to the page.

To get the PCI Vault service key required to use this method you need to log in to the Netcash Account, click on Account Profile, open NetConnector, click on PCI Vault Key; here you will find the key but you need to also add the return URL. To do this click edit and add your return URL where we need to post back the result to and then click submit.

Create a form post

<form action="" method="post" name="payNowForm">
    <input id="PciKey" name="PciKey" type="hidden" value="PCI-VAULT-SERVICE-KEY---OBTAIN-FROM-MERCHANT-SITE" />
    <input type="hidden" name="Extra1" value="Extra ">
    <input type="hidden" name="Extra2" value="Extra 2">
    <input type="hidden" name="Extra3" value="Extra 3">
    <input type="submit" value="Pay by Credit Card">

Extras 1 – 3 are not compulsory fields, only PciKey.


If tokenisation is successful, the following fields will be returned:

Successful = 1
Token = Vault token for card

If tokenisation failed, the following fields will be returned:

Successful = 0

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 system. The web service will return all batches, whether they were uploaded via the web service or manually created via the Netcash web site.


Compact Upload File Specification

Click here for the Netcash Compact Debit Order upload file format. The compact file format is used where large number of transaction records are UPDATED for processing of a Debit Order batch. New line items can not be loaded with the Compact Debit Order upload file format.


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