Currently set to Index
Currently set to Follow

Overview

This document is intended as a guide for programmers designing remote systems which will interact with the NIWS Web Service (Netcash Integrated Web Service) / Netcash API.

Kindly adhere to the Netcash brand guidelines when developing.

 

Suggested Integration Process Flow


We recommend that you download the suggested API integration process flow document and keep it on hand while you develop.

Important

The Netcash API makes use of web services are WCF Soap based Web Services. Please familiarize yourself with the use of WCF Soap based Web Services before you attempt to use the Netcash API.

  1. Netcash makes use of system generated GUiD’s. You as Developer will require a Software Vendor Key GUiD, if you have an Independent Software Vendor (ISV) Agreement with Netcash – which must be valid and active. Speak to the Pay Now Specialist at Netcash for details.
    1.1. a Software Vendor Key (SVK) GUiD will record transactions processed via your System/Software/Infrastructure to the Netcash infrastructure for ISV Agreement purposes.
    1.2. a Service Key (SK) GUiD is specific to the respective Netcash service being used. It has various parameters which your client can configure relating to his/her Netcash service requirements.
  2. Your client’s Netcash Account must be in an ACTIVE state. (see NetConnector for validation of Service Keys and account status)
  3. You must have the list of Netcash services activated for your client with their respective Service Keys.
  4. You should use the ValidateServiceKey method in the niws_partner.svc web service to pre-validate your client’s Service Keys before they are stored in your system. Do NOT store any GUiD in your system if it does not pass the Netcash validation.
  5. Your client’s Service Keys need to be stored in an encrypted manner in your software for security purposes before the Netcash services can be accessed from your software. These Service Keys are called as “variables” by the respective Netcash service/module.
  6. Your client requires valid and active login credentials for the Netcash system for each user before they can access any Netcash service/s.
  7. Service Permissions need to be explicitly granted to the client’s user on the Netcash system before they will be able to access the service via the NetAccess.

Web Service Methods

The list of Netcash web service methods can be found here

What is NIWS?

The Netcash Integration Web Service (NIWS) is designed to provide remote systems with the same functionality which is available to clients on the Netcash website. The web service reveals methods which enable a software developer to automate access to a variety of Netcash services.

The web service uses a standard, generic file format called (NIF), Netcash Integrated File which allows the remote system to request various services without extensive reprogramming by the developer. The NIWS service combines and consolidates the functionality provided by all the existing web services. It also provides the option of sending multiple requests in a single file.

Responses Synchronous Services

The NIWS_Validation entry point offers a range of synchronous services. The calling system receives a response in the same session. Responses from the synchronous services do not need to be retrieved.

Advantages

  • Responses are returned by the web service, polling is not required. The web service can be used without supplying a postback URL.

Disadvantages

  • Not all Netcash products can be offered as synchronous web services.
  • Synchronous services are restricted to one transaction per call.
  • Files cannot be uploaded using the synchronous services.
  • Input data is restricted to specified parameters.
  • Responses differ in format due to the nature of the data returned.

Asynchronous Services

The NIWS_NIF entry point supports asynchronous services for file upload, thus allowing multiple transactions in a single call. Asynchronous services require a postback URL to which the responses can be returned. If a postback URL cannot be supplied, the calling system needs to poll in order to retrieve the responses.

Advantages

  • Most services offered by the synchronous services are also available using the asynchronous methods.
  • Batch-based uploads (e.g. Payments of Salaries) can only be offered as asynchronous services.
  • Asynchronous methods utilise the Netcash Integration File (NIF) format. NIF is a generic file format which can be adapted to all services without extensive reprogramming.
  • Input data is flexible and can be adapted to the end-user’s requirements.
  • Because they permit file uploads, asynchronous services allow multiple transactions to be processed in a single call.
  • Asynchronous services allow the end-user to determine when responses are collected.
  • Error handling parameters (e.g. jump errors and forward action date) can be set by the business user on the Netcash web site.
  • Both postback and polling are supported.
  • Even if a postback URL has been supplied, response files can still retrieved from the Netcash polling queue.

