Before you start

Please download the suggested API integration process flow document and use it as a reference when developing.
Kindly adhere to the Netcash brand guidelines when developing.

 

Programmers Guide

Refer to our Programmers guide for more detail on how to apply the required methodology in this document.
Ensure that the settings for developers are adhered to before you proceed with your implementation.

 

Web Service Methods

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

 

Quick Start Guides

Quick Start Guides will help you understand this service and get you started.

Overview

NetConnector is the area in an application (host software); where the Netcash client can insert credentials to enable communication with Netcash.
These credentials refer to Service Keys the Netcash client can issue in the NetConnector section of their Netcash account.

It is important to familiarise yourself with Service Keys, and their purpose by clicking here

NetConnector is divided into two components

  1. NetAccess user login details storage.
  2. Validation of Netcash Service Keys

It is important that all Service Keys are stored and validated as system variables and retrieved from the NetConnector database when used with integrated service/s.

This avoids search and replacement of service keys if they are regenerated by the Netcash client. Service keys should be validated at least once every 24 hours and with each login to ensure interaction with the Netcash account is successful. ISV Software Vendor Keys should be treated in the same manner but not exposed to the user.

The Netcash Integration Web Service (NIWS) is a single web service that exposes multiple endpoints. It is specific to the NIWS_partner* endpoint: https://ws.netcash.co.za/NIWS/niws_partner.svc and describes the input to the ValidateServiceKey method.

To access this web service method you require an Account Service and a Software Vendor Key (SVK): 24ade73c-98cf-47b3-99be-cc7b867b3080

Note: ISV’s have unique SVK’s issued by Netcash after their integration was successfully signed off.

 

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

Usage

The NIWS_Partner endpoint has the following methods available:

Method name Usage
ValidateServiceKey Check a range of Service key/Service Id combinations for a specified Netcash account to ensure that the key is valid

 

Object Name Description
Class ServiceInfo

Properties:

  • ServiceID
  • ServiceKey
List ServiceInfoList Generic list to add service info
Class ValidateServiceKeyRequest

Properties:

  • MerchantAccount
  • ServiceInfoList
  • SoftwareVendorKey
Class ValidateServiceKeyResponse
Class ServiceInfoResponse

Properties:

  • ServiceID
  • ServiceKey
  • ServiceStatus
List ServiceInfoResponseList Generic list holding service info responses per service

Input

The service accepts an object which contains the Software Vendor Key and account number, used for authentication, and then an array of service id/service key combinations to be validated:

Example 1:

protected NIWS_Partner.ServiceInfoList GetServiceInfo(string pServiceID, string pServiceKey)
    {
      ServiceInfo = new NIWS_Partner.ServiceInfo();
      ServiceInfo.ServiceId = pServiceID;
      ServiceInfo.ServiceKey = pServiceKey;
      ServiceInfoList.Add(ServiceInfo);
      return ServiceInfoList;
     }
 protected void ValidateServiceKey(string AccountNumber,
            string AccountServiceKey,
            string DebitOrderServiceKey,
            string CreditorServiceKey,
            string PayNowServiceKey,
            string RiskReportsServiceKey,
            string SalaryServiceKey)
    {
     //initialise all operations needed
     //---------------------------------------
     client = new NIWS_Partner.NIWS_PartnerClient();
     ValidateServiceKeyRequest = new NIWS_Partner.ValidateServiceKeyRequest();
     //---------------------------------------
     string SoftwareVendorKey = "24ade73c-98cf-47b3-99be-cc7b867b3080";
     //Populating request to validate
     //---------------------------------------
     //Add account number to MerchantAccount
     ValidateServiceKeyRequest.MerchantAccount = AccountNumber;
     //Add Vendor key issued by Netcash
     ValidateServiceKeyRequest.SoftwareVendorKey = SoftwareVendorKey;
     //checks if field was populated
     if (pAccountServiceKey != String.Empty)
     {
      ServiceInfoList = GetServiceInfo("5", AccountServiceKey);
     }
     if (pCreditorServiceKey != String.Empty)
     {
      ServiceInfoList = GetServiceInfo("2", CreditorServiceKey);
     }
     //Add service info list to request
     ValidateServiceKeyRequest.ServiceInfoList = ServiceInfoList;
     //---------------------------------------
     //Calling the ValidateServiceKey method validating account number with the service keys added
     var Request = client.ValidateServiceKey(ValidateServiceKeyRequest);
     //Do a check on the response for Account Status
     //001 = valid
     if (Request.AccountStatus == "001")
      {
     //do something, eg. output if account active
     //then add service info to list to check on each service status
       ServiceInfoResponseList = Request.ServiceInfo;
        foreach (var s in ServiceInfoResponseList)
         {
           string service = s.ServiceId;
            switch (service)
             {
              case "2": //do something
               break;
              case "3": //do something
               break;
              case "5": //do something
               break;
              case "10": //do something
               break;
              case "14": //do something
               break;
              default: //do something
               break;
             }
           }
        }
       else
        {
      //output if account not active
        }
      //Close client
        client.Close();
    }

