- Home
- /
- Outbound Payments
- /
- Salary & Creditor Payments
Salary & Creditor Payments
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 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 your Netcash Payments Advisor for more information.
See the service overview here.
QuickStart Guides
We have developed some Quick Start Guides to help you understand this service and to help you get started.
Programmers Guide
To start, refer our Programmers guide for more detail on how to apply the required methodology in this document.
Please ensure that the settings for Developers are correctly set before you proceed with the implementation below specification.
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:
|
Method | RequestFileUploadReport |
Parameter:
|
Once you have built the file call:
- Web service: https://ws.netcash.co.za/NIWS/niws_nif.svc
- Method: BatchFileUpload
- Service key: Salary payments service key or Creditor payments service key
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 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
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 | Name | Type | Value |
---|---|---|---|
1 | Record Identifier | AN | H |
2 | Service Key | AN | Salary Payments Service Key / Creditor Payments 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 payments service key OR Creditor payments 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 (ideal for bonus or once off payments where the time the recipient receives the funds is not important) DatedSalaries – Dated salary batch upload (ideal for salary / wage payments) Realtime – Sameday creditor batch upload (ideal for supplier or creditor payments) DatedPayments – Dated creditor batch upload (ideal for once off payments where the time the recipient receives the funds is not important) 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 Salary 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 102 131 132 133 134 135 136 162 252
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 AccName001 1 BankAccountName001 1 470010 0 21000000000 300 Wages
Mandatory field
The fields indicated by is 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 *requirement | ||
251 | Default Beneficiary statement reference | ![]() |
|
252 | Beneficiary statement reference | ![]() |
|
281 | Payment beneficiary group | ||
301 | Extra 1 | ||
302 | Extra 2 | ||
303 | Extra 3 |
Optional fields
If the optional fields are to be included in the transaction records, they must be specified in the key record (K).
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 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 | 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. |
Examples
F 2 0 9999
Example of input file
H C74EXXX5-5499-4663-85FB-2A6XXXXFB9EF 1 DatedSalaries My Salary Batch 20131204 24ade73c-98cf-47b3-99be-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\tC74EXXX5-5499-4663-85FB-2A6XXXXFB9EF\t1\tDatedSalaries\tMy Salary Batch\t20131204\t24ade73c-98cf-47b3-99be-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.
- The action date is the date the transaction is processed to the recipient’s bank account.
- TIP: See request action date web service
- Business days are the days between -and including Monday to Friday but does not include public holidays and/or weekends.
Same day payments | Dated 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 |
Payment cleared in the beneficiary bank account |
FNB account holders will see value after 15h00 on the action date. NON-FNB account holders see value one (1) calendar day after the action date backdated to the action date (same day service value) |
All payments reflect in all beneficiary bank accounts at the same time -on the action date; irrespective of bank, branch -or the 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 prior to action date |
Processing days (excludes public holidays) |
Monday to Friday | Monday to Saturday |
Retrieving the Load Report
- Postback option: you have activated the postback option in your NetConnector profile, the load report is automatically posted back to the URL you supplied.
- Polling option: (recommended)
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: Salary payments service key or Creditor payments 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)
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 | Account reference | AN58 | Acc Ref :{your account reference} |
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 SALARY BATCH SUCCESSFUL 01:59 PM R1.00 20160410 ###END 01:59 PM
Upload report example (successful with errors):
###BEGIN MY SALARY BATCH SUCCESSFUL WITH ERRORS 01:29 PM R1.00 20160410 Acc Ref :XI001 Line :3 Account details could not be validated. Please check the fields Bank account type, Branch code & Account number. Acc Ref :XI001 Line :3 Bank account number has incorrect length (min 4, max 11 characters) Acc Ref :HCOS01 Line :5 Beneficiary statement reference has incorrect length (min 4, max 20 characters) Acc Ref :HCOZ01 Line :6 Beneficiary statement reference has incorrect length (min 4, max 20 characters) ###END 01:29 PM
Upload report example (unsuccessful):
###BEGIN MY SALARY BATCH UNSUCCESSFUL 01:23 PM R1.00 20160410 ###ERROR: A system error occurred. Please contact Netcash R0.00 20160410 ###END 01:23 PM
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 (ZA) system. The web service will return all batches, whether they were uploaded via the web service -or manually created via the Netcash (ZA) web site.
Testing
See Testing section for more details. If you require any integration assistance contact our technical support team
Version 2020.1
Copyright © 2022 Netcash (PTY) Ltd