Overview

This specification is relevant to Netcash merchants who want to tokenise credit card details through a GUI (graphical user interface). It applies to all data required to invoke the GUI and deal with the response from the interface.

The idea behind this GUI is to lower the PCI requirement to a Self-Assessment where the merchant must fill in questionnaire A to be compliant.

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.

Format

Requests to the webservices must be made in HTTPS.

URL’s are validated according to W3 standards (forward slash and colons)

Non-permissible characters will be automatically removed during validation.

Usage

The procedure involved to render the GUI is that one needs to first encrypt the URL that renders the GUI and then send the encrypted version of the URL appended to the base URL. This document specifies the fields required as input fields and the response variables that will be posted once the cardholder has filled out the form.

PCI Service Key

To use this service, you will need to use a PCI Service Key. This key can be found by logging into the Netcash system and clicking on the Account profile tab in the top menu. You then click on NetConnector in the left menu and click on PCI vault key.

Styling

The service allows for some styling to be sent to the GUI, so it can match the environment it is being displayed in. The styling features are as listed below including the abbreviation codes for appending them to the URL. The value that is sent with the styling attribute is a standard hex color value for the color you are trying to display in that item. Font names should conform with standard browser font offerings. If there is an error with any of these the values will display the screen defaults as if they were not present in the request to start with.

Caller

The GUI allows for the initiator to return to a URL of their choice to capture the tokenized reply in their environment. This attribute will thus hold the URL of the page the return will be sent to.

How does it work

Build the URL

The URL of the GUI you will be opening in your frame or to display in your website is built in a very specific way and the order of the variables in important. This means that to render the GUI correctly you need to make sure to get the order of the variables exactly in the order they are listed below. The URL will start with http://cde.netcash.co.za/Site/TokeniseCard.aspx and will then be followed by the attributes below, in the right order as listed. It is also very important to URL encode the Caller URL

URL Attribute Order Structure

URL Example

http://cde.netcash.co.za/Site/TokeniseCard.aspx?PciKey=bf77b54e-abd3-41db-b6ec-89121dd2c0db&bbc=#f0f0f0&ff=Arial&fs=14px&bc=#777777&btnbbc=#f1f1f1&btnc=#777777&caller= http%3A%2F%2Fwww.mysite.co.za%2FprocessThis.asp

Encryption
The next thing that is required once you have the URL for the GUI established, is that you encrypt it by running it through the following webservice

https://ws.netcash.co.za/CDN/SecurityService.asmx by consuming the method called “GetEncryptedUrl” and passing in the URL you have created as the only parameter.

Base URL

Once you have received the encrypted GUI URL back from the web service you can now append this to the base URL and call the page. The base URL is

https://cde.netcash.co.za/Site/

ASP Classic / HTTP code snippet

oSoap.ClientProperty("ServerHTTPRequest") = true
  oSoap.MSSoapInit("https://ws.netcash.co.za/CDN/SecurityService.asmx?wsdl")
   sResult = oSoap.GetEncryptedUrl("http://cde.netcash.co.za/Site/TokeniseCard.aspx?PciKey=00000000-0000-0000-000000000000&bbc=#f0f0f0&ff=Arial&fs=14px&bc=#777777&btnbbc=#f1f1f1&btnc=#777777&caller= http%3A%2F%2Fwww.mysite.co.za%2FprocessThis.asp")
    theURL = "https://cde.sagepay.co.za/Site/"
   theURL = theURL & sResult

iframe src=<%=theURL%> width=600 height=500 frameborder="0">

.NET code snippet

Protected Sub Button1_Click(sender As Object, e As EventArgs) Handles Button1.Click
  Dim i As New SecurityService.SecurityServiceSoapClient
  Dim postUrl As String = HttpUtility.UrlEncode("http://merchant.netcash.co.za/Default.aspx?test=1&bla=2")
  Dim baseUrl As String = "https://cde.netcash.co.za/Site/"
  Dim theUrl As String = "https://cde.netcash.co.za/Site/TokeniseCard.aspx?PciKey=bf77b54e-abd3-41db-b6ec-89121dd2c0db&bbc=#f0f0f0&ff=Arial&fs=14px&bc=#777777&btnbbc=#f1f1f1&btnc=#777777&caller=" & postUrl & """"
  Dim result As String = baseUrl & i.GetEncryptedUrl(theUrl)
 Response.Redirect(result, True)
End Sub

Input / Output

Input

A request for the GUI is a simple call to the URL once you have built it up as stipulated above.

Output

Once you have made the request to the GUI and it has been filled in by the client the output to the caller URL that was stipulated in the initial call is as follows:

Testing

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