DebiCheck Debit Orders

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

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

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. It does not replace Same-day and Dated debit orders but can be used as an alternative. By using DebiCheck you can obtain authentication, benefit from the preferential presentation of the debit and track the bank account over a selected period.

Read more about DebiCheck contract types and authentication options here

See the service overview here.

Click here for information on the DebiCheck Authentication – without using the Netcash eMandates.

Technical Information

NIWS_NIF is an asynchronous web service which exposes multiple methods. The method BatchFileUpload allows an external system to submit a batch file of DebiCheck Debit Orders 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 list of unpaid transaction codes

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 C74EXXX5-5499-4663-85FB-2A6XXXXFB9EF 1 DebiCheck 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.

Example

K 101 162 232 249 301 302 303

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.

Example:  T Acc001 AccName001 1 BankAccountName001 1 470010 0 25000000000 100

Mandatory fields

The fields indicated by are mandatory for the specified instruction.

Key	Field name	Mandatory
101	Account reference
249	DebiCheck mandate reference
232	DebiCheck tracking days

Optional fields

Additional data pertinent to the Debit order.

If field 162 (Debit amount) is not specified, the amount stipulated in the mandate will be debited to the account.

Specify any optional fields included in the transaction records in the key record (K).

Transaction fields

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

Example of input file

H	C74EXXX5-5499-4663-85FB-2A6XXXXFB9EF	1	DebiCheck	My	Test	Batch	20131204	24ade73c-98cf-XXXX-XXXX-cc7b867b3080
K	101	162	232	249	301	302	303
T	AB001123456	150000	9	NC00000021	Jones	Sept	Inv123456
T	CD001123457	17500	3	NC00000134	Brown	Sept	Inv123457
F	2	167500	9999

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

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

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

Input

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:

<system.webServer>
    <httpProtocol>
        <customHeaders>
            <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="IDC DSP COR ADM DEVi TAIi PSA PSD IVAi IVDi CONi HIS OUR IND CNT"'
            />
            <add name="X-UA-Compatible" value="IE=Edge" />
        </customHeaders> 
    </httpProtocol>
</system.webServer>

Creating the call

Ensure that you add a postback url PCI Vault screen on your system frontend, otherwise you will get a message stating that you do not have access to the page.
To get the PCI Vault service key required to use this method you need to log in into the merchant site;

1. click on Account Profile
2. open NetConnector
3. 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="https://cde.netcash.co.za/Site/TokeniseCardExternal.aspx" 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">
</form>

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

Responses

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

Successful = 1
Token = Vault token for card
CardHolderName
MaskedCardNumber
ExpMonth
ExpYear
Extra1
Extra2
Extra3

If tokenisation failed, the following fields will be returned:

Successful = 0
Extra1
Extra2
Extra3

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.

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