Disadvantages

  • Asynchronous services require polling or a postback URL to retrieve the responses.

What do you need?

The NIWS_NIF entry point supports asynchronous services for file upload, thus allowing multiple transactions in a single call. Asynchronous services require a postback URL to which the responses can be returned. If a postback URL cannot be supplied, the calling system needs to poll in order to retrieve the responses.

  • Developers should familiarise themselves with calling a web service and processing the return in their chosen development language.
  • The web service is only available to registered Netcash merchants. You need to ensure that the Netcash account you are using is activated.
  • Access to services is regulated by service specific keys which are issued by Netcash. You should ensure you have the correct service key for the service you wish to access.
  • You should ensure you have the latest version of the NIF file specification.
  • If you are utilising the postback responses, you need to create a handler to accept incoming posted responses.
    • ASPX page
    • ASHX handler
    • PHP page
    • Or any other type of endpoint that accepts an HTTP POST form.

Service keys

Service keys are GUIDs used to authenticate the calling system. Service keys are issued per service to a Netcash merchant account.

  • The service key must be valid.
  • The service key must be activated on the Netcash system.
  • The service must be active for the specified merchant account.
  • The merchant account must be active.
  • The service key must be valid for the instruction issued.

How to get a service key

  • From your Netcash Payment Advisor
    • Service keys can be issued by Netcash Merchant Account Super Users or you can contact your Netcash Payment Advisor for assistance.
  • Generate keys from the Netcash web site
    • Service Keys can also be created using the NetConnector pages on the merchant website.
  • Manage existing keys from the Netcash web site
    • The super user of the account can use the NetConnector services pages to activate or deactivate existing service keys to meet user requirements. The page can also be used to re-generate keys in the event that a current service key is compromised.

Note:

key will fail authentication.

Usage Accessing the web service

The web service entry points can be accessed via the following URLs:

Entry points and methods

The NIWS_Validation entry point offers a range of synchronous services. The calling system receives a response in the same session. Responses from the synchronous services do not need to be retrieved.

The following functions are available within the single NIWS web service:

Entry Point Type Method Description
NIWS_Validation Synchronous ValidateBankAccount Check Branch and CDV
Synchronous ValidateBranchCode Check branch
Synchronous GetBankList List of supported banks
Synchronous Get Bank List With Default Branch Code List of supported banks, including a default branch code if it exists
Synchronous Get Branch List List of branches for specified bank
NIWS_NIF Asynchronous Request Merchant statement Returns daily statement by date
Asynchronous RequestInterimMerchantStatement Returns interim statement for current date
Synchronous RequestActionDate Checks action date
Asynchronous BatchFileUpload All NIF format file uploads
Synchronous RequestFileUploadReport For polling for the upload reports
Asynchronous RequestCreditDataReport For polling for the result files
Synchronous RequestAVSReport For polling for the result files

Request string

Incoming web service calls are in the format: {Method}({Service key}, {parameters})

Example: public string BatchFileUpload(string ServiceKey, string File)

The service key in the input string authenticates the calling application and authorises access to the web service. Where a file is sent to the BatchFileUpload method, the header record of the file will contain the service key as well. The service key contained in the file will be used both for authentication and to indicate the service being accessed.

Retrieving Data Synchronous

  • Synchronous services respond in the same session.
  • Only single requests can be sent to the synchronous methods
  • For a description of the responses, refer to the individual web service documentation.

Asynchronous

Responses from asynchronous services can be accessed either by polling for a result or by supplying a postback URL to which the result can be sent.

Polling

The web service entry points can be accessed via the following URLs:

Where no postback URL has been supplied, the remote system should poll the Netcash queue to retrieve data.

