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

This specification is relevant to integrators who want to tokenize 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 questionnaire A to be compliant.

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

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

Access your PCI vault key on your Netcash account by navigating to Account profile – Netconnector – PCI Vault key

Styling

Styling can be sent to the GUI, to match the environment where it is being displayed.

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.

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

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=bf79254e-abcd-41db-1234-89121dd2x1yz&bbc=#f0f0f0&ff=Arial&fs=14px&bc=#777777&btnbbc=#f1f1f1&btnc=#777777&caller=http%3A%2F%2Fwww.mysite.co.za%2FprocessThis.asp

Encryption

Once you have the URL for the GUI established, 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/

Examples

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=bf79254e-abcd-41db-1234-89121dd2x1yz&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=bf79254e-abcd-41db-1234-89121dd2x1yz&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

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.

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.