Start

Introduction

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

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.
      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  [ A-Z a-z 0-9 - _ . ( ) : / \  ] space – 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. 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.

About NIFS

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 types

Synchronous Responses

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

Asynchronous responses

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.

Entry Points and Methods

Usage Accessing the web service

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

*niws_partner service uses SOAP 1.2. with WS-* addressing. See example

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.

Please refer to the webservice methods and entry points here

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”

File format

Netcash file format is a tab-delimited string file.

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:

Entry PointPolling IdFileAccount reference
uploadreportstringtab delimitedNo
creditdatareportstringbase64 encodedYes
avsdatareportstringtab delimitedNo

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

Client Identifiers
Field Name

Alpha/ Numeric

Value
101Account reference

AN22

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

AN20

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

N1

0 = Inactive 1 = Active
104Delete this account

N1

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

N1

0 = Inactive 1 = Active
104Delete this beneficiary

N1

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

N11

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

Alpha/ Numeric

Value
110IsConsumer

N1

0 = Company 1 = Individual
111ID number

N13

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

AN

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

A15

Details to be used for Consumer enquiry
114First name

A15

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

A15

Details to be used for Consumer enquiry
117Date of birth

N8

CCYYMMDD
118Gender

A1

M or F
119Title

N1

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

Alpha/ Numeric

Value
121Trading name

AN

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

AN

Entity registration number
123Registered name

AN

Entity name
124VAT Number

N

Entity VAT number
125Legal 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
AVS Details
Field NameAlpha/ NumericValue
126AVS 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.
127Is 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)
User Details
Field Name

Alpha/ Numeric

Value
128Designation

A10

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

A20

Manager, Owner, Bookkeeper, etc.
Banking Details
Field Name

Alpha/ Numeric

Value
131Banking detail type

N1

1 = bank account
2 = credit card
9 = public beneficiary (applicable to outbound payments only)

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

132Bank account name

AN15

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

N1

1 = Current / Checking
2 = Savings
134Bank 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 beneficiary payments use “000000” as branch code
135Filler

N1

0
136Bank 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

132Credit card holder

AN20

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

N1

1 = MasterCard 2 = Visa
134Expiry month

N2

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

N4

4 digit year (CCYY)
136Credit card token

AN36

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

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

132Filler

N1

0
133Bank account type

N1

9
134Filler

N1

0
135Filler

N1

0
136Pre-defined beneficiary code

AN8

The Netcash beneficiary code.
Amounts
Important: Amounts must be zero (0) or greater; negative values are not allowed. For invoicing, Zero amount only allowed when ignoreAmount=true.
Field Name

Alpha/ Numeric

Value
161Default debit amount

N10

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

N10

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

N10

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

N10

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

N10

The credit amount (in cents)
164Credit terms

AN2

Credit term code
165Ignore invoice amount

AN1

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

Alpha/ Numeric

Value
201Email address

AN

This is the email address used to notify your client of the debit order.
(The “@” and “.” symbols are allowed in this field)
202Mobile 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)

203Postback URL

AN

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

AN

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

Alpha/ Numeric

Value
241Include DebiCheck authentication

N1

Indicates whether DebiCheck authentication is requested in addition to the Mandate

0 = Do not request DebiCheck authentication
1 = Request DebiCheck authentication

(The eMandate can still be signed)

242Debicheck mandate template Identifier

AN

The identifier of the DebiCheck template to be used to generate this mandate

EG: NCDCT000000001

243DebiCheck collection amountNThe debit amount in cents
246DebiCheck first collection differsN1
0 = Amount of the 1st debit is the same as 243 DebiCheck collection amount
1 = Amount of the 1st debit differs from 243 DebiCheck collection amount
247DebiCheck first collection amountNThe first debit amount in cents
248Debicheck first collection dateN8CCYYMMDD
249Debicheck mandate referenceANThe ID of the DebiCheck authentication
EG: NC000000001
250Debicheck collection dayAN7DebiCheck collection day code EG: WEEK_01
See DebiCheck Collection Day Frequency table
Payment Reference Details
Field Name

Alpha/ Numeric

Value
251Default 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)
252Beneficiary
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)
253Unique 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.
254Description of goods (p3)

AN50

The description of the goods sent for payment for your internal reference
255Send 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
256Send 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
257Request 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
258Credit card token (M15)

AN36