The asynchronous web service methods will return a file token which is used by the calling system to retrieve the load report and/or data file. A file token is a GUID generated by the web service to uniquely identify the report to be retrieved. Requests are file-based and may contain multiple transactions therefore responses are not immediate. If the request passes initial validation, the NIWS web service responds with a file token. The remote system uses the file token to request results from the polling queue. If the load report or response file is not yet available, the web service returns “FILE NOT READY”

Upload Report

The file token is sent to the NIWS_NIF RequestFileUploadReport method to retrieve the load report. public string RequestFileUploadReport(string ServiceKey, string FileToken)

Risk Reports

Use the same file token and send the request to NIWS_NIF RequestCreditDataReport method to retrieve the base64 encoded PDF file. public string RequestCreditDataReport(string ServiceKey, string FileToken)

Account Verification Report

Use the same file token and send the request to NIWS_NIF RequestAVSReport method to retrieve the string array. public string RequestAVSReport(string ServiceKey, string FileToken)

Postback response

Where the remote system has supplied a postback URL, both the load report and, where applicable, the requested report will be posted back to the supplied URL.The POST parameters are as follows:

Entry Point Polling Id File Account reference
uploadreport string tab delimited No
creditdatareport string base64 encoded Yes
avsdatareport string tab delimited No

The remote system processes the response and prints OK to the URL to indicate that the response has been received successfully. The Netcash system will continue to retry the postback until the remote system responds with “OK”.

The first two retries will be immediate, with a 30 second delay between retries. Subsequent retries will occur at 10 minute intervals until the maximum of 10 retries has been reached.

Note: even when a postback URL has been supplied, the load report and requested reports will still be placed in the polling queue. The remote system can still use the supplied file token to retrieve the reports.

NIF Response files

The responses in this chapter apply to the asynchronous services. For responses from the synchronous services refer to the web service specific documentation. The web service has a three tiered response structure.

  • Web service validation, which checks the web service call and responds with an error code.
  • File parsing, which validates the content of the file string and responds in the load report.
  • Email confirmation, which generates automatic emails containing the same information contained in the load report.

These responses are described in detail below.

Input Field Legend

Please note that some fields are no longer supported or not relevant to the method you are using. Contact the author to inquire about a specific field if such is not mentioned in the document you are integrating.

Field Name

Alpha/ Numeric

Value
101 Account reference

AN22

The unique account reference that you will use in the future to address this client
Minimum 2 Maximum 22 characters
102 Account name

AN20

The name of your client’s account on the Netcash system (Typically your client’s name)
103 Account active

N1

0 = Inactive 1 = Active
104 Delete this account

N1

0 = Don’t delete 1 = Delete
103 Beneficiary active

N1

0 = Inactive 1 = Active
104 Delete this beneficiary

N1

0 = Don’t delete 1 = Delete
105 Netcash account number

N11

The account number of the merchant’s Netcash account
Field Name

Alpha/ Numeric

Value
110 IsConsumer

N1

0 = Company 1 = Individual
111 ID number

N13

The South African identity number which is to be checked. Must be 13 digits.
112 Passport number

AN

The passport number or foreign ID number which is used in Consumer Africa enquiries.
113 Surname

A15

Details to be used for Consumer enquiry
114 First name

A15

Details to be used for Consumer enquiry
115 Maiden name A15 Details to be used for Consumer enquiry
116 Other name

A15

Details to be used for Consumer enquiry
117 Date of birth

N8

CCYYMMDD
118 Gender

A1

M or F
119 Title

N1

1 = Mr
2 = Mrs
3 = Ms
4 = Miss
5 = Dr
6 = Prof
Field Name

Alpha/ Numeric

Value
121 Trading name

AN

The name of the business to be checked.
122 Registration number

AN

Entity registration number
123 Registered name

AN

Entity name
124 VAT Number

N

Entity VAT number
125 Legal Entity