Example 2:

</ValidateServiceKey>
 <MethodParameters>
  <request>
   <SoftwareVendorKey>24ade73c-98cf-47b3-99be-cc7b867b3080</SoftwareVendorKey>
    <MerchantAccount>599990123456</MerchantAccount>
      <ServiceInfoArray>
        <ServiceInfoArray0>
         <ServiceId>1</ServiceId>
         <ServiceKey>9c999cae-9999-99c9-a0c9-9999999999de </ServiceKey>
        </ServiceInfoArray0>
        <ServiceInfoArray1>
         <ServiceId>3</ServiceId>
         <ServiceKey>8c888cae-8888-88c8-a0c8-8888888888de </ServiceKey>
        </ServiceInfoArray1>
        <ServiceInfoArray2>
         <ServiceId>5</ServiceId>
         <ServiceKey>7c777cae-7777-77c7-a0c7-7777777777de </ServiceKey>
        </ServiceInfoArray2>
       </ServiceInfoArray>
  </request>
 </MethodParameters>
</ValidateServiceKey>

Example 3: (.php)

#!/usr/bin/php
<?php

// Use WDSL mode on SoapClient
$soap = new SoapClient(
            "https://ws.netcash.co.za/niws/niws_partner.svc?wsdl",
            array( "trace" => 1,'soap_version'=>SOAP_1_2)
        );
$hdr = new SoapHeader('http://www.w3.org/2005/08/addressing', 'Action', 'http://tempuri.org/NIWS_Partner/ValidateServiceKey');
$hdr2= new SOAPHeader('http://www.w3.org/2005/08/addressing', 'To', 'https://ws.netcash.co.za/NIWS/NIWS_Partner.svc');
$soap->__setSoapHeaders(array($hdr, $hdr2));

// This is value for parameter named "request" as sent through to ValidateServiceKey method
// See ValidateServiceKeyRequest entry in WSDL.

$sil = Array();
$sil[] = [ 'ServiceId' => '5', 'ServiceKey' => '00000000-0000-0000-0000-000000000001' ];
$sil[] = [ 'ServiceId' => '4', 'ServiceKey' => '00000000-0000-0000-0000-000000000002' ];
$sil[] = [ 'ServiceId' => '3', 'ServiceKey' => '00000000-0000-0000-0000-000000000003' ];
$sil[] = [ 'ServiceId' => '2', 'ServiceKey' => '00000000-0000-0000-0000-000000000004' ];

$r = [
        'SoftwareVendorKey' => '24ade73c-98cf-47b3-99be-cc7b867b3080',
        'MerchantAccount'   => '510123456789
        'ServiceInfoList' => $sil
      ];

$result = $soap->ValidateServiceKey(['request'=>$r]);
var_dump($result);
?>

Response

The service responds synchronously with an object containing an authentication status and a status for each element pair in the array:

Example 1:

<ValidateServiceKey>    
    <MethodParameters>
        <ValidateValidateServiceKeyResponse> <!--- Software Vendor Key / Merchant Account --->
            <SoftwareVendorKey>24ade73c-98cf-47b3-99be-cc7b867b3080</SoftwareVendorKey>
            <MerchantAccount>599990123456</MerchantAccount>
            <AccountStatus>001</AccountStatus>
        <ServiceInfo attr0="ServiceInfoResponseArray"isNull="false">
            <ServiceInfoResponseArray0> <!--- Service Array 0 --->
                <ServiceId>1</ServiceId>
                <ServiceKey>9c999cae-9999-99c9-a0c9-9999999999de</ServiceKey>
                <ServiceStatus>106</ServiceStatus>
            </ServiceInfoResponseArray0>
            <ServiceInfoResponseArray1> <!--- Service Array 1 --->
                <ServiceId>3</ServiceId>
                <ServiceKey>8c888cae-8888-88c8-a0c8-8888888888de</ServiceKey>
                <ServiceStatus>105</ServiceStatus>
            </ServiceInfoResponseArray1>
            <ServiceInfoResponseArray2> <!--- Service Array 2 --->
                <ServiceId>5</ServiceId>
                <ServiceKey>7c777cae>-7777-77c7-a0c7-7777777777de</ServiceKey>
                <ServiceStatus>001</ServiceStatus>
            </ServiceInfoResponseArray2>
        </ServiceInfo>
        </ValidateValidateServiceKeyResponse>
    </MethodParameters>
