Introduction to Paylink

Paylink is a comprehensive, low latency, secure and flexible online hosted payment form. It has been built from the ground up to cater for mobile and responsive design, meaning that your payments can be completed on a desktop, tablet or smartphone catering for IOS, Android or conventional browser environments.

Comprehensive: Paylink caters for the entire payment process including authorisation, payment notifications and validation.

Low latency: Paylink is written to be fast. Content such as images and JavaScript files are delivered using a global content delivery network. The payment form is a single page html 5 application with minimal dependencies ensuring that Paylink provides a fast, low latency user experience for the end customer.

Secure: Paylink 3 uses the latest browser security models to protect merchant and customer data, and is rigorously tested each time a new version is deployed.

Flexible:  Paylink is flexible by nature, it is responsive to the viewer's experience and offers a vast array of customisations.

Paylink makes online e-commerce easier to implement by handling the card payment process direct with the cardholder's browser and CityPay's payment processing servers, allowing you to concentrate on your business whilst allowing us to handle the payment process.

CityPay are also a PCI Level 1 accredited service provider, which streamlines your PCI accreditation process by indirectly handling sensitive cardholder data (CHD).

Key Benefits of Using Paylink

  1. Simplified payment solutions;
  2. payment processing is handled by our secure web servers adding security and confidence to your shoppers;
  3. 3D-Secure authentication is available within the application without any difficult MPI integration, allowing for immediate Verified by Visa and MasterCard SecureCode processing;
  4. customisation may be performed on the secure payment form;
  5. significantly reduced technical and financial overheads associated with software implementation and PCI compliance;
  6. reduced time-to-market.

Data Representation

Paylink 3 supports JSON, XML and application/x-www-form-urlencoded data exchange to create token based payment requests and payment notifications.

Token Based Payments

Paylink interacts with the Customer using a Payment Token embedded in a URL. The token is created by your application, calling the Paylink server create process to generate the token. You are then able to provide the generated token to the card holder via multiple methods, including HTTP redirection (GET or POST), a link in a page, email or pdf or a QR Code.

Paylink provides that every Payment Token is subject to an expiry period which, by default, is 30 minutes. The expiry period may be extended to any length of time either through configuration of the Payment Token Request or by management configuration. 


Paylink can perform web hooks using a HTTP POST call to the Merchant Application known as a PostBack. If payment is not made by a customer before the relevant Payment Token expires, Paylink 3 performs a PostBack to advise the Merchant Application that the relevant Payment Token and Payment Transaction has expired.

User interface

The Paylink 3 user interface has been developed with the following objectives in mind –

User friendly: the user interface has been written with the aim of guiding the user through the payment process logically and with ease.

Compliance with modern browser standards, the user interface is generated using HTML5 and is tested for compatibility with older browsers.

Wide, cross-platform browser support: Paylink has been developed to support Microsoft Internet Explorer version 8 and above, Google Chrome, Mozilla Firefox, the Opera browser and Apple Safari. It has also been developed to support payment on Android and Apple iOS-based devices.

HTML5 Single Page Application: the user interface is designed as a single page HTML5 application which requires the user to download the page only once where all subsequent interactions between the Customer Browser and Paylink are structured using the XMLHttpRequest API ("XHR") to allow a high level of interaction between the Customer and the Paylink Payment Form.

Responsive design: Paylink's style is built upon a cut down version of Twitter Bootstrap. the payment form automatically scales to fit the screen area available to the customer's browser while maintaining breadth of functionality.

Internationalisation: Paylink generates a Payment Form appropriate to the Customer according to the language reported by and the location implied by the HTTP Accept-Language request header received by Paylink 3 from the Customer Browser.

Pragmatic error reporting

By virtue of its staged validation and processing architecture, Paylink generates a list of all validation errors it encounters when processing an incoming request from the Merchant Application before returning any response. Accordingly, the Merchant Application is able to implement comprehensive error management and reporting.


Paylink maintains a record of the changes a Customer makes to the pre-completed Payment Form, and any subsequent changes the Customer makes to their payment details on each attempted payment submission.

3-D Secure

3-D Secure is embedded into Paylink, ensuring that the authentication experience for the user is seamless. No further integration is required to run a fully seamless authenticated transaction process, thereby reducing exposure to fraudulent transactions.

Integration Testing

To facilitate integration development and testing, Paylink provides a test transaction mode which behaves in accordance with the production payment processing system. See  Testing Best Practices for using the test mode.

Custom Fields

Paylink offers the ability for a Merchant Application to provide custom fields for data collection through the payment form. 

Card Holder Account Support

Paylink supports the storage of card holder account data which stores card holder data, allowing Merchants to process a payment for subsequent charging. 

PCI-DSS requires that the card security code should not be stored and we are therefore unable to store this data. Due to this absence, card holder account payment transactions may be subject to higher transaction charges due to the heightened chargeback risk.

Surcharging Support

Paylink optionally enables Merchants to apply surcharges to Payment Transactions depending on the type of Payment Card the customer intends to use for the transaction. Surcharge functionality includes support for –

  1. fixed amount surcharges irrespective of the transaction value;
  2. percentage surcharges which may operate to pass on the cost of credit cards transaction processing; or
  3. a mixture of fixed amount surcharges and percentage surcharges which may operate to reflect the different transaction processing approaches adopted for credit and debit card transactions.


We have designed Paylink to be simple in delivery but as secure as possible. Paylink 3 complies with PCI-DSS requirements by following the recommendations of the Open Web Application Security Project ("OWASP") top 10 vulnerabilities as follows –

Injection: the Paylink application is protected from any injection flaws by ensuring that all data is parameterised and input validation is performed before any data is handled by the application.

Broken Authentication and Session Management: Paylink uses the URL as a construct of a session and does not require a session cookie to maintain state. The scope at which this URL is available is configurable such that a payment may be locked to a browser or IP address. The unique identifier in the URL is a 64 bit randomised string that is guaranteed to be unique per merchant.

Cross Site Scripting: Paylink 3 is protected against cross-site scripting ("XSS") attack vectors through a number of mechanisms. All input data is validated, sanitised and encoded before being rendered within the body of the page. We also enable a Content Security Policy ("CSP") for the Paylink application which ensures that the application is only allowed to load page resources from an acceptable list of directives.

Insecure Direct Object References: No references are used in communication between the Merchant Application and Paylink, or the Customer Browser and Paylink 3 that map directly to internal objects with the exception of the Payment Token used for Payment Transaction session management.

Security Misconfiguration: Paylink is deployed in compliance with CityPay's internal security policies that provide for structured security analysis and security hardening of servers based on their potential exposure. CityPay's internal security policies are regularly updated to be abreast of latest security trends and all of our servers are regularly patched and vulnerability tested.

Sensitive Data Exposure: Card holder data is encrypted using HTTPS with validated SSL certificates. Additionally, HTML forms generated are transmitted with the Cache-Control HTTP header set to prevent caching on the Customer Browser, or by any intermediate proxy. The HTML form element is prevented from remembering the data entered by disabling autocomplete.  Sensitive data such as the primary account number ("PAN") are encrypted using an asymmetric encryption algorithm immediately following input validation on the server. Throughout its operations, CityPay uses industry standard strong encryption algorithms (AES256) and has adopted key management and rotation process to maintain security.

Missing Function Level Access Control: Every Paylink Payment Token Request is subject to authentication and access control before a Payment Token is generated. Paylink does not have any hidden functions accessed without authentication, or outside the context of an established Payment Transaction session.

Cross Site Request Forgery: Paylink creates a CSRF token in the form of a session based cookie when the Payment Token URL is first accessed. This cookie is used to effectively bind the Payment Token to the relevant Customer Browser session to protect the Payment Transaction against cross-site request forgery ("CSRF") attacks.

Using components with Known Vulnerabilities: any dependencies are subject to scrutiny and are validated for use as a dependency through acceptable use policies. CityPay only uses industry validated components and maintains a vulnerability programme that checks for vulnerabilities against these components.

Unvalidated Redirects and Forwards: The payment token follows an undisclosed, internal algorithm which allows us to validate any Payment Token before it arrives to us. As the token is generated by a server side call, the merchant is able to trust the URL before forwarding the user for payment.

Web browser support

Specifically, we support the latest versions of the following browsers and platforms. On Windows, we have limited support Internet Explorer 8-10 and recommend IE 11 or Edge. 


Paylink 3 Technical Overview

Payment processing is initiated by a request from the Merchant's Application servers to CityPay to generate a Paylink Token via an API call. Paylink generates a unique token which should be handled by your web application to forward the user to the Paylink Payment Form for completion . 

Hello Paylink!

A simple workflow process can be

  1. The shopper selects items they which they wish purchase from your online store. They then select that they wish to pay be card payment.
  2. Your online store sends an API call to Paylink to generate a payment Token. 
  3. Once the token is generated, your online store forwards the user's browser to the secure URL provided with the Token Response
  4. The shopper enters their card details into the online form
  5. Paylink authorises the transaction in real time with the CityPay acquiring cloud
  6. When successfully processed, we notify your webstore via a PostBack
  7. The shopper is redirected back to your online store 