N2

  1. Registered company (Pty) Ltd
  2. Close corporation
  3. Section 21 company
  4. Non-profit organization
  5. Trust
  6. Co-operative
  7. Sole proprietor
  8. Partnership
  9. Educational institution
  10. Unknown/Other
  11. Association
  12. Incorporation
Field Name

Alpha/ Numeric

Value
126 AVS check number

AN13

This field contains the number linked to a bank account. This field can contain an SA Identity number, Foreign ID number, Passport number or Business registration number.
127 Is ID number

AN13

0 = Not an SA ID number
1 = AVS check number is an SA ID number (Netcash will automatically validate the number before sending it to the bank)
Field Name

Alpha/ Numeric

Value
128 Designation

A10

Director, Member, Trustee, Sole proprietor, etc
129 Job description

A20

Manager, Owner, Bookkeeper, etc.
Field Name

Alpha/ Numeric

Value
131 Banking detail type

N1

1 = bank account
2 = credit card
3 = pre-defined beneficiary

Use these fields if field 131 is set to 1 (bank account) All fields 132- 136 are mandatory

132 Bank account name

AN15

The name of the bank account to be debited or credited (may differ to the name in field 102)
133 Bank account type

N1

1 = Current / Checking
2 = Savings
3 = Transmission
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.
135 Filler

N1

0
136 Bank account number

N11

The homing bank account number. May not exceed 11 digits.

Use these fields if field 131 is set to 2 (credit card) All fields 132- 136 are mandatory

132 Credit card holder

AN20

The card holder name as it appears on the front of the card
133 Credit card type

N1

1 = MasterCard 2 = Visa
134 Expiry month

N2

2 digit month (MM) include leading zero
135 Expiry year

N4

4 digit year (CCYY)
136 Credit card token

AN36

PCI Token generated for credit card processing
137 Masked credit card number First 4 and last 4 digits of card number – middle 8 digits replaced with zeroes.
138 Budget

A1

Y = Display budget option in card details page
N = Do not display budget option in card details page

Use these fields if field 131 is set to 3 (Pre-defined beneficiary) All fields 132- 136 are mandatory

132 Filler

N1

0
133 Bank account type

N1

9
134 Filler

N1

0
135 Filler

N1

0
136 Pre-defined beneficiary code

AN8

The Netcash beneficiary code.
Field Name

Alpha/ Numeric

Value
161 Default debit amount

N10

The default amount to be set in the masterfile (in cents)
162 Debit amount

N10

The amount of this debit order (in cents)
161 Default payment amount

N10

The default amount to be set in the beneficiary masterfile (in cents)
162 Payment amount

N10

The amount of this payment (in cents)
163 Credit amount

N10

The credit amount (in cents)
164 Credit terms

AN2

Credit term code
165 Ignore invoice amount

AN1

Y = call for amount to be paid. N = use the value contained in the barcode
Field Name

Alpha/ Numeric

Value
201 Email address

AN

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 mobile number to be used for SMS notifications

NOTE: Only South African mobile numbers are accepted

(a) Via a web service method, the mobile number must start with South African country code ’27’ (EG. 27812345678)
(b) Via a form post (eCommerce service), the mobile number must start with a ‘0’ (EG. 0812345678)

203 Postback URL

AN