Credit card token for subscription cards
259Subscription indicator (M16)N10 = No subscription
1 = Log as a subscription payment
260Subscription cycle (M17)NNumber of cycles for subscription payment
261Subscription frequency (M18)N1          Monthly
2          Weekly
3          Bi-weekly
4          Quarterly
5          Six monthly
6          Annually
262Subscription start date (M19)N8CCYYMMDD
263Subscription recurring amount (M20)NRecurring amount (can differ from initiating 3D Secure  payment)
264Split payment indicator (M21)N0 = Not split
1 = Split payment
265Split target account (M22)N11Account number of Netcash target account
266Split amount (M23)NFixed value to be payed to target account
267Split percentage (M24)NPercentage of total value to be payed to target account
268Split minimum amount (M25)NMinimum payment to target account
269Split maximum amount (M26)NMaximum payment to target account
270Transaction Reference IDNNetcash statement transaction ID of the original Pay Now transaction to be refunded
Grouping Details
Field Name

Alpha/ Numeric

Value
281Debit masterfile group

AN2

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

AN2

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

Alpha/ Numeric

Value
301Extra 1

AN999

Custom User defined data
(Extra data you want returned for your internal system use)
302Extra 2

AN49

Custom User defined data
(Extra data you want returned for your internal system use)
303Extra 3

AN49

Custom User defined data
(Extra data you want returned for your internal system use)
304Additional 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.
311Field 1

AN50

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

AN50

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

AN50

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

AN50

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

AN50

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

AN50

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

AN50

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

AN50

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

AN50

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

Alpha/ Numeric

Value
321Physical address line 1

AN50

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

AN50

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

AN50

min:2, max:50
324Physical suburbAN50min:2, max:50
325Physical city

AN50

min:2, max:50
326Physical postal code

N4

327Physical 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
331Postal address line 1

AN50

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

AN50

min:2, max:50
334Postal suburb

AN50

min:2, max:50
335Postal cityAN50min:2, max:50
336Postal code

N4

337Postal 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

Contact Details
Field Name

Alpha/ Numeric

Value
341Phone number

N11

Include dialing codes EG: 27117822349
342Fax number

N11

Include dialing codes EG: 27117822349
Default Status
Field Name

Alpha/ Numeric

Value
401Default Action

A1

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

N8

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

AN13

The account which was defaulted on.
405Amount owed

N10

The default amount (in cents)
Trade References
Field Name

Alpha/ Numeric

Value
421Trade name 1

AN50

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

N11

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

AN50

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

AN50

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

N11

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

AN50

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

N11

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

Alpha/ Numeric

Value
441Subject telephone 1

N11

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

AN

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

Alpha/ Numeric

Value
501Debit order collections

N1

0 = not requested
1 = requested
502Creditor payments

N1

0 = not requested
1 = requested
503Salary payments

N1

0 = not requested
1 = requested
504Risk reports

N1

0 = not requested
1 = requested
505Pay Now

N1

0 = not requested
1 = requested

Activate Pay Now Request for Debit Order unpaids
509Resubmit 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
Credit Data (Risk)
Field Name

Alpha/ Numeric

Value
450Reason code

N2

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

Alpha/ Numeric

Value
601Installment occurrenceA4OOFF = once-off
RCUR = recurring
602Tracking indicatorN10 = No tracking
1 = Tracking
603Initiation dateN8CCYYMMDD
604Maximum collection amountNThe maximum debit amount allowed in cents
605Entry classAN4See Entry Class Table
606Debtor identification typeI = SA ID number
P = Passport
T = Company registration number
607Collection frequencyHow often will the debit run
Weekly: Event takes place once a week
FRTNF: Event takes place once every two weeks
MNTH: Event takes place once a month.
QURT: Event takes place once every three months or four times a year.
MIAN: Event takes place once every six months or two times a year.
YEAR: Event takes place once a year.
ADHO: Monthly By Rule – Event takes place based on the day of the month selected *see Ad Hoc Table Below
608Collection frequency day codeAN2On which day will the debit run 01 to 31
609Date adjustmentN10 = No date adjustment
1 = Date adjustment allowed
610Adjustment categoryA1Indicates period for amendment on Instalment Amount.
Must contain:
N – Never
Q – Quarterly
A – Annually
B – Bi-annually
R – Repo (when the repo rate changes)
611Adjustment typeA4AMNT = adjust by a specified amount
PERC = adjust by a percentage
612Adjustment amountNAmount by which the contract amount may be adjusted
613Debit value typeA11FIXED
VARIABLE
USAGE BASED
614Tracking day codeN20 = No Tracking
1 = 1 Day Tracking
2 = 2 Day Tracking
3 = 3 Day Tracking
4 = 4 Day Tracking
5 = 5 Day Tracking
6 = 6 Day Tracking
7 = 7 Day Tracking
8 = 8 Day Tracking
9 = 9 Day Tracking
10 = 10 Day Tracking
99 = Stop presentation
615Number of debitsNThe total number of times the debit will run
616RMS (Registered Mandate Service)N10 = do not apply RMS
1 = Apply RMS
617Custom contractAN50The contact number being migrated
Account Status
Field Name