Accessing Paylink

The Paylink service is provided using a strongly encrypted TLS 1.2 channel for transmitting payment card data. 

Data is exchanged using XML, JSON or URL encoded form data. For Paylink 3, we recommend JSON. Whichever data type is used, Paylink generates its response using the same format used by the originating request. The Paylink API allows developers to integrate applications using a wide variety of languages that support established transport and application-layer protocols for data exchange.

Transaction Control Flow

  1. Paylink Token Generation
    1. the Merchant Application generates a Token for a Paylink Transaction via an API call (see  Token API Reference )
    2. the Merchant Application transfers browser control to the Paylink service to a URL within the Paylink Token Response (i.e. http redirect, javascript document.location or printed material).

  2. Payment Form
    1. Paylink validates and authenticates the request and renders a Payment Form based on the account configuration;
    2. the Shopper completes the Payment Form using their user agent (browser);
    3. the Payment Form validates the information entered into the form and on validation, is processed by the Paylink Processing Server;

    4. Paylink generates a Transaction Response which is handled by the Payment Form to determine –
      1. whether the transaction was successfully processed;
      2. whether the transaction was not successfully processed;
  3. Transfer of application control flow from Paylink to the Merchant Application
    1. if an On Success URL or an On Failure URL exists, a redirection will occur after any delay, from the Customer's Browser. 
    2. Should a Return Parameters Flag be set for the Transaction, the POST call will include the results of the transaction.

Successful payment transaction control flow

  1. if an On Success URL was configured in the originating Token Request for the Transaction and a redirection delay has been specified, the Payment Form displays a dialog stating that the Transaction was successful. After the requisite delay or on the Customer clicking on a button of the dialog, the Payment Form redirects the Customer Browser to the On Success URL;
  2. if an On Success URL was configured in the originating Token Request for the Transaction and no redirection delay has been specified, the Payment Form redirects the Customer Browser to the On Success URL immediately;
  3. if an On Success URL was not specified for the Transaction, the Payment Form displays a dialog stating that the Transaction was successful. The Customer is required to close the browser tab or window.

Failed payment transaction control flow

Displays a dialog stating that the Transaction failed and allows the Customer to – 

  1. amend their payment card details to enable a further Transaction Request to be made; or
  2. if an On Failure URL was specified for the Transaction, click on the Return button for the Customer's Browser to be redirected to the On Failure URL; or
  3. The Customer closes the browser tab or window;

Merchant Application Integration

To integrate with CityPay Paylink, you will need:

  1. CityPay Client Id. This is a top level account which identifies you as a client on our systems. Each client may have multiple merchant accounts.
  2. CityPay Client Licence Key. This licence key identifies your services that are registered for your account.
  3. CityPay Merchant Id. To be able to process you will need a merchant id. This maps to one or more bank merchant accounts and can be used to process and route payments to your merchant account.

Please contact sales if you do not have these details.


See  Testing Best Practices  for testing your integration.


Before creating tokens, we need to open access for your systems to process transactions for each Merchant Id. Access control is based on your IP address either as a single IP address or a subnet.  This whitelists your application through the Paylink application firewall and allows token creation. You will also require authenticated access provided by your Merchant Id and Licence Key within the request.

When setting up your account, please advise support of any IP addresses to be configured.

Recommended Integration Workflow

  1. determine content type of call: JSON(preferred), XML, Url-Encoded
  2. create structure for the Token Request
    1. specify the relevant merchantId for your account
    2. specify the relevant licenceKey provided for the Paylink service
    3. specify the transaction mode
      1. is a test transaction set test to true
      2. is a live transaction set test to  false
      3. specifying no value will result in a test transaction
    4. specify the identifier
    5. specify the amount
    6. specify further options as per the  Token API Reference
  3. perform a HTTPS POST operation to the Paylink3 server URL, specifying the Token Request as the body of the POST call
  4. inspect and parse the Token Response
  5. if the result field is 1, obtain the value of the url field and direct or redirect the customer browser to the provided value
  6. If the result field is 2, obtain the value represented by errors and process each  error according to their respective errorCode;

Token API Reference

Supported Types

Paylink supports XML or JSON requests. This allows for developers to integrate with languages they are familiar with. A payment request can be selected as

  1. JSON request by setting the content-type header to "application/json
  2. Xml request by setting the content-type header to "text/xml"


JSON data representation provides support for name-value pairs, array values accessed by index in a familiar yet language independent form. JSON names are case sensitive with integer and boolean  values specified in unquoted form.