The URL to be used for responses
(The “//:” “@” and “.” symbols are allowed in this field)
204 Report image URL

AN

The URL to which the report is to be sent
Field Name

Alpha/ Numeric

Value
231 Default NAEDO tracking days

N

This value will be inserted into the masterfile as the default for the client.
232 NAEDO tracking days

N1

1 = No Tracking
2 = 1 Day
3 = 3 Day
4 = 7 Day
5 = 14 Day
6 = 21 Day
7 = 32 Day
Field Name

Alpha/ Numeric

Value
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.
(Maximum 20 characters)
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.
(Maximum 20 characters)
253 Unique Pay Now reference (p2)

AN50

This is a unique reference that you will assign to each transaction. This reference should only ever be USED ONCE.
254 Description of goods (p3)

AN50

The description of the goods sent for payment for your internal reference
255 Send SMS for Pay Now Invoice (M12)

A1

Y/N – if this field is set to yes and 202 has valid data, a payment instruction SMS will be sent to the mobile number
256 Send Email for Pay Now Invoice (M13)

A1

Y/N – if this field is set to yes and 201 has valid data, a payment instruction Email will be sent to the Email address
257 Request credit card subscription
token for Pay Now Invoice (M14)

A5

true/false (case sensitive) default = ‘false’. Insert ‘true’ to request a token returned in postback
258 Credit card token (M15)

AN36

Credit card token for subscription cards
259 Subscription indicator (M16) N1 0 = No subscription
1 = Log as a subscription payment
260 Subscription cycle (M17) N Number of cycles for subscription payment
261 Subscription frequency (M18) N 1          Monthly
2          Weekly
3          Bi-weekly
4          Quarterly
5          Six monthly
6          Annually
262 Subscription start date (M19) N8 CCYYMMDD
263 Subscription recurring amount (M20) N Recurring amount (can differ from initiating 3D Secure  payment)
264 Split payment indicator (M21) N 0 = Not split
1 = Split payment
265 Split target account (M22) N11 Account number of Netcash target account
266 Split amount (M23) N Fixed value to be payed to target account
267 Split percentage (M24) N Percentage of total value to be payed to target account
268 Split minimum amount (M25) N Minimum payment to target account
269 Split maximum amount (M26) N Maximum payment to target account
Field Name

Alpha/ Numeric

Value
281 Debit masterfile group

AN2

Links this client to an existing group.
Validation will fail if the group does not exist
281 Payment beneficiary group

AN2

Links this beneficiary to an existing group
Validation will fail if the group does not exist
Field Name

Alpha/ Numeric

Value
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)
304 Additional Accept/Decline text (m10)

AN100

Any text sent in this parameter is returned to the Accept and Decline return URL’s. This is usually used with basket products like OSCommerce and VirtueMart.
311 Field 1

AN50

Custom User Defined data (Extra data you would like added to your client’s master file record)
312 Field 2

AN50

Custom User Defined data (Extra data you would like added to your client’s master file record)
313 Field 3

AN50

Custom User Defined data (Extra data you would like added to your client’s master file record)
314 Field 4

AN50

Custom User Defined data (Extra data you would like added to your client’s master file record)
315 Field 5

AN50

Custom User Defined data (Extra data you would like added to your client’s master file record)
316 Field 6

AN50

Custom User Defined data (Extra data you would like added to your client’s master file record)
317 Field 7

AN50

Custom User Defined data (Extra data you would like added to your client’s master file record)
318 Field 8

AN50

Custom User Defined data (Extra data you would like added to your client’s master file record)
319 Field 9

AN50

Custom User Defined data (Extra data you would like added to your client’s master file record)
Field Name

Alpha/ Numeric

Value
321 Physical address line 1

AN50

min:2, max:50
322 Physical address line 2

AN50

min:2, max:50
323 Physical address line 3

AN50

min:2, max:50
324 Physical suburb AN50 min:2, max:50
325 Physical city

AN50

min:2, max:50
326 Physical postal code

N4

327 Physical province

N1

1 = Western Cape
2 = Gauteng
3 = Eastern Cape
4 = Free State
5 = KwaZulu Natal
6 = Limpopo
7 = Mpumalanga
8 = Northern Cape
9 = North West
331 Postal address line 1

AN50

min:2, max:50
332 Postal address line 2 AN50 min:2, max:50
333 Postal address line 3

AN50

min:2, max:50
334 Postal suburb

AN50

min:2, max:50
335 Postal city AN50 min:2, max:50
336 Postal code

N4

337 Postal province

N1

1 = Western Cape
2 = Gauteng
3 = Eastern Cape
4 = Free State
5 = KwaZulu Natal
6 = Limpopo
7 = Mpumalanga
8 = Northern Cape
9 = North West
Field Name