Alpha/ Numeric

Value
510Account stage

A

Opportunity
Registration
Active
Closed
511Account status

A

Inactive opportunity
Lead opportunity
Active opportunity
Busy registering
Registration complete
Registration verification
Active pending
Active
Suspended
Closed
Unused account
Software Vendor Information
Field Name

Alpha/ Numeric

Value
521Software vendor key

AN36

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

AN25

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

AN30

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

AN199

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

N1

1 = Log active opportunity
526Account manager id

N

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

N1

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

N10

Employee bracket
Electronic Mandate Information
Field Name

Alpha/ Numeric

Value
530Debit frequency

N1

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

N2

MM
532Commencement day (debit day options)

AN4

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

AN4

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

AN50

Agreement reference
536Cancellation notice period

N2

01 – 20
537Allow variable debit amounts

N1

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

N1

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

AN

Additional clauses to be included the mandate
540Send mandate

N1

0 = Do not automatically send mandate for signature
1 = Automatically send valid mandates to the account holder for signature
541Debit 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
542Add to Mastefile

B

0 = False (Default)
Netcash Internal Reserved Data
Field Name

Alpha/ Numeric

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

DebiCheck Specific Indicators

DebiCheck Ad Hoc Table

This table contains the list of Ad Hoc Collection Frequency Codes for use in field 607.

*ADHO = Monthly by rule :

01=Last Monday
02=Last Tuesday
03=Last Wednesday
04=Last Thursday
05=Last Friday
06=Last Saturday
07=First Monday
08=First Tuesday
09=First Wednesday
10=First Thursday
11=First Friday
12=First Saturday
13=Last day
14=2nd Last day

DebiCheck Entry Class Table

This table contains the list of Entry class codes for use in field 605.

Entry Class IDDescription
0021Insurance Premium
0022Pension Fund Contribution
0023Medical Aid Fund Contribution
0026Unit Trust Purchase
0028Charitable or religious contributions
0031H.P. Repayment
0032Account Repayment
0033Loan Repayment (other than Mortgage)
0034Rental-Lease (other than Property)
0035Service Charge (Maintenance of Service Agreements, etc.)
0036Service Charge (Variable Amounts)
0037Value Added Tax (Vat collection)
0041Rent (Property)
0042Bond Repayment

DebiCheck Collection Day Codes

This table contains the list of Collection Day Frequency codes for use in field 250.