</ValidateServiceKey>

The original data submitted in the request is returned with a status for each section. In the example above:

  • The Software Vendor Key is valid and active. – See Software Vendor Key / Merchant Account above
  • The Merchant Account Number is valid and active. – See Software Vendor Key / Merchant Account above
  • The Service Key submitted for service id 1 is either invalid or not activated. Service (1) is active for Merchant Account – See Service Array 0 above
  • The service id 3 is not activated for the Merchant Account number submitted. – See Service Array 1 above
  • The Service Key submitted for service id 5 is active and the service is active for the Merchant Account.

Note: Invalid/inactive service keys should not be stored in the calling application.

Only where the service key response is 001 should the key be stored in the application.

Response Code Response status
001 Authenticated
103 No active partner found for this Software vendor key
104 No active client found for this Account number
200 General service error – contact Netcash support
201 Account locked out

 

Service key validation

Per ServiceId/Servicekey combination submitted.

Response Code Response status
001 Validated
105 No active service found for this Account number/ServiceId combination
106 No active service key found for this Account number/ServiceId /Servicekey combination

Service ID

The following service ID’s may be submitted:

Service ID Service Name
1 Debit orders
2 Creditor payments
3 Risk reports
5 Account service
10 Salary payments
14 Pay Now

 

Security lockout

An automated 10-minute lockout is built into the system to minimize the risk of brute force attacks by malicious persons or software.

Each request that includes a non-positive response (authentication failure or invalid service key) will be recorded. After the 3rd attempt within a 10-minute period, the account number will be locked and no further requests relating to that account number will be permitted for 10 minutes. The system will return a 201 error.

After the 10-minute timer has expired, any further requests that include an invalid service key will re-initiate the 10-minute lockout.

Only a request that contains valid data will clear the table.
After the 10-minute timer has expired, any further requests that include an invalid service key will re-initiate the 10-minute lockout.

NetAccess User Detail Storage

We recommend that you store the Netcash website user login details in a secure, encrypted manner in your database. These login details are then used to auto-login the user into the NetAccess infrastructure. The user must be able to update his/her details in your NetConnector infrastructure.

TIP: You may invoke the NetAccess module without passing login details. This will require the Netcash user to enter their login details manually.

The “OK” button should only be enabled once all the Service Keys are validated. If a new Service Key is entered; it should be validated using this specification before it can be stored in NetAccess and/or the application database.
Multi-Tenant

NetConnector allows for a multi-tenant setup. For each entity/company/division/cost center etc. that uses the same software, a NetConnector setup screen should be linked when processing is initiated for a specific entity, all the pre-validated NetConnector keys are used for processing.

General Security (see web UI example)

  • Login details for NetAccess is encrypted in the application database. A restore / password reminder service for these credentials should not be made available to the user. The user can reset their login details on the Netcash website and re-enter them in NetAccess and/or the application database.

Web UI Example

Below is a suggested NetConnector layout screen for users using web interfaces. It is suggested that drop-down / select is used for multiple accounts.

NetConnector Configuration

Your Netcash service keys are valid.
Netcash account name edit
Netcash Account Number edit
Netcash Account Service Key edit
Netcash Debit Order Service Key edit
Netcash Vault Service Key edit
Netcash Salary Payment Service Key edit
Netcash Creditor Payment Service Key edit
Netcash Pay Now Service Key edit
Netcash Risk Services Service Key edit

Netcash QR/POS Pay Point Configuration

Paypoint/Lane/Till Name edit
Paypoint/Lane/Till Name edit
Paypoint/Lane/Till Name edit
Paypoint/Lane/Till Name edit

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.

Labels to be used in host software

In an effort to minimize support we recommend standardising labels in integrated software.If the label in Netcash and the integrated software is the same, it eliminates confusion for the end user.

Service Key (GUiD) Description
Account Number Client Netcash Account number –  number starts with “5 ” and is N11
Account Services Service Key Used for Bank Account Validation and Statements
Debit Order Service Key Used for Debit Order Service
Salary Payment Service Key Used for Salary/Wage Payments
Creditor Payment Service Key Used for Creditor/3rd Party Payments
Risk Services Service Key Used for Verification and Risk Services
Pay Now Service Key Used for all Pay Now services
Vault Service key Used for Credit Card Tokenization
Merchant Token* Used by Pay Now QR to identify till points/lanes/pay points

*Note: Multiple Merchant Tokens could exist, depending on the number of “pay points” created. See the recommended user experience here.

Applications must open NetAccess in a “frameless pop-up window”. Optimal dimensions are 560w x 650h (pixels).

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.

Testing

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