Payment Refunds

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

The Netcash web service ‘NIWS_NIF’ sends batched files of previously settled Pay Now Credit Card transaction ID’s for refund. ^{*see note}

Data submitted in the file will be displayed on the Merchant site for authorisation by a user before they are submitted to the credit card switch for a refund

The service is asynchronous and requires polling or postback to retrieve the load report:

• BatchFileUpload (NIF file containing a list of transaction Ids and refund amounts)
• RequestFileUploadReport (Returns the result of the NIF file upload including any errors encountered while parsing the file)

Contact Netcash for more information.

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 transactions to be refunded.

Once you have built the file call:

Web service: https://ws.netcash.co.za/niws/niws_nif.svc

• Method: BatchFileUpload
• Service key: Pay Now service key

Input

Requests to the web service are sent as strings

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. These fields 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, being the first record in the file.

Record Structure

Field explanations

Example

H C74EF975-aa36-0000-XXXX-dcd68866XXXX 1 CreditCardRefund Refund batch 20201030 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.

Example

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

IMPORTANT:

1. The transaction ID is the Netcash statement transaction ID of the original Pay Now transaction to be refunded.
2. You may refund a partial amount or full amount value for the transaction, but the refund amount may not exceed the original transaction value on the Netcash Statement.
3. ALL refunds submitted via NIWS_NIF will require manual authorisation by the user before the transaction/s will be processed.

Record structure

 Example

T 100235689 15000

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 1 15000 9999

Example of input file

H C74EF975-aa36-0000-XXXX-dcd68866XXXX 1 CreditCardRefund Refund batch 20201030 24ade73c-98cf-47b3-99be-cc7b867b3080
K 270 162
T 100235689 15000
F 1 15000 9999

Example of string file (C#)

string fl =
"H\C74EF975-aa36-0000-XXXX-dcd68866XXXX\t1\tCreditCardRefund\tRefund Batch\t20131204\t24ade73c-98cf-XXXX-XXXX-cc7b867b3080" +
Environment.NewLine +
"K\t270\t162" +
Environment.NewLine +
"T\t100235689\t15000" +
Environment.NewLine + "F\t2\t15000\t9999";
string FileToken = BatchFileUpload("78e30d1e-aa36-0000-XXXX-dcd68866XXXX", fl);

See note regarding the processing of refunds

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

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: Pay Now Service Key

Requests to the web service are sent as strings

Example:

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)

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 :100235689 Line :3 Invalid Amount
###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

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.

Testing

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