Alpha/ Numeric

Value
341 Phone number

N11

Include dialing codes EG: 27117822349
342 Fax number

N11

Include dialing codes EG: 27117822349
Field Name

Alpha/ Numeric

Value
401 Default Action

A1

A = Add
R = Remove
U = Update
402 Default type
403 Effective date

N8

CCYYMMDD The date from which the Default status is effective.
404 Account number

AN13

The account which was defaulted on.
405 Amount owed

N10

The default amount (in cents)
Field Name

Alpha/ Numeric

Value
421 Trade name 1

AN50

The name of the company to be contacted for reference
422 Trade contact 1 AN50 The name of the person within the company to be contacted for reference
423 Trade telephone 1

N11

The phone number of the company to be contacted.
Include dialling codes EG: 27117822349
424 Trade name 2

AN50

The name of the company to be contacted for reference
425 Trade contact 2

AN50

The name of the person within the company to be contacted
426 Trade telephone 2

N11

The phone number of the company to be contacted
Include dialling codes EG: 27117822349
427 Trade name 3 AN50 The name of the company to be contacted for reference
428 Trade contact 3

AN50

The name of the person within the company to be contacted
429 Trade telephone 3

N11

The phone number of the company to be contacted
Include dialling codes EG: 27117822349
Field Name

Alpha/ Numeric

Value
441 Subject telephone 1

N11

The phone number of the person to be contacted
Include dialling codes EG: 27117822349
442 Subject telephone 2

AN

The phone number of the person to be contacted
Include dialling codes EG: 27117822349
Field Name

Alpha/ Numeric

Value
450 Reason code

N2

The reason for which an enquiry was requested. (Required by credit bureaus)
See table below:
Field Name

Alpha/ Numeric

Value
501 Debit order collections

N1

0 = not requested
1 = requested
502 Creditor payments

N1

0 = not requested
1 = requested
503 Salary payments

N1

0 = not requested
1 = requested
504 Risk reports

N1

0 = not requested
1 = requested
505 Pay Now

N1

0 = not requested
1 = requested
Activate Pay Now Request for Debit Order unpaids
Field Name

Alpha/ Numeric

Value
509 Resubmit unpaids via Pay Now

N1

0 = not requested
1 = requested
Note: this field can not be used for Masterpass or Visa checkout as no token is returned for those transactions
Field Name

Alpha/ Numeric

Value
510 Account stage

A

“Opportunity”
“Registration”
“Active”
“Closed”
511 Account status

A

“Inactive opportunity”
“Lead opportunity”
“Active opportunity”
“Busy registering”
“Registration complete”
“Registration verification”
“Active pending”
“Active”
“Suspended”
“Closed”
“Unused account”
Field Name

Alpha/ Numeric

Value
521 Software vendor key

AN36

The software vendor key (GUID) issued by Netcash to the vendor
522 Software account number

AN25

The account number of the merchant on the software vendor’s system
523 Software serial number

AN30

The serial number of the vendor’s software licensed to the merchant
524 Notes

AN199

OPCO name, Software serial number, Software account number
Triple space separated.
525 Activate now

N1

1 = Log active opportunity
526 Account manager id

N

For internal Netcash use only.
This is the database id of the account manager to whom the lead is assigned
527 Channel partner indicator

N1

Does the lead originate from a Sage Pastel channel partner (0 = No / 1 = Yes)
Default value = 0
528 Employee bracket

N10

Sage VIP Employee bracket
Field Name

Alpha/ Numeric

Value
530 Debit frequency

N1

1 = Monthly
2 = Bi-monthly
3 = Three monthly
4 = Six monthly
5 = Annually
6 = Weekly
7 = Bi-weekly
531 Commencement month

N2

MM
532 Commencement day (debit day options)

AN4

