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.

Technical Information

NIWS_NIF is an asynchronous web service that exposes multiple methods.
The method BatchFileUpload allows an external system to upload a batch file of mandate requests.

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


public string BatchFileUpload(string ServiceKey, string File)


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 Sage Pay Technical Support.


Input File Structure

Each file has the following mandatory records:

H – Header record identifies the upload and passes instructions to the Sage Pay 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 code AN Your software vendor code


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 MandateToMasterfile – Update Debit order Master file with mandate data
Batch name Use this field as an identifier of your batch.
Action date Current date
Software vendor code This is a code issued by Netcash.



H	C74EF975-5429-4663-85FB-2A64CA0FB9EF	1	MandateToMasterfile	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 allthe 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.



K 101

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.
    (As stipulated in the key, only the account reference of the mandate is required in the T record)


Mandatory fields


The fields indicated by  are mandatory for the specified instruction.


Key Field name Mandates
101 Account reference

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


Transaction fields

Field Name Type Value
101 Account reference AN22 The unique reference used to identify the mandate.

(Existing Debit Order master file references will be updated. New references will be created where they do not exist in the Debit order master file)

Minimum 2 Maximum 22 characters



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 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 0
End-of-file indicator ‘9999’ – Indicates there are no more records.



F 2 0 9999


Retrieving the Load Report

Postback option

Postback has not been activated in this version of the service


Polling option

You will need to request the load report using the file token received from the BatchFileUpload method call.


Using the file token, call:

  • Web service:
  • Method: RequestFileUploadReport
  • Service key:  Debit Order service key

Requests to the web service are sent as strings



public string RequestFileUploadReport(string ServiceKey, string FileToken)


Output file


File content

If the file submitted is in the correct format, the Load report header will contain “SUCCESSFUL”.

The Load report will contain a result (Created, Updated or Failed) for each Account reference submitted.


  • Created indicates a new record was created in your debit order Masterfile
  • Updated indicates that an existing record was overwritten with the data extracted from the Mandate
  • Mandate not found indicates that the Account reference supplied does not exist
  • Failed indicates that the Creation/Update could not take place due to a data error.


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 /
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 Account reference you supplied
2 Line number AN Line: {line in your file}
3 Error message AN  “Created” “Updated” “Mandate not found” or “Failed”
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

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.


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

Netcash may provide example/sample/demo ‘code snippets’ and/or external links in this Technical Document. Such are for guidance purposes only and may not function on every developer’s system/s. Netcash disclaims any and all liability for the usage of guidance resources provided -and you as the Developer; must accept full responsibility for the usage of such. While every possible effort has been taken to ensure compatibility across multiple system configurations, the contents of this document cannot be guaranteed to work on all systems, with all operating systems -and/or with all system configuration/s.