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 outbound Payment files to a Netcash account and then to the National Payment System. Netcash’s outbound payments are similar to internet banking payments with the added benefit of

  • faster clearing times – all Netcash payments clear at midnight of the Action date. Thus, no interbank waiting time as all beneficiaries are paid simultaneously; irrespective of the bank, branch -or account type.
  • reduced -and fixed transaction charges – Netcash payments are billed at one (1) fixed transaction charge irrespective of bank, branch, or account type unlike most commercial banks do.

Contact Netcash for more information.

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 salary -or creditor payments for processing.

Compact Upload File Specification

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

The Service

Object Name Description
Method BatchFileUpload

Parameter:

  • ServiceKey (salary or creditor)
  • File
Method RequestFileUploadReport

Parameter:

  • ServiceKey (salary or creditor)
  • FileToken (received on file upload if successful)

Once you have built the file call:

Input

Requests to the web service are sent as strings

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:

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.

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 Name Type Value
1 Record Identifier AN H
2 Service Key AN Salary/Creditor Payment 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 Salary/Creditor Payment Service Key
Version “1” – This is the Netcash version of the file specification
Instruction Update – update the master file without loading a batch
PaySalaries – Sameday salary batch upload (read more about payment types here)
RTCSalaries – Realtime salary batch upload
DatedSalaries – Dated salary batch upload
Realtime – Sameday creditor batch upload
DatedPayments – Dated creditor batch upload
RTCPayments – Realtime creditor 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 to be made to the beneficiary.
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)

Example

H C74EXXX5-5499-4663-85FB-2A6XXXXFB9EF 1 PaySalaries 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 102 131 132 133 134 135 136 162 252

Mandatory fields

The fields indicated by are mandatory for the specified instruction.

See the full API key legend for value requirements

Key Field name Update PaySalaries DatedSalaries
Realtime
DatedPayments
101 Account reference
102 Account name
103 Beneficiary active
104 Delete beneficiary
131 Banking detail type
132 Bank account name
133 Bank account type
134 Branch code
135 Filler
136 Bank account number
161 Default amount
162 Amount
201 Email address
202 Mobile number
251 Default Beneficiary statement reference
252 Beneficiary statement reference
281 Payment recipient / beneficiary group
301 Extra 1
302 Extra 2
303 Extra 3

Optional fields

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

Optional fields

If the 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 account reference that you will use in the future to address this client
(Minimum 2; Maximum 22)
102 Account name AN25 The name of your client’s account on the Netcash system (Typically your client’s name)
(Minimum 2; Maximum 25)
103 Beneficiary active N 0 = Inactive
1 = Active
104 Delete this beneficiary N 0 = Don’t delete
1 = Delete
131 Banking detail type N1 1 = bank account
132 Bank account name
(account holder name)
AN30 The name of the bank account to be debited or credited (may differ to the name in field 102)
(Maximum 30 characters)
133 Bank account type N1 1 = Current / Checking
2 = Savings
3 = Transmission
9 = Public Recipient / Beneficiary
134 Bank account branch N6 The branch code of the homing account.
This field MUST be 6 digits. Pre-fill with zeroes if less than 6.
For Public Recipient / Beneficiary payments use “000000”
135 Filler N1 0
136 Bank account number N11 The homing bank account number. May not exceed 11 digits.
For Public Beneficiary payments use Public Recipient / Beneficiary reference number
161 Default payment amount N The default amount to be set in the masterfile (in cents)
162 Payment amount N The amount of this payment (in cents)
201 Email address AN50 This is the email address used to notify your client of the debit order.
(The “@” and “.” symbols are allowed in this field)
202 Mobile number N11 The cell number to be used for SMS notifications Include dialling code
EG: 27827822349
NOTE: cell numbers which are not correctly formatted will be ignored and not updated to the masterfile
251 Default Beneficiary
statement reference
AN20 This field is the statement reference that appears on the client’s bank statement. This field can only be used when updating the beneficiary masterfile.
(Minimum 4; Maximum 20 characters)
Note: only the first 12 characters will appear on the beneficiary statement
252 Beneficiary
statement reference
AN20 This field is the statement reference that appears on the client’s bank statement. This field can only be used when making payments.
(Minimum 4; Maximum 20 characters)
Note: only the first 12 characters will appear on the beneficiary statement
281 Payment beneficiary group AN50 Links this beneficiary to an existing group
Validation will fail if the group indicated does not exist.
301 Extra 1 AN999 Custom User-defined data (Extra data you want returned for your internal system use)
302 Extra 2 AN49 Custom User-defined data (Extra data you want returned for your internal system use)
303 Extra 3 AN49 Custom User-defined data (Extra data you want returned for your internal system use)

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

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

 

Example

F 2 0 9999

Example of input file

 

H 78e30d1e-aa36-0000-XXXX-dcd68866XXXX 1 DatedSalaries Batch_Name 20131204 24ade73c-98cf-XXXX-XXXX-cc7b867b3080
K 101 102 131 132 133 134 135 136 162 252
T EMP001 A Employee 1 AB Employee 1 632005 0 40600000004 110200 Dated sal test
T EMP002 X Employee 1 X Employee 2 198765 0 2060000001 200000 Dated sal test
F 2 310200 9999

Example of string file (C#)

 

string fl =
"H\t78e30d1e-aa36-0000-XXXX-dcd68866XXXX\t1\tDatedSalaries\tBatch_Name\t20131204\t24ade73c-98cf-XXXX-XXXX-cc7b867b3080" +
Environment.NewLine +
"K\t101\t102\t131\t132\t133\t134\t135\t136\t162\t252" +
Environment.NewLine +
"T\tEMP001\tA Employee\t1\tAB Employee\t1\t632005\t0\t40600000004\t110200\tDated sal test" +
Environment.NewLine +
"T\tEMP002\tX Employee\t1\tX Employee\t2\t198765\t0\t2060000001\t200000\tDated sal test" +
Environment.NewLine + "F\t2\t310200\t9999";
string FileToken = BatchFileUpload("78e30d1e-aa36-0000-XXXX-dcd68866XXXX", fl);

Processing deadlines

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

 

Same day payments Dated payments Real-Time payments
Must be loaded -and authorized
on Netcash before
12:59 on the action date 12:59 one (1) business day prior to action date 08h30 to 15h30 on the payment day for amounts up to R5 000 000.00
15h30 to 16h30 on the payment day for amounts up to R250 000.00
Payment cleared
in the beneficiary bank account
  • Funds will be available in the beneficiary bank account the next banking day, value-dated for the (same day) payment date.
  • The processing cut-off time is 12h59 on the payment day.
  • Valid payment dates are Monday to Friday (excluding public holidays).
All payments are reflected in all beneficiary bank accounts at the same time -on the action date; irrespective of bank, branch -or account type. This service is recommended for Salary and/or Wage payments.
Funding of Netcash account By 12:59 on action date By 12:59 one (1) business day before action date Amounts over R250 000 authorised between 15h30 to 16h30 will only be processed the next working day
Processing days
(excludes public holidays)
Monday to Friday 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

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

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

 

Field

Name

Type

Value

1

Record identifier

AN8

###BEGIN

2

Batch name

AN

{your batch name}

3

Result of upload

A13

SUCCESSFUL / UNSUCCESSFUL / SUCCESSFUL WITH ERRORS

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

Unique reference

AN25

The unique reference you supplied in (p2)

2

Line number

AN

Line :{line in your file where error was found}

3

Error message

AN

The error message

OR

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

 

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

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

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.