01 – 31 or Last Day Of Month Forward slash separated list.
EG: 05/15/25/LDOM
533 December debit day

AN4

01 – 31 or Last Day Of Month Forward slash separated list. EG: 05/15/25/LDOM
534 Agreement date CCYYMMDD
535 Agreement reference number

AN50

Agreement reference
536 Cancellation notice period

N2

01 – 20
537 Allow variable debit amounts

N1

0 = Do not allow variable amounts
1 = Allow variable amounts
538 Request AVS

N1

0 = Do not run account verification check
1 = Run account verification check
539 Additional clauses

AN

Additional clauses to be included the mandate
540 Send mandate

N1

0 = Do not automatically send mandate for signature
1 = Automatically send valid mandates to the account holder for signature
541 Debit day on public holiday or weekend

N1

If the debit day falls on a public holiday or weekend the client will be debited
0 = Preceding ordinary business day
1 = Very next ordinary business day
Field Name

Alpha/ Numeric

Value
901 Reserved Internal use only (CD product ID)
902 Reserved Internal use only (Warehouse report ID)

Web service validation

The NIWS web service performs initial validation on the incoming web service method call. If the validation fails the 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.

This validation takes place before the NIF file is checked. If an error code is returned, the web service has not yet begun to parse the file data.

File Parsing

If the request is successfully validated, the file contained in the string is parsed. Responses are returned in the load report 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 Type Value
Record identifier AN8 ###BEGIN
Batch name AN SUCCESSFUL / UNSUCCESSFUL / SUCCESSFUL WITH ERRORS
Result of upload A13 100
Start time of report AN8 HH:MM AM/PM

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

Field Type Value
Account reference AN58 Acc Ref :{your account reference}
Line number AN Line :{line in your file where error was found}
Error message A13 The error message

OR

Field Type Value
Record identifier AN8 ###ERROR
Error message AN The error message

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

Field Type Value
Record identifier AN6 ###END
End time of report AN8 HH:MM AM/PM

Email confirmation

In addition to the load report which is returned to the calling application, the NIWS system also sends an email confirmation to the email address which is registered against the Netcash service key. As with service keys, email addresses can be managed by Netcash administrators on request or by a user on the merchant web site. The email could be used to inform business users of the outcome of a submitted batch. Only a single email address is captured, if the merchant requires the mail to be sent to multiple users, the onus is on the merchant to set up an email distribution list on their system and supply Netcash with the email address of the distribution list. The format of the email confirmation mirrors the load report format in that it contains the BEGIN and END tags so that it can be machine readable. Due to the unreliability of mail servers, it is not recommended that developers rely on the email confirmation but rather use the load report to determine the outcome of a request.

NIF Error handling

Three different types of errors can be returned during file parsing:

  • Data errors
  • File structure errors
  • System errors

These errors will be reported in the load report file structure. The Load report message format (between the header and trailer records) differs slightly between Data errors and Structure or System errors.

Data errors
Data errors refer to lines in a file which has passed structural validation. The load report will contain the line(s) which failed validation indicating the account reference and the line in the file where the error was detected.

###BEGIN    My Test Batch SUCCESSFUL WITH ERRORS 03:45 PM
Acc Ref:    EMP001 Line :3 Invalid account number
###END      03:45 PM

Example

File structure errors
If any structural errors are detected the file is rejected before any transaction records are processed. In this case the account reference and line number fields will be replaced with an error tag indicating that no records in the file were parsed.

Example

###BEGIN    My Test Batch UNSUCCESSFUL 03:45 PM
###ERROR    File is malformed, header record could not be identified
###END      03:45 PM

System errors
System errors which cause the web service to abort the parsing will be reported in the same way, using the error tag.

Example

###BEGIN    My Test Batch UNSUCCESSFUL 03:45 PM
###ERROR    A system error has occurred. Contact Netcash (ZA) support
###END      03:45 PM

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.

Version 2020.1

Copyright © 2020 Netcash (PTY) Ltd