CodeDescription
WEEK_01Weekly Monday
WEEK_02Weekly Tuesday
WEEK_03Weekly Wednesday
WEEK_04Weekly Thursday
WEEK_05Weekly Friday
WEEK_06Weekly Saturday
WEEK_07Weekly Sunday
FRTN_01Fortnightly First Monday
FRTN_02Fortnightly First Tuesday
FRTN_03Fortnightly First Wednesday
FRTN_04Fortnightly First Thursday
FRTN_05Fortnightly First Friday
FRTN_06Fortnightly First Saturday
FRTN_07Fortnightly First Sunday
FRTN_08Fortnightly Second Monday
FRTN_09Fortnightly Second Tuesday
FRTN_10Fortnightly Second Wednesday
FRTN_11Fortnightly Second Thursday
FRTN_12Fortnightly Second Friday
FRTN_13Fortnightly Second Saturday
FRTN_14Fortnightly Second Sunday
MNTH_01Monthly 1
MNTH_02Monthly 2
MNTH_03Monthly 3
MNTH_04Monthly 4
MNTH_05Monthly 5
MNTH_06Monthly 6
MNTH_07Monthly 7
MNTH_08Monthly 8
MNTH_09Monthly 9
MNTH_10Monthly 10
MNTH_11Monthly 11
MNTH_12Monthly 12
MNTH_13Monthly 13
MNTH_14Monthly 14
MNTH_15Monthly 15
MNTH_16Monthly 16
MNTH_17Monthly 17
MNTH_18Monthly 18
MNTH_19Monthly 19
MNTH_20Monthly 20
MNTH_21Monthly 21
MNTH_22Monthly 22
MNTH_23Monthly 23
MNTH_24Monthly 24
MNTH_25Monthly 25
MNTH_26Monthly 26
MNTH_27Monthly 27
MNTH_28Monthly 28
MNTH_29Monthly 29
MNTH_30Monthly 30
MNTH_31Monthly 31
QURT_01Quarterly 1
QURT_02Quarterly 2
QURT_03Quarterly 3
QURT_04Quarterly 4
QURT_05Quarterly 5
QURT_06Quarterly 6
QURT_07Quarterly 7
QURT_08Quarterly 8
QURT_09Quarterly 9
QURT_10Quarterly 10
QURT_11Quarterly 11
QURT_12Quarterly 12
QURT_13Quarterly 13
QURT_14Quarterly 14
QURT_15Quarterly 15
QURT_16Quarterly 16
QURT_17Quarterly 17
QURT_18Quarterly 18
QURT_19Quarterly 19
QURT_20Quarterly 20
QURT_21Quarterly 21
QURT_22Quarterly 22
QURT_23Quarterly 23
QURT_24Quarterly 24
QURT_25Quarterly 25
QURT_26Quarterly 26
QURT_27Quarterly 27
QURT_28Quarterly 28
QURT_29Quarterly 29
QURT_30Quarterly 30
QURT_31Quarterly 31
MIAN_01Biannually 1
MIAN_02Biannually 2
MIAN_03Biannually 3
MIAN_04Biannually 4
MIAN_05Biannually 5
MIAN_06Biannually 6
MIAN_07Biannually 7
MIAN_08Biannually 8
MIAN_09Biannually 9
MIAN_10Biannually 10
MIAN_11Biannually 11
MIAN_12Biannually 12
MIAN_13Biannually 13
MIAN_14Biannually 14
MIAN_15Biannually 15
MIAN_16Biannually 16
MIAN_17Biannually 17
MIAN_18Biannually 18
MIAN_19Biannually 19
MIAN_20Biannually 20
MIAN_21Biannually 21
MIAN_22Biannually 22
MIAN_23Biannually 23
MIAN_24Biannually 24
MIAN_25Biannually 25
MIAN_26Biannually 26
MIAN_27Biannually 27
MIAN_28Biannually 28
MIAN_29Biannually 29
MIAN_30Biannually 30
MIAN_31Biannually 31
YEAR_01Yearly Annual
ADHO_01Ad-hoc Last Monday
ADHO_02Ad-hoc Last Tuesday
ADHO_03Ad-hoc Last Wednesday
ADHO_04Ad-hoc Last Thursday
ADHO_05Ad-hoc Last Friday
ADHO_06Ad-hoc Last Saturday
ADHO_07Ad-hoc First Monday
ADHO_08Ad-hoc First Tuesday
ADHO_09Ad-hoc First Wednesday
ADHO_10Ad-hoc First Thursday
ADHO_11Ad-hoc First Friday
ADHO_12Ad-hoc First Saturday
ADHO_13Ad-hoc Last day
ADHO_14Ad-hoc 2nd last day

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.

CodeDescription
100Authentication failure. Ensure that the service key in the method call is correct
101Date format error. If the string contains a date it should be in the format CCYYMMDD
102Parameter error. One or more of the parameters in the string is incorrect
200General 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.

Data Handling

File Parsing

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)

FieldTypeValue
Record identifierAN8###BEGIN
Batch nameANSUCCESSFUL / UNSUCCESSFUL / SUCCESSFUL WITH ERRORS
Result of uploadA13100
Start time of reportAN8HH:MM AM/PM

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

FieldTypeValue
Account referenceAN58Acc Ref :{your account reference}
Line numberANLine :{line in your file where error was found}
Error messageA13The error message

OR

FieldTypeValue
Record identifierAN8###ERROR
Error messageANThe error message

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

FieldTypeValue
Record identifierAN6###END
End time of reportAN8HH: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.

Error Handling

NIF Error handling

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

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

Additional Resources

Branding

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.

Support

If you require any assistance contact our technical support team

Testing

Testing

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

Disclaimer

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.