This specification is relevant to integrators 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.
This web service will lower the PCI requirement to a Self-Assessment level where the integrator can fill in a questionnaire to be compliant.
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.
To render the GUI one needs to 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 input fields and response variables that will be posted once the cardholder has completed the form.
PCI Service Key
a PCI Service Key is required for this service. Access your PCI vault key on your Netcash account by navigating to Account Profile/Netconnector/PCI Vault key
Styling can be sent to the GUI, to match the environment where it is being displayed in. The styling features listed below including the abbreviation codes for appending to the URL. The value that is sent with the styling attribute is a standard hex colour value for the colour you are wanting to display in that item. Font names should conform to standard browser font restrictions. Should there be an error with any of these, the values will display the screen defaults as if they were not present in the request.
|body text colour||bc|
|button background colour||btnbbc|
|button text colour||btnc|
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.
Building the URL
The URL of the GUI you will be opening in your frame or to display in your website is built in a specific way and the order of the variables is important. To render the GUI correctly you need to ensure that the order of the variables is exactly as 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 addition, It is important to URL encode the Caller URL
URL Attribute Order Structure
Once you have the URL for the GUI established, encrypt it by running it through the following web services
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.
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
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
A request for the GUI is a simple call to the URL once you have built it up as stipulated above.
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|