Programmers Guide

Before you start

Please download the suggested API integration process flow document and use it as a reference when developing.

Web Service Methods

The list of Netcash web service methods can be found here.

Quick Start Guides

Quick Start Guides will help you understand our services and get you started.

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. 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.
      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 their Netcash service requirements.
      It is IMPORTANT that you familiarize yourself with Service Keys and their function – read more here
   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.
   8. Only use standard A & AN ASCII characters – our system has been programmed to remove all characters that could possibly be used for SQL injection as a security measure. Thus, no “ " ’ & % , / \ * ^ $ ± § ` ~ etc. characters will be allowed and simply be replaced with a space un upload. To avoid data being truncated or references not being reconciled, please ensure the necessary changes are applied in your system/s.
   9. Where required, a ‘batch name’ indicator must be inserted in the header record. It is used to identify the batch from the load report. This value/indicator is an AN50 value and only standard A & AN ASCII characters are allowed.

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.

Response: 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.

Postback Frequencies

• Postbacks occur up to seven (7) times including the first attempt
• There are synchronous and asynchronous postbacks. The system sends a notify postback each time it records a transaction.
• In total, the retry window is roughly 15 minutes. The time intervals are as follows:
  • 1 = 10 seconds
  • 2 = 30 seconds
  • 3 = 1 minute
  • 4 = 2 minutes
  • 5 = 4 minutes
  • 6 = 8 minutes
• The remote system cannot retrieve the postback data once the retries have expired. Users may request a manual resend from support@netcash.co.za

Response: 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. Read more on the postback frequencies here

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.

It is IMPORTANT that you familiarize yourself with Service Keys and their function – read more here

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

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:

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

DebiCheck Specific Indicators

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

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

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

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

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

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

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

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

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.

Support

If you require any assistance contact our technical support team

Testing

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