Paylink Token Request
	"merchantId": <integer_value>,
	"licenceKey": "<string_value>",
	"identifier": "<string_value>",
	"test": "<string_value>",
	"amount": <integer_value>,
	"cardholder": {
		"title": "<string_title>",
		"firstName": "<string_value>",
		"lastName": "<string_value>",
		"address": {
			"address1": "<string_value>",
			"address2": "<string_value>",
			"area": "<string_value>",
			"postcode": "<string_value>"
Paylink Token Response (Error)
	"id": "<string_value>",
	"result": 0,
	"errors": {
		"code": "<string_value>",
		"msg": "<string_value>"
Paylink Token Response (Success)
	"id": "<string_value>",
	"result": 1,
	"url": "<string_value>"


The XML data representation provides support for arbitrarily nested name-value pairs. Element names are case sensitive . Where values are omitted or specified in the form of an empty element such as <element/>  these values are considered as not provided or empty. 

Paylink Token Request
Paylink Token Response (Error)
		<error code="code" msg="msg" />
Paylink Token Response (Success)

Paylink Token Request

To create a Paylink token, a call should be made to the Paylink server at The call is validated, checking

  1. the source of the request
  2. the content type of the request
  3. the validity of the request

Once these have all been met, a response will be returned which provides a url which should then be used to redirect the user's browser to payment.

Merchant Authentication Fields

These fields are required to identify your account

	"merchantId": 12345,
	"licenceKey": "ASCnrtsona46on",

int, Required 

The merchant id that you wish to process this transaction with. You will be provided with one or more merchant ids when signing up for an account.


string, Required

The licenceKey field is used to identify the licensed version of the Paylink service that is being run. The licensed version holds default configurations which may streamline the Required parameters for running the service.

If you are migrating from a previous version of Paylink, you will need to obtain a new licence key, if you have not been supplied with a new key, please contact support.

Processing Configuration

Fields used to identify what is to be processed

	"amount": 7495,
	"clientVersion": "MyApp 1.0.1",
	"email": "",
	"identifier": "0209fcb3fe72",
	"test": true
    <clientVersion>MyApp 1.0.1</clientVersion>

int, Required

The amount field is used to specify the intended value of the transaction in the lowest denomination with no spacing characters or decimal point. This is the net total to be processed. An example of £74.95 would be presented as 7495.


string, (Optional) (Advanced)

The clientVersion field is used to specify the version of your application that has invoked the Paylink payment process. This feature is typically used for tracing issues relating to application deployments, or any Paylink integration module or plugin.


string, (Optional)

The email field is used for the Merchant to be notified on completion of the transaction . The value may be supplied to override the default stored value.

Emails sent to this address by the Paylink service should not be forwarded on to the cardholder as it may contain certain information that is used by the Paylink service to validate and authenticate Paylink Token Requests: for example, the Merchant MID and the licence key.


string, Required (5-50 characters)

The identifier field is used to identify a particular transaction linked to a Merchant account. It enables accurate duplicate checking within a pre-configured time period, as well as transaction reporting and tracing. The identifier should be unique to prevent payment card processing attempts from being rejected due to duplication.


string, Required (default=true)

The test field specifies mode of the transaction as follows

true: the transaction will be processed as if it was a live transaction however authorisation will be performed by the CityPay Test Authorisation System to enable comprehensive systems integration testing. If no value is supplied then a request is assumed to be a test transaction by default.

false: the transaction will be processed and authorised using an upstream Payment Card Acquirer such that, on a successful transaction, the relevant Payment Card Holder Account will be deducted the amount of the transaction on authorisation and the Merchant credited.

Cardholder Fields

Cardholder fields are used to identify the underlying cardholder processing the transaction. These values are optional and the user can complete these values on the online form.

	"cardholder": {
		"title": "Mr",
		"address": {
			"address1": "1 Downing Street",
			"address2": "Westminster",
			"area": "London",
			"postcode": "SW1A 2AA",
			"country": "GB"
		// advanced optional security
		"remoteAddr": "",
		"userAgent": "Mozilla/5.0(Mac...Safari/537.36"
			<address1>1 Downing Street</address1>
			<postcode>SW1A 2AA</postcode>
		<!-- advanced optional security -->
	    <acceptHeaders>text/html,applicat ...;q=0.9</acceptHeaders>
			<userAgent>Mozilla/5.0(Mac ...Safari/537.36</userAgent>


object, (Optional)

The cardholder node represents a container for the following card holder-related fields.


string, (Optional)

The field is used to for the payment card holder's email address. This field is used to send a receipt from the Paylink service direct to the payment card holder.

In any given transaction, the email address for the payment card holder may be

  1. provided through the Paylink Token Request to enable pre-population of the Paylink Payment Form; or
  2. collected through the Paylink Payment Form.

string, (Optional)

The cardholder.firstName field refers to the first name of the card holder.


string, (Optional)

The cardholder.lastName field refers to the last name of the card holder.


string, (Optional)

The field refers to a known mobile number of the card holder. This can be used for

  1. Data collection via the Paylink Payment Form; or
  2. Optionally send an SMS on completion of a transaction. This feature is a licensable option and is not configured by default.

string, (Optional)

The cardholder.title field refers to the title for the card holder



The cardholder.address entity represents a container for the following address-related fields.


string, (Optional)

The cardholder.address.address1 , cardholder.address.address2 and cardholder.address.area fields are used for to the billing address of the payment card holder. The billing address for the payment card holder is Required if AVS address checking is enabled.

In any given transaction, the billing address for the payment card holder may be

  1. provided within the Paylink Token Request to enable pre-population of the Paylink Payment Form; or
  2. collected through the Paylink Payment Form.

string, (Optional)

The cardholder.address.postcode field is used for the postal/zip code associated with the billing address of the payment card holder. The postal code is Required if AVS postcode checking is enabled.

In any given transaction, the postal code associated with the billing address for the payment card holder may be

  1. provided through the Paylink Token Request to enable pre-population of the Paylink Payment Form; or
  2. collected through the Paylink Payment Form.

string, (Optional) (RFA)

The field is used to specify the country of the billing address of the payment card holder.

In any given transaction, the country of the billing address for the payment card holder may be

  1. provided through the Paylink Token Request to enable pre-population of the Paylink Payment Form using an ISO 3166 two or three character country code.; or
  2. collected exclusively through the Paylink Payment Form.

Advanced CardHolder Security Options

These fields are used only where the user of your site should be restricted to the same browser.


string, (Optional) (Advanced)

The cardholder.acceptHeaders field may be used to specify the accept headers string generated by the Customer Browser on GET and POST requests. This field may be used to lock the Paylink Payment Form to the Customer Browser such that, if the Customer were to attempt to use a different browser to conclude the Payment transaction or a malicious third party was to attempt to hijack the Payment transaction, an error will be generated.


string, (Optional) (Advanced)

The cardholder.remoteAddr field may be used to specify the remote IP address of the customer's browser. This field may be used to lock the payment process to the shopper by referencing the IP Address from which the original requests emanate. Should the shopper use a different source address or a malicious third party was to attempt to hijack the transaction, an error will be generated.

While locking a Payment transaction to an IP Address may reduce the risk of Payment transaction hijacking, Customers that access the Merchant Application from mobile broadband services, domestic broadband services or indirectly through a proxy cache may change their IP address on each GET or POST operation.


string, (Optional) (Advanced)

The cardholder.userAgent field may be used to specify the user agent string of the Customer Browser. This field may be used to lock the Paylink Payment Form to the Customer Browser such that, if the Customer were to attempt to use a different browser to conclude the Payment transaction or a malicious third party was to attempt to hijack the Payment transaction, an error is generated.

Some browsers may vary this value depending on installed plugins. Paylink only supports values that may be directly compared.

Configuration Fields

Configuration Fields allow for tailoring the Paylink user experience and for providing integration parameters to work with your webstore

	"config": {
		"acsMode": "inline",


Container for config options. When specified, config items will override any stored account values.


string, (Optional) (default = iframe)

The config.acsMode field specifies the approach to be adopted by the Paylink payment form when displaying a 3-D Secure authentication window. The values may be as follows

iframe: shows the 3-D Secure ACS in an iframe dialog, neatly embedding it in Paylink. This provides a more seamless flow for the card holder who is able to validate and authenticate their card through the dialog provided by their bank.

inline: an inline mode transfers the full browser window to the ACS which allowing the payment card holder to see their payment card issuer's details and the accompanying SSL connection status and certificate in the address bar of the Customer Browser.

If you request an iframe mode and the browser width is deemed as being small (< 768px) then an inline mode will be enforced. This is to ensure that mobile users have an improved user experience.

Custom Parameters

You are able to add custom fields to the Paylink engine which may request further information from the shopper. Fields may also be used as secrets and not be displayed in the browser, for instance a session token on your server. A custom parameter can display as a text field, select list, checkbox or any html5 input type.


array, (Optional)

The config.customParams field may be use to add custom fields to the Paylink Payment Form to collect additional information for Merchant use.

"config": {
   			"placeholder":"Enter the value for bespoke1"

Each custom parameter consists of the following properties


string, Required

refers to the name of the parameter used to specify the HTML form element name. This value can be referred back through the PostBack data.


string, (Optional)

an initial value for the parameter as it appears on the Form. If your parameter is hidden, the value will be required


boolean, (Optional)

a boolean value that states whether the field is required or optional. When an element is required, validation will be performed on the end user's input form


string, (Optional)

a value to set as the HTML5 placeholder attribute which will render in modern browsers.


string, (Optional)

a label that should appear immediately before the field element in the generated HTML form, describing what the form is used for. If this value is not supplied, the name value will be used


boolean, (Optional)

refers to a boolean value that states whether the field is a locked field that prevents entry or amendment by the person completing the form.

pattern a string value which specifies the HTML5 validation logic which is checked before submitting the form for payment for example a value of "PC[0-9]*" will require a value such as PC1, PC123.

a value which can allow grouping of custom elements. If no value is provided, a default addition parameters group is rendered.

This allows logical grouping to the payment form for multiple elements. For example, 3 elements with the group of "Your Details" would be displayed with a heading of "Your Details" and each form element displayed under this heading. Any items not within this group will be displayed in their respective group titles or the default group.

Groups are rendered alphabetically.

order a value which allows you to order the position of elements in a grouping. For instance a value which has 1 will order first. Defaults to 0. Items can be pushed in front by using negative values.

string, (Optional)

refers to the type of HTML 5 field entry and which may include ' hidden ' to represent a hidden field, or any other permitted value for the ' type ' attribute of the HTML 5 input element.

Should the fieldType be 'select' a select list will render however it will require populating with option values. Values can be constructed by providing a list in the value parameter, delimited by a pipe character '|'. If a single value is provided this value will be used as the value and label of the option item. To provide a different value and label to an item, you can delimit further with a colon ':'.

For instance

..."label" : "Age Group", "fieldType": "select", "value" : "Under 18|18-30|30-50|50+".... would render as 
  <option value="Under 18">Under 18</option>
  <option value="18-30">18-30</option>
  <option value="30-50">30-50</option>
  <option value="50+">50+</option>
..."label" : "Age Group", "fieldType": "select", "value" : "junior:Under 18|hipster:18-30|midage:30-50|senior:50+".... would render as 
  <option value="junior">Under 18</option>
  <option value="hipster">18-30</option>
  <option value="midage">30-50</option>
  <option value="senior">50+</option>


int, (Optional)

The config.expireIn field specifies a period of time in seconds after which the Payment Token or the associated transaction will expire. A default value of 30 minutes is specified by the Paylink service.

There is presently no limit imposed as to how long a given Payment Token may be held open; the technical limit being the period of time representable by a signed integer value.

The API can also convert an expiry time based on a string value. The following values are accepted

s Time in seconds, for example 90s
m Time in minutes, for example 20m
h Time in hours, for example 4h
w Time in weeks, for example 4w
M Time in months, for example 6M
y Time in years, for example 1y

string, (Optional)

The config.merch_branding field may be used to specify a URL for a custom cascading style sheet ("CSS") for the Merchant Application that the Payment Form may use to customise the appearance of the Payment Form.


string, (Optional)

A URL of a merchant logo to include. The URL should be delivered using HTTPS.


string, (Optional)

A URL of the terms of payment that you wish to be confirmed. If provided, a link and checkbox will be added that will be Required to be checked before payment may continue.


string, (Optional)

The config.lockParams field may be used to lock fields which are displayed in the form.

For example, if the cardholder.address.postcode field were to be specified in the config.lockParams field, this would will prevent the customer amending the postal code for the billing address of the payment card holder.

Field locking may be specified on a fine-grained parameter level such as cardholder.address.postcode, or cardholder.address.address1; or alternatively on a more coarsely-grained, container-level basis such as cardholder.address and cardholder which operates to lock all of the address-related fields and all the payment card holder-related fields respectively on any Paylink Form.

The following fields that may be locked are as follows

"cardholder": {
  "firstname": "John",
  "lastname": "Smith",
  "email": "",
  "address": {
   "address1": "12 New Street",
   "address2": "Old Plaza",
   "area": "",
   "country": "AU",
   "postcode": "4110"


The value of config.lockParams is specified as an array of string, using the JSON form.

      "lockParams" :[ "cardholder.address.postcode", "" ]


The value of config.lockParams is specified as a string list value, delimited by a comma



The config.options field specifies a list of configuration options to be applied to the transaction which provide, complement or override default values or the MID configuration for these options. Available options are

BYPASS_AVS_POSTCODE : which bypasses the AVS postcode checking policy where it is enabled by default;

BYPASS_AVS_ADDRESS : which bypasses the AVS address checking policy where it is enabled by default;

BYPASS_CSC_Required : which bypasses the CSC checking policy where it is enabled by default;

BYPASS_3DSECURE : which bypasses 3D secure processing where it is enabled by default. It is not possible to enforce 3D Secure as it requires further configuration by your account setup;

BYPASS_CUSTOMER_EMAIL : which allows bypassing of sending emails to the customer when enabled;

BYPASS_CUSTOMER_SMS : which allows bypassing of sending SMSs to the customer when enabled (licensed option);

BYPASS_DUPLICATE_CHECK : which allows the bypassing of the duplicate checker, this is on by default and allows prevention of duplicate transactions from being processed within a time slot;

BYPASS_MERCHANT_EMAIL : which allows bypassing of sending emails to the merchant account.

BYPASS_PREAUTH : which bypasses pre-authorisation when it is enabled to pre auth by default (licensed option);

CREATE_CAC_ACCOUNT_ON_AUTHORISATION : which Required where creating card holder accounts to confirm creation is Required (licensed option);

ENFORCE_AVS_ADDRESS : which enforces the AVS address checking policy where it is disabled by default;

ENFORCE_AVS_POSTCODE : which enforces the AVS postcode checking policy where it is disabled by default;

ENFORCE_CSC_Required : which bypasses the CSC checking policy where it is disabled by default;

ENFORCE_PREAUTH : which enforces pre-authorisation when it does not pre auth by default (licensed option);

REQUIRE_CUSTOMER_EMAIL : Enforces that the card holder must enter an email address;


Options are provided as an array of strings, i.e.




If BYPASS and ENFORCE options for the same underlying functionality exist or are supplied in the config.options array, the BYPASS option will be take precedence.


Nested Key Pairs, (Optional)

To allow for greater inoperability, Paylink offers developers the ability to include Json data in any call using a config.passThroughData field. This data will be stored with your token request for the duration of the transaction session but not with any resulting authorisation. This is useful to provide information related to the user's session or cart. A practical length of 1024 bytes is possible to be stored.

"config": {
        "passThroughData": {
            "Key1": "Value1",
            "Key2": "Value2",
            "Key3": 1234,
            "Key4": true,
            "Key5": {
                "sub1": "asdfadf",
                "sub2": 1234.9
            "Key6": [
                    "s1": 141,
                    "s2": true
                    "s1": 99,
                    "s2": true

The Paylink system doesn't restrict you to simple key value pairs and allows for nested complex objects to be supplied as demonstrated in the example above.

Pass through data will be supplied on a post back call or a post redirection.


string pairs, (Optional)

When sending a post back, it may be necessary to include authentication information or similar to the application you are calling. Values can be provided in the Token Request which are added as HTTP headers in the post back. For example

"config" {
        "passThroughHeaders": {
            "key1": "value1",
            "key2": "value2"

will result in HTTP headers being sent

POST /YourUrl HTTP/1.1
Content-Type: application/json
key1: value1
key2: value2
Cache-Control: no-cache
Pragma: no-cache

The pass through headers are only actioned on a post back and not redirection.


string, (Optional)

The config.postback field specifies a URL which is used by the Paylink service to inform the Merchant Application of the outcome of the transaction. This URL must be a valid URL which is accessible by the Paylink service on ports 80 or 443. Merchant internal or localhost addresses often used for development testing cannot be used unless made publicly available.

Within development we suggest using a product such as to create a secure tunnel for building your web hook.

In any given transaction, a postback URL may be provided through each Token Request or fallback to a default configured value in your panel.

If a URL is specified by the Paylink Token Request, it will take precedence over the configured value.

A valid URL is considered

  1. not an empty string
  2. is RFC1738 compliant
  3. is a valid, reachable port

A preconfigured URL may be expressly disabled by forwarding a value of none in your Token Request.

Testing HTTPS connections.

Paylink supports POSTback URLs where the endpoints use self signed certificates, or certificates signed by a private Certification Authority.


string, (Optional) (default = async)

The config.postback_policy field is used to specify a policy for POSTback URL handling, the options for which are as follows

sync: the operation will be performed before a Response is returned to the Customer Browser to ensure that the transaction may be authoritatively confirmed as successful by the Merchant Application before the outcome of the transaction is communicated to the customer.

async : the operation will be performed in the background whilst a response is returned to the customer's browser effectively speeding up the communication of the result to the customer

none: no operation will be performed.

No value or any other value will trigger the default setting.


string, (Optional) deprecated - see redirect_success and redirect_failure

The config.redirect field may contain a Redirection URL which the Customer Browser is redirected to, by the Paylink Payment Form, using a POST operation on successful or failed processing of a transaction; subject to MID configuration.

In any given transaction, the Redirection URL may be

  1. provided by the MID configuration; or
  2. provided to the Paylink through the Paylink Token Request.

If no config.redirect value is specified by MID configuration, or through the Paylink Token Request, the Paylink Payment Form will not return to the Merchant Application. The Payment Form will provide advice of the outcome of the transaction to the Customer and leave the Customer Browser in a state where the Customer must close the relevant browser tab or window.

The config.redirect field has been superseded by the config.redirect_success and config.redirect_failures fields, respectively.


int, (Optional)

The config.redirect_delay field may be used to specify a delay in seconds before the Customer Browser is redirected by the Paylink Payment Form on conclusion of a successful transaction. If the transaction fails, subject to MID configuration, the customer may be given the opportunity to resubmit the transaction with amended details for reprocessing.

If no value is set or is a negative value, the Paylink Payment Form will not redirect the Customer Browser until a Customer has clicked on a button to return to the store.

If config.redirect_delay is set to 0, the Customer Browser will be redirected immediately on a successful transaction; there will be no delay.

If config.redirect_delay is set to a value greater than 0, the Paylink Payment Form will display a modal dialog in the Customer Browser and redirect after the number of specified number of seconds have elapsed.


string, (Optional)

The config.redirect_success field may contain a Redirection URL which the Customer Browser is redirected to, by the Paylink Payment Form, using a POST operation on successful payment processing of a transaction; subject to MID configuration.

In any given transaction, the Redirection URL may be

  1. provided by the MID configuration; or
  2. provided to the Paylink through the Paylink Token Request.
  3. If no redirect_success field is provided, the value from the config.redirect field will be used

If no config.redirect_success value is specified by MID configuration, or through the Paylink Token Request, the Paylink Payment Form will not return to the Merchant Application on successful conclusion of a transaction, but will instead provide advice of the outcome of the transaction to the Customer and leave the Customer Browser in a state where the Customer must close the relevant browser tab or window.


string, (Optional)

The config.redirect_failure field may contain a Redirection URL which the Customer Browser is redirected to, by the Paylink Payment Form, using a POST operation on failed payment processing of a transaction; subject to MID configuration.

In any given transaction, the Redirection URL may be

  1. provided by the MID configuration; or
  2. provided to the Paylink through the Paylink Token Request.
  3. If no redirect_success field is provided, the value from the config.redirect field will be used

If no config.redirect_failure value is specified by MID configuration, or through the Paylink Token Request, the Paylink Payment Form will not return to the Merchant Application on a failed transaction that the Customer has not attempted to resubmit, but will instead leave the Customer Browser in a state where the Customer may only close the relevant browser tab or window.


boolean, (Optional)

The config.return_params field is used to determine whether the Paylink Payment Form should return the results of the transaction when redirecting the browser back to your store. The process is documented in Redirection Handling and uses a JavaScript process to perform a HTTP POST back to your store.

If a config.return_params value of true is specified, the POST operation will be accompanied by the results for the transaction passed as the body of the request.

If no value is specified for the config.return_params field, or any other value is specified, the POST operation will default to false and no values will be sent.

It is not recommended for a Merchant Application to rely on values it receives indirectly from the Paylink Payment Form via the Customer Browser as there is a risk that the values may have been adjusted immediately before the request is made to the Redirection URL. The Merchant Application can, however, validate the values it receives through the Redirection URL POST operation by submitted them to a suitable a SHA1 or SHA256 cryptographic hash function.


string, (Optional) (default = main)

The config.renderer field specifies the Paylink Payment Form to use for the transaction. The available options are

main : which refers to the main renderer, the default responsive design for the Paylink Payment Form which will adapt its layout to the Customer Browser in use such as mobile or desktop.

Card Holder Account Fields


string, (Optional) (Required with Card Holder Account Integration)

The accountNo field is used to specify a Client unique account number that the Paylink service should use when creating a Cardholder Account. The value of the accountNo field is an alpha-numeric string generated by the Merchant and should be no longer than 20 characters in length.

Cart Fields



Container for cart options.

The shopping cart represented in the cart.contents field group is not cross checked with the amount field


string, recommended

The cart.productionInformation field specifies information about the product or service that is the subject of the transaction. It will be rendered by the Paylink Payment Form in the header of the page.


string, (Optional)

The cart.productDescription field provides full text to the payment header and overrides the productInformation field.


integer, (Optional)

The mode field specifies the behaviour or functionality of the cart as follows --

Value Meaning
0 No cart functionality applies. This is the default value for the mode field.
1 Read-only cart functionality applies: the cart is shown with a breakdown of the item details provided by objects contained in the the contents array.
2 Selection cart functionality applies: the cart is shown as a drop-down box of available cart items that the customer can a single item select from.
4 "Dynamic" cart functionality applies: a text box is rendered to enable the operator to input an amount.
5 "Multiple item" cart functionality applies: the cart is displayed with items rendered with selectable quantities

array, (Optional)

The cart.contents field represents an array containing zero, one or more cart items represented by objects of the form --

	"sku": "<sku>",
	"label": "<descriptive label>",
	"category": "<category>",
	"brand": "<brand>",
	"variant": "<variant>",
	"count": 1,
	"amount": 1000

string, recommended

The sku field refers to the stock control unit identifier for the cart item.


string, recommended

The label field refers to a descriptive label for the cart item.


string, (Optional)

The category field refers to the category or classification of the cart item. For example, items may be categorised as food or non-food items, fancy goods, beverages and so forth. The Paylink Payment Form does not constrain the value of the category field to a particular set of categories; these are defined by the Merchant.


string, (Optional)

The brand field refers to the brand of the cart item. The Paylink Payment Form does not constrain the value of the category field to a particular set of brands; these are defined by the Merchant.


string, (Optional)

The variant field refers to the variant of the cart item to enable similar items to be distinguished according to certain criteria. For example, similar items may be distinguished in terms of size, weight and power. The Paylink Payment Form does not constrain the value of the variant field to a particular set of metrics; these are defined by the Merchant.


integer, (Optional)

The count field refers to the quantity of units that, taken together, represent the cart item. The Paylink Payment Form assumes a count of 1 in the event that no value for the count field is provided for a cart item.


integer, (Optional)

The amount field refers to the monetary amount chargeable in respect of the cart item, expressed in "lowest denomination form" ("LDF"). The Paylink Payment Form does not multiply this figure by the value provided by the count value for the cart item; this is principally to avoid rounding errors to introduce discrepancies between the value of the goods charged for and the total amount represented by the collection of cart items.

** Required subfields are only Required if the parent container is present in the relevant data represented.

Paylink Token Response

JSON Example

	"id": "ND4NjIzNzA4NzQyNjA0NTU",
	"result": 1,
	"url": ""

XML Example

    <id> ND4NjIzNzA4NzQyNjA0NTU </id>
    <url> </url>
Merchant Authentication Fields


string, Required 

The id field contains the merchant unique identifier for the configured transaction.


int, Required

The result field contains the result for the Paylink Token Request which is either

0 which indicates that an error was encountered while creating the token; or

1 which indicates that a Token was successfully created.

On successful validation, authentication and processing of the Paylink Token Request


string, Required (when result=1)

The url is the Paylink Token URL which is to be used by the Customer Browser to access the Paylink Payment Form.

On failure of the Paylink Token Request


Required (when result=0)

An array of errors which are found when attempting to create the payment URL

[n] code:

string, Required (when result=0)

The errors[n].code field contains an error code indicating why the Paylink Token Request could not be completed successfully.

[n] msg:

string, Required (when result=0)

The errors[n].msg field contains an error message indicating why the Token could not be generated.

Paylink Transaction Response Reference

Transaction Response parameters are returned in a POSTback or a redirection URL subject to configuration. 

Merchant Authentication Fields


The amount field specifies the total amount of the transaction in Lowest Denomination Form, inclusive of any surcharge applied.



The amount_initial field specifies the amount of the transaction as provided in the originating Paylink Token Request, in Lowest Denomination Form.



The authcode field contains the Authorisation Code returned by the Payment Card Acquirer if the transaction was successful . An Authorisation Code is an alpha-numeric string of characters and may in some cases be an empty string.



The authorised field authoritatively indicates that the transaction was authorised and was successful ; the authResult and errorCode fields may be used for more detailed information on the successful or failed transaction.

This value will be true for a live as well as a test transaction. It is therefore recommended to also check the mode field to ensure your system handles test transactions appropriately.



The currency field contains the currency of the transaction as an ISO 4217 3 digit alpha-numeric value.



The errorcode field contains an error code for the transaction Processing Request. An exhaustive list of error codes is available from API Response & Error Codes



The errorid field contains a Paylink internal error code for the transaction Processing Request in the form 000.000.000 for use in correspondence in relation to Paylink support issues.



The errormessage field contains a textual, human-readable error message for the transaction Processing Request.



The identifier field contains the identifier provided for the transaction in the originating Paylink Token Request.



The merchantid contains the CityPay Merchant MID that the transaction Processing Request was processed with.



The mode field specifies the mode of the transaction by returning " live " or " test ".



The result field contains an integer result code that indicates the outcome of the transaction in more detail. The following result codes are an exhaustive list and cater for all transaction types, including electronic commerce, card present and mail-order telephone-order transactions. Some result codes may not be relevant to the Merchant Application or to processing in an online environment.






Result code when a transaction is declined by the acquirer and no further processing is allowed



Result code when a transaction is accepted by the acquirer.



The transaction was rejected due to an error


Not Attempted

The transaction was never attempted to be processed (default)



Result code when a transaction has been referred for manual authorisation


Perform PIN Retry

Retry the PIN entry


Force Signature Verification

Force Signature Verification



Hold transaction and recheck


Security Error

Security Error


Call Acquirer

Call Acquirer


Do Not Honour

Do Not Honour


Retain Card

Retain Card


Expired Card

The card has expired. This normally occurs when a valid expiry date is supplied and the card has been superseded by the issuer.


Invalid Card No

The card number is invalid. This may occur after a valid LUHN check


Pin Tries Exceeded

The number of PIN entries have been exceeded


PIN Invalid

The PIN number entered is invalid


Authentication Required

Authentication required for a transaction, in an e-commerce transaction, the system will need to refer to an ACS


Authentication Failed

Authentication is required for the transaction. The authorisation process failed.



Is a business model which is used to verify that a card looks valid using AVS and CSC to check



A result which is returned when a pre-authorised transaction has been cancelled



The unknown response is a value returned when the system has produced an error and the result cannot be determined



The status field contains a single digit status of the authorisation. The status is a flag which determines how the transaction will be handled for settlement. Ordinarily the value of this is 'O' which indicates that the transaction is open for settlement. Merchants who have pre-authorisation enabled can determine that the transaction is pre-authorised by seeing a 'P' in this response.






The transaction is deemed as open for settlement and will be batched on the next scheduled batch run.


A Assigned The transaction has been assigned to a batch and will be settled on the next settlement run.
S Settled The transaction has been settled to the acquirer.
X Storage Failure This is used internally to determine if there was a problem in storage, you would not expect this value from Paylink
D Declined The transaction has been declined and will not settle
R Rejected The transaction has been rejected and will not settle
P PreAuth The transaction has been pre-authorised. The transaction will require a completion or a cancellation to settle.
C Cancelled The transaction has been cancelled and will not settle. Ordinarily a reversal would have occurred with the acquiring bank.
E Expired The transaction has expired and has automatically been reversed. The transaction will not settle.
I Initialised This is used internally to determine that the transaction has been initialised, you would not expect this value from Paylink
H Wait For Auth The transaction has been halted, waiting for authentication such as 3DSecure.
. Hold The transaction has been placed on hold and requires intervention. This is used by the grey listing of our fraud systems. (Full stop)
? Unknown This is a status which cannot be determined, you would not expect this value from Paylink


If surcharge functionality is enabled for the Merchant MID, the surcharge field contains the amount that has been added to the transaction by way of surcharge for the Payment Card selected to make the payment by the Payment Card Holder.

Surcharge functionality enables the Merchant to apply a fixed percentage charge or a fixed amount charge against a transaction to enable the Merchant to recover their costs of Payment Card processing. The actual surcharges to be applied to transactions are associated with a particular Merchant MID.


If surcharge functionality is enabled for the Merchant MID, the surcharge_rate field contains the rate in which the surcharge was applied.



The transno contains a Merchant-unique serial number for the transaction. The transno for a test transaction is -99; and for a transaction Processing Request that generated validation and request processing errors, -1.

Card Details


The cardSchemeId field contains an identifier for the card scheme of the Payment Card that was processed in the transaction.



The cardScheme field contains a string describing the card scheme of the Payment Card that was processed in the transaction.



The month of expiry of the card 1..12



The year of expiry of the card i.e. 2014



The maskedPan field contains a masked version of the Card Number used by the Card Holder when completing the Payment Form.

The Payment Card Number is masked by providing the first 6 numbers which identify the BIN Range for the Payment Card and the last 4 digits only; all other digits are substituted by an asterisk. For example: 412312******2151.

Card Holder Details


The address field contains the Payment Card Holder address used by the Customer when completing the Payment Form.



The country field contains the country code that the Payment Card Holder selected when completing the Payment Form.



The email field contains the email address that the Payment Card Holder entered when completing the Payment Form.



The firstname field contains the first name of the Payment Card Holder as entered on the Payment Form.



The lastname field contains the last name of the Payment Card Holder as entered in within the Payment Form.



The postcode field contains the postcode that the Payment Card Holder entered when completing the Payment Form.



The title field contains the title of the Payment Card Holder as entered on the Payment Form.

RFA Fraud Response Fields


The AVSResponse field contains the result of address verification by the upstream Payment Card Acquirer



' ' (Space)

No information


Address matches, post code does not


Postal code not verified due to incompatible formats


Street address and Postal code not verified due to incompatible formats


Street address and postal codes match


AVS Error


Issuer does not participate in AVS


Address information verified for international transaction


Street address and Postal codes match for international transaction


No match on address or postcode


Postal codes match. Street address not verified due to to incompatible formats


System unavailable or Timed Out


Service not supported by issuer or processor


Address information unavailable


9 digit post code matches, Address does not


Postcode and Address match


Address and 5 digit post code match


5 digit post code matches, Address does not

The meaning of some values are duplicated due to the source values from MasterCard and Visa.



The CSCResponse field contains the result of the card security code checking by the upstream Payment Card Acquirer




Card verification data matches


the card verification data was checked but did not match


The card verification data was not processed


The card verification data should be on a card but the merchant indicates that it is not


Issuer not certified, did not provide the data or both


No information

3DSecure Result Codes


The cavv field is set to a value generated by the Card Issuer during authentication. The cavv can provide evidence of transaction authentication during an online purchase. If the transaction is authenticated, this value should be kept to receive chargeback protection.



The eci field contains the Electronic Commerce Indicator (ECI) which indicates the level of security applied when the cardholder provided payment card details to the Merchant. Values for the eci field are

5: set when a transaction has been fully authenticate using 3DSecure;

6: set when an attempt is made to authenticate the cardholder using 3DSecure, but the Payment Card Issuer or the Payment Card Holder were not participating in the 3DSecure scheme, or the Payment Card Issuer ACS was not able to respond to the request;

7: set when transaction authentication was unsuccessful or not attempted.



The authenticationResult field provides the outcome of 3DSecure authentication as follows

Y : authentication was successful;
N : authentication failed;
U : authentication could not be performed;
A : authentication was attempted but could not be performed

Authentication that could not be performed or attempted may result in a transaction that is authorised by the Acquirer. In such circumstances, the transaction may be subject to a higher risk profile and may not benefit from the shift in fraudulent transaction liability from Merchant to Customer that 3DSecure authentication generally provides.

CityPay are able to control the workflow of your transaction if you desire only fully authenticated transactions to be authorised.

Cardholder Account Fields


The cac field contains the results of the control path followed by Paylink 3 in response to a transaction Processing Request for a transaction which the Merchant Application indicated, by MID configuration or through the originating Paylink Token Request, that it requires to be associated with a Cardholder Account. The values returned in the cac field are as follows

0 indicates that no action has been taken;

indicates that the Cardholder Account referenced in the accountNo field of the originating Paylink Token Request was loaded and processed;

This result code is not usually generated in the context of a transaction progressed using the Payment Form.

2 indicates that a new Cardholder Account, with the account reference returned in the cac_id, was created successfully in circumstances where the Merchant Application has not provided an identifier in the accountNo field of the originating Paylink Token Request;
3 indicates that the Cardholder Account with the identifier given by the accountNo field in the originating Paylink Token Request was updated with cardholder details such as the billing address and postal code submitted to Paylink 3 by the Customer using the Payment Form;

indicates that the Cardholder Account with the identifier given by the accountNo field in the originating Paylink Token Request was deleted;

This result code is not usually generated in the context of a transaction progressed using the Payment Form.

5 indicates that the Cardholder Account with the identifier given by the accountNo field in the originating Paylink Token Request.


The cac_id field contains the identifier of the Cardholder Account associated with the transaction.

transaction Response Digests

string (deprecated - md5 is known to be broken)

The digest field contains the results of an MD5 Hash Function applied to a subset of fields in the transaction Processing Response encoded as a Base64 string. The digest comprises the following parameters

  • authcode
  • amount
  • errorcode
  • merchantid
  • transno
  • identifier
  • licencekey


This field is deprecated as MD5 is known to be broken. Please use sha256 instead.



The sha1 field contains the results of a SHA1 Hash Function applied to a subset of fields in the transaction Processing Response encoded as a Base64 string. The digest comprises the following parameters

  • authcode
  • amount
  • errorcode
  • merchantid
  • transno
  • identifier
  • licencekey

Although SHA1 is still in wide use, it is ending the end of its life time, it is therefore recommended to use sha256 in preference.



The sha256 field contains the results of a SHA256 Hash Function applied to a subset of fields in the transaction Processing Response encoded as a Base64 string. The digest comprises the following parameters

  • authcode
  • amount
  • errorcode
  • merchantid
  • transno
  • identifier
  • licencekey

Handling the Digest

A digest is used to trust the integrity of the returned data. This is performed by concatenating fields of the response with additional information not present in the response data. To handle a digest

  1. concatenate the following response fields, in order  authcodeamounterrorcodemerchantidtransnoidentifierlicencekey
  2. apply through the hash function
  3. encode the byte array result from the hash function as a base64 string
  4. compare the generated value to the value returned by Paylink
  5. if the both digests are the same, the integrity of the data is correct
  6. if the digests differ, the data should be considered as incorrect. It is up to your application whether to accept the result at this time

To test the digest, use the values "A12345", "55731", "001", "12345", "2074", "os11a3v0il9f7iqfos765o1lh21250232646", "2Y9000000007" which result in a digest values of. For instance 

var x = "A1234555731001123452074os11a3v0il9f7iqfos765o1lh212502326462Y9000000007";
// H is a digest function such as SHA-256
var digestMatched = H(x) == "digest-value"
Algorithm Example Value
MD5 6/6eA4PcNekKGUfhfjRvtw== 
SHA-1 vO3FEspL0I0vBmCtbzR6uz5eJIE=
SHA-256 VYcQXQf7l78VG52QRkCgBlhVCzTE/ztAiYPlJXaQzYQ=

Algorithm Usage

Paylink supports MD5, SHA-1 and SHA-256. Both MD5 and SHA-1 are no longer considered secure. CityPay therefore recommend checking the SHA-256 digest value returned within the sha256 parameter.

Postback Handling

On processing a Transaction Request, Paylink will optionally perform a HTTP POST operation to the provided Postback URL. The body of the POST call contains a  Transaction Response  represented by the content-type of the originating call (JSON, XML, URL). A postback is a pseudonym for a Webhook.

To accept Postback calls, the Merchant should optionally configure their firewall to accept HTTP or HTTPS addresses from our production IP addresses of and as appropriate.

A Postback does contain integrity information which should also be checked to confirm that it is sent from a valid source.



    "sha1": "+Yz7zrgtzI4AN1b9UOa7th2u+/4=",
    "cardScheme": "Visa Debit",
    "expYear": 2020,
    "authenticationResult": "?",
    "CSCResponse": "M",
    "digest": "BxNq3NffJGzVfqFLYfjm+w==",
    "email": "",
    "identifier": "shop_12345",
    "firstname": "Joe",
    "AVSResponse": "M",
    "cavv": "",
    "postcode": "JE3 1ZZ",
    "result": 1,
    "datetime": "2018-02-28T09:02:51.603Z",
    "errormessage": "Accepted Transaction",
    "country": "GB",
    "amount": 8192,
    "sha256": "qLYMh02W+Wjg1pN2r/TV8Al+YlcLwLn8exotfNYdRFA=",
    "maskedPan": "475117******5712",
    "lastname": "Smith",
    "expMonth": 11,
    "cac": 0,
    "status": "O",
    "errorid": "000",
    "currency": "GBP",
    "address": "1 street",
    "errorcode": "000",
    "mode": "live",
    "authcode": "460190",
    "cardSchemeId": "VD",
    "eci": "7",
    "title": "",
    "authorised": "true",
    "cac_id": "",
    "transno": 271696,
    "merchantid": 12345678


An Xml packet is wrapped in a paylinkTransactionResult element.

    <CSCResponse> </CSCResponse>
    <AVSResponse> </AVSResponse>
    <postcode>JE2 3NT</postcode>
    <errormessage>Test Transaction</errormessage>
    <address>la rue de home</address>


Providing a Postback URL

A URL can be provided within the setup of your account and becomes the default URL. If a postback value is supplied in the Token Request, it will override the stored value. Should a value of none be supplied in the Token Request, no postback will be performed. The determination of whether a postback should be sent is performed on a transaction by transaction basis.

A URL can only be on ports HTTP 80 and HTTPS 443. This is due to PCI firewall compliance. If you wish to utilise multiple applications or use a different port, we recommend reverse proxying your calls via Apache or Nginx.

A URL likewise cannot be a local address and must be accessible across the Internet from our payments cloud. If you are developing an integration and testing Postback calls, you will need to setup firewall rules and allow a HTTP(S) endpoint to reach your development servers.

Postback Delivery Options

A Postback may be delivered at different points of the lifecycle of a transaction. If a transaction is authorised, you can expect a post back to be sent. A postback may be withheld such that, if a transaction is processed and either rejected or declined, Paylink will allow the cardholder to retry a different card or correct their values. Therefore a further attempt is made against the Paylink session with 1 or more transaction entries generated for the cardholder to reach payment. From an ordering perspective you will only want to know whether the transaction has been approved or not, therefore the last result is delivered. We determine what to deliver based on successful authorisation or timeout of the token. 

Connection Settings

We recommend your store is hosted behind a secure site using HTTPS. Paylink will accept all certificate authorities as standardised by Oracle's Java runtime. If you are developing your site or have an untrusted certificate authority, Paylink can be configured to trust all authorities. This is a configurable option and is not recommended however we understand for testing purposes it may be necessary to allow this setting.

Paylink will attempt a Postback and require a connection within 10 seconds. Once connected it will also wait for a response for 10 seconds. If we are unable to determine that the Postback has been received then the Postback is marked as failed.

Postback Response Handling

To confirm the Postback has been received by your servers, we expect a 20X response i.e. 200 OK to be returned. 

Strategy for Synchronization

A Postback call may be configured to be synchronous or asynchronous (default). 

Synchronous Postback 

If the Postback is synchronous, Paylink will execute the Postback before any response is delivered to the Customer's Browser. This ensures that the information has been delivered to your site before the result is presented to the Card Holder. The Postback call is attempted by default only once. This is to ensure that Paylink can respond to the Customer Browser within a reasonable period of time. Paylink however can be configured to retry. 

If we are unable to retrieve a response in this time period Paylink may

  1. Allow the transaction to continue but move the Postback to a background process which will retry asynchronously; or
  2. Email out a failure message

Asynchronous Postback

If the Postback is asynchronous, Paylink will execute the Postback in a background process. resulting in a faster user experience. The Postback call may be received by the Merchant Application an arbitrary period of time after the Transaction was concluded. While the actual period of time between the provision of a response is likely to be relatively small, a Merchant Application that uses asynchronous PostBack calls should be implemented to avoid reliance on the outcome of the Transaction until the Postback call is actually received.

In an asynchronous mode, a Postback is queued for delivery and may retry up to 10 times (configurable). A retry will be attempted every minute for the first 3 attempts, every 15 minutes for the next 3 attempts and every hour for every consequential retry.

Redirection Handling

Redirection is optional. If no redirection is provided Paylink will display a notice of the transaction result to the end user and no further action will be necessary other than closing the browser.

Once a transaction has processed, the browser can be redirected back to the merchant's store, within the Paylink API this is known as a redirect. A redirection may depend on whether the transaction result is successful or failed. Likewise you are able to configure a redirection URL on each token request or a default value that may be configured store wide. The default is to have no redirection.

A redirection from Paylink is performed via a HTTP POST application/x-www-form-urlencoded rather than a HTTP 302 redirection. This enables Paylink to send data in the redirection in a POST call. Optionally a URL may be prefixed with a verb such as "GET:" where the redirection process will enforce a GET call. For instance

A default redirection simply provides a URL

{ "redirect_success": "", "redirect_failure": "" }

whilst an enforced GET call can be preceded

{ "redirect_success": "GET:", "redirect_failure": "GET:" }

A Merchant Store that relies on receiving the result of the transaction through redirection in preference to a post back should be aware that –

  1. Customer Browser Redirection is unreliable : The Customer may close the browser, or a network failure may occur immediately or before being redirected to a redirection URL. In such cases, the Merchant Application will not receive an update of the status of the transaction, despite the fact that it may have been successful.
  2. Status information flow depends on compliant Customer behaviour : This means that the Merchant Application only receives status updates when the Customer Browser is redirected either automatically, or by requiring the user to click a button on the Payment Form. 

If the Customer Browser Redirection URL refers to an unencrypted protocol such as HTTP, the Customer Browser is likely to display a warning that they are moving from a secure, encrypted connection to an unsecured connection. This is a by-product of the redirection being performed as a POST operation. To ensure that the user experience is as seamless as possible, it is recommended that Merchant Applications use an encrypted protocol such as HTTPS.

Redirection Payload

If a transaction has been configured for redirection, Transaction Response data may optionally be including within a HTTP POST call, with the following considerations

  1. it is feasible that the payload data may not be genuine, and data should be validated using a SHA-2 digest. 
  2. data will optionally be returned in success or failure results
  3. the redirection data will only be provided once the transaction is concluded. 
    1. the Content-Type entity header of the POST operation will be set to application/x-www-form-urlencoded it is not currently capable of performing JSON or XML data redirections
    2. the payload data will be URL encoded regardless of the request content-type

Using the Paylink Simulator

Please note that the Paylink simulator is causing problems with versions 3.1.x of Paylink, we are hoping to get an update out soon on the 3.2.x release.


Paylink includes a simulator which allows you to test post backs and redirects against test transactions. To use the simulator set the payment request test parameter to simulator .

You will be presented a page with a warning stating that you are using the simulator. 

API Config

The page will initially display a tab asking you to process an authorisation. First though, we need to check that Paylink has received and configured the session against our parameters.

Select the tab header for "API Config". You will notice that details sent in the API are displayed as configured values in the API. Complex objects such as the Card Holder details are displayed in JSON format for inspection. 

The redirection or POSTback URLs are shown with the source of the configuration. You may see

"ApiCall' - the url was defined via the API 
"StoreConfig" - the url was defined in a configuration on our systems
"Default" - the url was taken from a default setting, normally inherited. This for example may be the default redirect parameter in preference to the success or failure url parameters.
"Simulator" - the url was provided directly by the simulator (you can change this url for testing) 


The JSON API config tab differs by showing the full packet of data that is used to configure Paylink under the hood. Whilst this is the same set of data, it is useful to interpret how Paylink will behave while performing integration testing.

To run a test transaction move back to the Process Auth tab.

Process Auth

On the process auth tab, we load dummy card data into the transaction and forward a transaction in real time to the authorisation test server. This simulates a live transaction however a "test" authorisation is enforced.

Once successfully processed, you should see a message stating that the transaction was authorised and the error code result message. Data is stored within the page for inspection and allows you to view the authorisation data as seen by the Paylink page. 

Inspect Result

The inspect result is available if a transaction has been processed and will display the outcome of the test transaction. This data can be used as an example of the data sent back for a POSTback call or a redirection. 

Redirection Testing

Once data is returned you can run sample redirects between the Paylink engine and your server. Redirects are performed once a transaction has been authorised to return the user back to your store (redirect_success). If a user presses cancel or if a user's transaction is declined and they do not wish to proceed, the user is redirected to the redirect_failure url.

The simulator allows you to edit the API values below for testing during your session.

Clicking on the run modal redirect test will show a modal dialog and will allow multiple redirection tests to be performed for your integration testing

If you wish to edit the URL for testing, you may click on each URL to edit the value as required.

Postback Testing

Once data is returned you can run sample postback tests between the Paylink engine and your server. The simulator allows you to edit this value below if you wish to forward a test elsewhere.

A dialog will display illustrating the postback call's result, 200 here being HTTP 200 OK.

Email Testing

Once data is returned you can test the email functionality of the account by sending a test customer email or merchant email based on the transaction result. To use, simply enter the required email address to receive the configured email for your account.

Our logging method returns, in brackets -

ME - if a Merchant Email
CE - if a Customer Email

followed by the result i.e. ...Email Sent to ...

If you request that emails are bypassed in the API or Merchant configuration, you will notice a result similar to [ME] ...Bypassed. 


Paylink Notifications and Messaging

Email Handling

Paylink will optionally forward an email to a merchant email address as a notification and/or a customer email address as a receipt.

Emails are generated in multipart/alternative format containing both HTML and Plain Text MultiPart messages. Whilst we monitor our email platform for bounced messages, we cannot guarantee email delivery and it therefore should be used as a notification process rather than reliance on a payment being made.

Merchant Notification Email

A merchant notification email is optionally sent on approval of a transaction. It may also be configured to forward an email on expiration of a non processed transaction.

An example email is provided below

Emails will also forward any custom values send through the Paylink engine to allow help desk operators to identify internal information related to the transaction.

Customer Email Receipt

A customer receipt may be sent on completion of a transaction when certain conditions are met

  1. Your service is configured to send card holder emails
  2. The customer email option is not bypassed (using config.options = BYPASS_CUSTOMER_EMAIL)
  3. A valid RFC822 email address is provided in the bill to address (this may be enforced on form validation)

By default, an email is sent from CityPay Transaction <> to ensure that our email is delivered via our email policies, including Sender Policy Framework (SPF) and DKIM signatures. On setup of your account you will also be required to set a support email address which is then set in the Reply-To header of the email.

Should you wish to tailor the email sent or switch off this functionality, please consult your account manager.

An example email is provided below. 

SMS Notifications

Paylink supports SMS notifications as a licensing option. An SMS may be sent to the cardholder should the following conditions be met

  1. A valid SMS licence is included (additional fees may be applied)
  2. A valid mobile number is supplied in the billing details and meets the E.164 format specifications. The format is internationally standardised and provides the relevant information to route messages globally.

An SMS message is limited to 153 characters.


Paylink is able to integrate with other mechanisms such as Slack or HipChat. If you are interested in this feature, please consult your account manager.

Paylink 3 Branding Guide

Paylink's engine works by a series of renderers which determine how the page is finally rendered to the user. We have a primary form for use called 'main' which is also the default form. This form uses Cascading Style Sheets and JavaScript (with JQuery) for rendering of the main elements of the form and for functionality. Our CSS implementation is based on Twitter's Bootstrap Version 3. The implementation has been restricted to core uses within Paylink to limit download speed.

CityPay allows the Merchant to customise the appearance of the main Payment Form by supplying a cascading style sheet ("CSS") for the Transaction using the Token Request. Accordingly, a Merchant Applicant can be customised generally, or for specific Transactions. To enable a customer style sheet, specify the merch_branding parameter set to the URL of an appropriate style sheet.

A custom style sheet is situated after the main Paylink CSS file allowing for extensive control of the payment page.

The implementation of Paylink is subject to change from time to time to enhance functionality or in response to external requirements. The Company cannot accept responsibility for the appearance or function of the Merchant Application in the event of such changes being made. Wherever possible the Company will adhere to the specification provided; and shall announce any anticipated changes to the specification as appropriate.

Unfortunately CityPay does not yet host the style sheet or images on your behalf however there is limitation on hosting the style sheet on your website along with any images referenced for example by using background-image('your url'). Style sheets should be hosted on a secure server to prevent browsers notifying the user that non secured content is loaded. 

CSS Reference


CSS Class or ID



Section provides the card scheme logos for view. The logos are required to be presented on a white background to be in line with the card scheme marketing and branding guidelines


The main body of the application which contains text for help pages or the web form for the payment application. This section contains information regarding the transaction being processed or information responding back on the progress to the merchant.


The footer of the page which contains copyright information about the page and support information. The area may have an image set in the background.

div#paylinkForm The main form entry for Paylink


A header section which may contain background images or logos.

div#paylinkMenu The menu area for links to information about the page.


The main page division which identifies the complete Paylink page. The Paylink page wraps all Paylink content.

div#paylinkPayInfo Area which is designated to information regarding the payment
div#productDescription Contains a description on the payment that is being performed



Advanced Paylink Topics

Paylink also supports 

  1. Surcharging Support in Paylink
  2. Cardholder Account Functionality in Paylink

  3. Pre-Authorisation Support in Paylink

QR Codes

Paylink 3 allows integrators to forward the Url to the user as a generated qr-code. Once the token has been successfully created, the url format returned is where mid is an encoded version of your processing merchant account and token is a randomised string unique to your merchant account. To access a QR code, simply take the url and append /qrcode.png after the token. It will also create a gif image if required by appending /qrcode.gif.

The QR-code Api has some additional functions which can be ammended by using http query string parameters. This allows you to control the size and format of the barcode.

Parameter Data Type Default Description
type string qrcode

Specifies the type of barcode to produce. As we are encoding Urls we only support the following types

  • qrcode
  • datamatrix
h int 256 Specifies the height of the image generated a minimum of 32 pixels up to a maximum of 512 pixels
w int 256 Specifies the width of the image generated a minimum of 32 pixels up to a maximum of 512 pixels


QR Codes can be used for printed material such as invoices or advertising material as well as emails and electronic marketing. This allows for payments to be accessible from more products not just your website.


In regards to security of the QRCode, the token generated is considered an offer for a card holder to take payment. No card data or sensitive information is linked to this QR code. Should multiple users link to Paylink 3 via the code, they will both have independent access to Paylink.  

Setting Up

When creating a Paylink token, you are able to specify an expiry time in seconds. It is recommended to setup a long period of time i.e. 30 days in which the customer has the ability to pay. Paylink will notify a specified post back Url when either the customer has paid for the goods or the transaction has timed out. Should the transaction time out and the customer then attempt to pay, the transaction will display on screen as expired. 

Surcharging Support in Paylink 3

Paylink allows the Merchant to apply a surcharge to transactions depending on the card provided by the Customer. Surcharges may be applied as a fixed rate amount i.e. £0.50 or a percentage rate applied such as 2.5%.

If you wish to configure surcharging, please contact your support representative.

Surcharging Extensions to the Response

A response will include 

  1. amount specifies an integer of the amount ultimately processed, inclusive of the surcharge expressed in the lowest denomination
  2. initial_amount specifies the original amount specified in the originating token request, expressed in the lowest denomination
  3. surcharge specifies the decimal value of the rate in which the surcharge was applied for instance if the rate is 1.5% the value would be 1.5, if the rate is fixed at 0.25, the value would be 0.25

  4. surcharge_calc specifies the calculation used, possible values are % for percentage calculations and + for fixed rate calculations

Cardholder Account Functionality in Paylink 3

Paylink provides cardholder account support for referencing a store payment card details. This can be used to facilitate discrete bill payments and subscription style payments made under the continuing authority of the Customer. Paylink provides support for the acquisition and updating of payment card and cardholder information using the hosted Payment Form.

The Paylink API allows Merchant Applications to

  1. specify, on an individual transaction basis, whether a Cardholder Account is to be created when a transaction is successfully authorised; and
  2. obtain updated payment card information for use with a particular Cardholder Account.

To enhance Paylink to create card holder accounts, your account will need to be setup to accept this option. 

A cardholder account is identified using an account number parameter accountNo which is used to reference the account once created. The account number is within the bounds of your Client account allowing multiple merchant ids to be used against a single card holder account. Should a Transaction, on processing, be found to match an existing account, the transaction will be marked against that account. Should the card details have changed, these values are also updated.

Transactions initiated using the Paylink Payment Form are processed and coded as e-commerce transactions which provides for full validation of the payment card holder using 3D-Secure, CSC and AVS. Subsequent transactions are ordinarily coded as continuing authority transactions using batch processing through the CityPay API .

To process payments under using the Cardholder Account features of Paylink, the Merchant must obtain the prior agreement of the relevant Acquirer to allow the Merchant to process transactions subject to continuing authority. Additionally, it is recommended that the Merchant Application expressly obtains the consent of the Customer to be able to perform transactions under continuing authority, and to provide a mechanism for resolving disputes to avoid unnecessary chargeback events.

Enabling Card Holder Account Transactions

This can be performed by contacting your support representative. Once you have been notified that this has been enabled, the following options are programmable by your API integration.

  1. construct the Token Request in accordance with the basic integration
  2. obtain and record prior consent of the Customer to process the Transaction associated with the Token Request, and future transactions under continuing authority;
  3. specify the config.options field and include the option "CREATE_CAC_ACCOUNT_ON_AUTHORISATION "
  4. add the accountNo field to individually reference the Cardholder Account used
  5. optionally specify the firstName of the account holder;
  6. optionally specify the lastName of the account holder;

Card Holder Account Extensions to the Response

  1. if cac is  equal to 0 – no action is carried out
  2. if cac is equal to 1 – an account has been loaded and processed
  3. if cac is equal to 2 – an account was created using the value in the accountNo field
  4. if cac is equal to 3 – an account was updated recording any change of the billing address, the expiry date or card number
  5. if cac is equal to 4 – the account was deleted (Paylink does not support this method)
  6. if cac is equal to 5 – the account was auto created based on the identifier (configurable)

Pre-Authorisation Support in Paylink 3

Paylink supports pre-authorisation processes that involve

  1. an initial pre-authorisation of a Transaction, marked as the requested amount;
  2. receipt of a message indicating the success or failure of the pre-authorised Transaction;
  3. a subsequent completion or cancellation of the transaction via the CityPay API . Note that the completion command may increase or decrease the final amount.

Pre-authorised Transaction support is typically required for Merchants that require situations where the price may not be final, or there is a risk that the particular resource to be supplied to the customer may not in fact be supplied due to ordering, technical or communications failure. A pre-authorisation requires a completion or cancellation request to close the transaction. This should be completed within 7 days to ensure no additional fees are applied by MasterCard. We mark the transaction as an estimated amount which complies with the MasterCard mandate for Pre-Authorisation reservations and on completion of the transaction, an optional final actual amount can be set.

Pre-authorised Transaction support is required to be activated on your account and may be forced to pre-auth by default.

Requests into Paylink allow for configuration to bypass or enforce rules to ensure that you can pre-authorise only when required. To enforce a pre-auth, set the configuration value under config/options to include BYPASS_PREAUTH or ENFORCE_PREAUTH.

In all respects, a pre-authorised transaction is the same as a standard authorisation apart from the status field will be returned as 'P' for 'PreAuth'.

Paylink Integrations

Programming Language Examples

3rd Party Integrations

Invoice payment integration

Shopping Cart Examples

Paylink provides a full integration API however CityPay have plugins available for key shopping carts which allow your site to use Paylink will little or no integration.

+44 (0)1534 884000