Compact Debit Order File

Overview

Netcash offers a web service called ‘NIWS_NIF’ used to send batched Debit Order files to a Netcash account and then the National Payment System

Technical Information

Note:
Before submitting a Compact File, the Netcash Debit Order Masterfile on must already contain the banking information recognised against the Account Reference (101) you are submitting in the file. If there is no entry in the Netcash Debit Order Masterfile for Account Reference (101) this transaction line will fail on upload.

NIWS_NIF is an asynchronous web service which 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 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

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:

Unpaid reason codes

Click here for a complete list of unpaid reason 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 explanations

Example

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

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.

Example

T Acc001 100

Mandatory field

The fields indicated by are mandatory for the specified instruction.

Key	Field name	Update	CompactTwoDay/CompactSameday
101	Account reference
162	Amount

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

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

Examples

F 2 0 9999

Example of input file

H 78e30d1e-aa36-0000-XXXX-dcd68866XXXX 1 CompactTwoDay Batch_Name 20131204 24ade73c-98cf-XXXX-XXXX-cc7b867b3080
K 101 162
T EMP001 110200
T EMP002 200000
F 2 310200 9999

Example of string file (C#)

StringBuilder file = new StringBuilder();
file.AppendLine("H\txx34x5802-xxxx-abcd-c7xxxxz1ad9q\t1\tCompactSameDay\tMASTERSTART6\t20220916\t24ade73c-98cf-XXXX-XXXX-cc7b867b3080");
file.AppendLine("K\t101\t162");
file.AppendLine("T\tEMP001\t110200");
file.AppendLine("T\tEMP002\t200000");
file.AppendLine("F\t2\t310200\t9999");
string FileToken = BatchFileUpload("xx34x5802-xxxx-abcd-c7xxxxz1ad9q", fl.ToString());

Processing deadlines

• All times in 24hr format.
• Action date is the date the transaction is processed on the recipient bank account.
• Business days are the days between -and including Monday to Friday but do not include public holidays and/or weekends.

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:

• 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) {
  // 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)

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

Load report trailer (occurs once – the last line in the report)

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.

Testing

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