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

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”

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

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
134 Bank account branch

N6

The branch code of the homing account. This field MUST be 6 digits. Pre-fill with zeroes if less than 6.
For public beneficiary payments use “000000” as branch code
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 N16 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
241 Include 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)

242 Debicheck mandate template Identifier

AN

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

EG: NCDCT000000001

243 DebiCheck collection amount N The debit amount in cents
246 DebiCheck first collection differs N1
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
247 DebiCheck first collection amount N The first debit amount in cents
248 Debicheck first collection date N8 CCYYMMDD
249 Debicheck mandate reference AN The ID of the DebiCheck authentication
EG: NC000000001
250 Debicheck collection day AN7 DebiCheck collection day code EG: WEEK_01
See DebiCheck Collection Day Frequency table
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
270 Transaction Reference ID N Netcash statement transaction ID of the original Pay Now transaction to be refunded
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
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
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
450 Reason code

N2

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

Alpha/ Numeric

Value
601 Installment occurrence A4 OOFF = once-off
RCUR = recurring
602 Tracking indicator N1 0 = No tracking
1 = Tracking
603 Initiation date N8 CCYYMMDD
604 Maximum collection amount N The maximum debit amount allowed in cents
605 Entry class AN4 See Entry Class Table
606 Debtor identification type I = SA ID number
P = Passport
T = Company registration number
607 Collection frequency How 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
608 Collection frequency day code AN2 On which day will the debit run 01 to 31
609 Date adjustment N1 0 = No date adjustment
1 = Date adjustment allowed
610 Adjustment category A1 Indicates period for amendment on Instalment Amount.
Must contain:
N – Never
Q – Quarterly
A – Annually
B – Bi-annually
R – Repo (when the repo rate changes)
611 Adjustment type A4 AMNT = adjust by a specified amount
PERC = adjust by a percentage
612 Adjustment amount N Amount by which the contract amount may be adjusted
613 Debit value type A11 FIXED
VARIABLE
USAGE BASED
614 Tracking day code N2 0 = 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
615 Number of debits N The total number of times the debit will run
616 RMS (Registered Mandate Service) N1 0 = do not apply RMS
1 = Apply RMS
617 Custom contract AN50 The contact number being migrated
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

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 N8 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
542 Add to Mastefile

B

0 = False (Default)
Field Name

Alpha/ Numeric

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

DebiCheck Specific Indicators

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

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

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

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

Code Description
WEEK_01 Weekly Monday
WEEK_02 Weekly Tuesday
WEEK_03 Weekly Wednesday
WEEK_04 Weekly Thursday
WEEK_05 Weekly Friday
WEEK_06 Weekly Saturday
WEEK_07 Weekly Sunday
FRTN_01 Fortnightly First Monday
FRTN_02 Fortnightly First Tuesday
FRTN_03 Fortnightly First Wednesday
FRTN_04 Fortnightly First Thursday
FRTN_05 Fortnightly First Friday
FRTN_06 Fortnightly First Saturday
FRTN_07 Fortnightly First Sunday
FRTN_08 Fortnightly Second Monday
FRTN_09 Fortnightly Second Tuesday
FRTN_10 Fortnightly Second Wednesday
FRTN_11 Fortnightly Second Thursday
FRTN_12 Fortnightly Second Friday
FRTN_13 Fortnightly Second Saturday
FRTN_14 Fortnightly Second Sunday
MNTH_01 Monthly 1
MNTH_02 Monthly 2
MNTH_03 Monthly 3
MNTH_04 Monthly 4
MNTH_05 Monthly 5
MNTH_06 Monthly 6
MNTH_07 Monthly 7
MNTH_08 Monthly 8
MNTH_09 Monthly 9
MNTH_10 Monthly 10
MNTH_11 Monthly 11
MNTH_12 Monthly 12
MNTH_13 Monthly 13
MNTH_14 Monthly 14
MNTH_15 Monthly 15
MNTH_16 Monthly 16
MNTH_17 Monthly 17
MNTH_18 Monthly 18
MNTH_19 Monthly 19
MNTH_20 Monthly 20
MNTH_21 Monthly 21
MNTH_22 Monthly 22
MNTH_23 Monthly 23
MNTH_24 Monthly 24
MNTH_25 Monthly 25
MNTH_26 Monthly 26
MNTH_27 Monthly 27
MNTH_28 Monthly 28
MNTH_29 Monthly 29
MNTH_30 Monthly 30
MNTH_31 Monthly 31
QURT_01 Quarterly 1
QURT_02 Quarterly 2
QURT_03 Quarterly 3
QURT_04 Quarterly 4
QURT_05 Quarterly 5
QURT_06 Quarterly 6
QURT_07 Quarterly 7
QURT_08 Quarterly 8
QURT_09 Quarterly 9
QURT_10 Quarterly 10
QURT_11 Quarterly 11
QURT_12 Quarterly 12
QURT_13 Quarterly 13
QURT_14 Quarterly 14
QURT_15 Quarterly 15
QURT_16 Quarterly 16
QURT_17 Quarterly 17
QURT_18 Quarterly 18
QURT_19 Quarterly 19
QURT_20 Quarterly 20
QURT_21 Quarterly 21
QURT_22 Quarterly 22
QURT_23 Quarterly 23
QURT_24 Quarterly 24
QURT_25 Quarterly 25
QURT_26 Quarterly 26
QURT_27 Quarterly 27
QURT_28 Quarterly 28
QURT_29 Quarterly 29
QURT_30 Quarterly 30
QURT_31 Quarterly 31
MIAN_01 Biannually 1
MIAN_02 Biannually 2
MIAN_03 Biannually 3
MIAN_04 Biannually 4
MIAN_05 Biannually 5
MIAN_06 Biannually 6
MIAN_07 Biannually 7
MIAN_08 Biannually 8
MIAN_09 Biannually 9
MIAN_10 Biannually 10
MIAN_11 Biannually 11
MIAN_12 Biannually 12
MIAN_13 Biannually 13
MIAN_14 Biannually 14
MIAN_15 Biannually 15
MIAN_16 Biannually 16
MIAN_17 Biannually 17
MIAN_18 Biannually 18
MIAN_19 Biannually 19
MIAN_20 Biannually 20
MIAN_21 Biannually 21
MIAN_22 Biannually 22
MIAN_23 Biannually 23
MIAN_24 Biannually 24
MIAN_25 Biannually 25
MIAN_26 Biannually 26
MIAN_27 Biannually 27
MIAN_28 Biannually 28
MIAN_29 Biannually 29
MIAN_30 Biannually 30
MIAN_31 Biannually 31
YEAR_01 Yearly Annual
ADHO_01 Ad-hoc Last Monday
ADHO_02 Ad-hoc Last Tuesday
ADHO_03 Ad-hoc Last Wednesday
ADHO_04 Ad-hoc Last Thursday
ADHO_05 Ad-hoc Last Friday
ADHO_06 Ad-hoc Last Saturday
ADHO_07 Ad-hoc First Monday
ADHO_08 Ad-hoc First Tuesday
ADHO_09 Ad-hoc First Wednesday
ADHO_10 Ad-hoc First Thursday
ADHO_11 Ad-hoc First Friday
ADHO_12 Ad-hoc First Saturday
ADHO_13 Ad-hoc Last day
ADHO_14 Ad-hoc 2nd last day

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:

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.

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

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.