NetConnector Setup

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

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:

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.

Service key validation

Per ServiceId/Servicekey combination submitted.

Service ID

The following service ID’s may be submitted:

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.

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.

^{*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).

Testing

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