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.
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.
Style | Style Abbreviation |
body background-colour | bbc |
body font-family | ff |
body font-size | fs |
body text colour | bc |
button background colour | btnbbc |
button text colour | btnc |
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
Order | Atrribute | Example Value |
1 | PciKey | 00000000-0000-0000-000000000000 |
2 | bbc | #f0f0f0 |
3 | ff | Arial |
4 | fs | 14px |
5 | bc | #777777 |
6 | btnbbc | #f1f1f1 |
7 | btnc | #777777 |
8 | caller | http%3A%2F%2Fwww.mysite.co.za%2FprocessThis.asp |
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:
Returned Atrribute | Data sample |
CardNme | Joe Bloggs |
MaskedNumber | 4242********4242 |
Token | 00000000-0000-0000-000000000000 |
ExpiryMonth | 08 |
ExpiryYear | 2099 |
Testing
See Testing section for more details. If you require any integration assistance contact our technical support team
Version 2020.1
Copyright © 2021 Netcash (PTY) Ltd