Sage Pay Tokenisation GUI | Sage Pay

Introduction

This specification is relevant to Sage Pay customers who want to tokenise credit card details through a GUI 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.

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 Sage Pay system and clicking on the Account profile tab in the top menu. You then click on Sage Connect 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 https://cde.sagepay.co.za/Site/TokeniseCard.aspx and will then be followed by

URL Attribute order structure

Order Attribute  Example Value
1 PciKey 00000000-0000-0000-000000000000
2 bbc #f0f0f0
3 ff 14px
4 fs 14px
5 bc #777777
6 btnbbc #f1f1f1
7 btnc #777777
8 caller http://www.mysite.co.za/processThis.asp

URL Example

http://cde.sagepay.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://merchant.sagepay.co.za/Default.aspx

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.sagepay.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.sagepay.co.za/Site/

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

Returned Attribute Data Sample
CardNme Joe Bloggs
MaskedNumber 4242********4242
Token 00000000-0000-0000-000000000000
ExpiryMonth 08
ExpiryYear 2099