Currently set to Index
Currently set to Follow

Overview

NetConnector is regarded as the place in a third party application (host software); where the Netcash merchant will enter credentials to enable / communicate via the host software, with Netcash.

NetConnector is divided into three (3) critical components

  1. The NetAccess user login details storage.
  2. The validation of Netcash Service Keys entered into the application.

It is of vital importance that all Service Keys are stored (and validated) as “global/system variables” and ‘retrieved/called’ from your NetConnector database for usage in the respective service/s you integrate. This will eliminate search and replace of service keys as they can be reset on the Merchant Account as and when required. These service keys should be re-validated at least once every 24 hours and with each login/application start to ensure data will be successfully transmitted to the Netcash Merchant Account. The same methodology should be applied where an ISV receives their own unique Software Vendor Key. It too should be stored securely as a “global/system variable” and ‘retrieved/called’ from your NetConnector database for usage in the respective service/s you integrate.

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

Kindly adhere to the Netcash brand guidelines when developing.

Click here to see the recommended user experience which should be implemented.

    3.  NetAccess module integration.

The Netcash Integration Web Service (NIWS) is a single web service which exposes multiple endpoints. This specification 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 a valid Account Service -and Software Vendor Key (SVK) which is issued by Netcash – only used by approved Netcash ISV’s, alternatively you should use the default Software Vendor Key: 24ade73c-98cf-47b3-99be-cc7b867b3080

NetConnector was formerly known as Sage Connect.

Web Service Methods

The list of Netcash web service methods can be found here

QuickStart Guides

We have developed some Quick Start Guides to help you understand this service and to help you get started.

Programmers Guide

To start, refer our Programmers guide for more detail on how to apply the required methodology in this document.
Please ensure that the settings for Developers are correctly set before you proceed with the implementation below specification.

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/INIWS_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. – See Service Array 2 above

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

Due to the inherent risk in exposing a service that validates authentication details (Service Keys), 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 which 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 which include an invalid service key will re-initiate the 10-minute lockout.

Only a request which contains valid data will clear the table.

 

NetAccess User Detail Storage

NetConnector suggests 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. Read more about auto login and the required encryption.

TIP You may also invoke the NetAccess module without passing login details. This will entail that the Netcash website user will have to enter his/her login details manually.

Multi-Tenant
NetConnector facilitates a multi-tenant setup. For each entity/company/division/cost center etc. that uses the same software, a NetConnector setup screen should be made available. The advantage hereof is that when processing is initiated for a specific entity, the required entity can be selected and all the Netcash service keys -and related information (which has been pre-validated) can be used for processing.

General Security (see web UI example)

It is highly recommended that:

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

Invalid service keys are not stored in NetAccess and/or the application database. The “OK” button must only be enabled once all the Service Keys are validated. If a new Service Key is entered; it must be validated using this specification before it can be allowed to be stored in NetAccess and/or the application database.

Service key input

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. All data needs to be validated before allowing it to be saved to your database.

 

NetConnector Configuration

Your Netcash connection is verified.
Please provide a name for your Netcash account edit
Enter your Netcash Account Number edit
Enter your Netcash Account Service Key edit
Enter your Netcash Debit Order Service Key edit
Enter your Netcash Vault Service Key edit
Enter your Netcash Salary Payment Service Key edit
Enter your Netcash Creditor Payment Service Key edit
Enter your Netcash Pay Now Service Key edit
Enter your 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.

Netcash Logo

Please refer to the official Netcash brand guidelines when using any logos, images, icons, labels, descriptions, and/or references to Netcash in your development.

 

Labels to be used in host software.

Netcash endeavors to minimize support and training related issues by using standardized software labels within integrated software.
This makes it easier for end-users to understand as the labels on the integrated software and the labels on the Netcash system matches. We therefore require the usage of the following labels for the following reference fields in integrated software.

Service Key (GUiD) Description
Netcash Account Number Merchant Account number –  number starts with “5 ” and is N11
Account Services Service Key Used for Bank Account Validation and the Statement
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: there could be Multiple Merchant Tokens, depending on the amount of “pay points” setup. See the recommended user experience here.

All applications to open NetAccess in a “frameless pop-up window” from the respective application. The dimensions Netcash has designed the content for is 560w x 650h (pixels).

Testing

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

Netcash may provide example/sample/demo ‘code snippets’ and/or external links in this Technical Document. Such are for guidance purposes only and may not function on every developer’s system/s. Netcash disclaims any and all liability for the usage of guidance resources provided -and you as the Developer; must accept full responsibility for the usage of such. While every possible effort has been taken to ensure compatibility across multiple system configurations, the contents of this document cannot be guaranteed to work on all systems, with all operating systems -and/or with all system configuration/s.

Version 2020.1

Copyright © 2020 Netcash (PTY) Ltd