Paylink-v2 Single Page Paylink 2


Paylink is a fast, secure and easy to use online payment form system. Paylink makes online e-commerce safer by handling the card payment process direct with the card holder and the processing bank. Merchants who are looking for an easy to use 3d secure enabled payment system will find that there is no additional integration required to use 3d secure as this is completely seamlessly integrated into the Paylink application

For integration of e-commerce systems, Paylink provides a reliable hosted payment system that does not require the merchant to setup secure forms or secure servers for handling payment requests. Merchants can easily use their existing e-commerce system/store and Merchants can simply forward a token of data for processing and the Paylink system will communicate direct to your customers. The Paylink system will forward a response from the completed payment for your systems to deal with accordingly.


  • Paylink provides a simple and effective way of connecting your e-commerce store with CityPay.
  • Payment processing is handled by CityPay's secure web servers adding security and confidence to your shoppers.
  • Paylink responds back to your systems in easy to integrate methods so you may know instantly what the result of a transaction is.
  • 3D-Secure is available within the application without any difficult MPI integration, allowing for immediate Verified by Visa and MasterCard SecureCode processing.
  • Customisation may be performed on the secure payment form.
  • No advanced development skills required to integrate.

There are 2 options for integrating with Paylink.

  1. Use this guide for integrating your site/shopping cart into the Paylink system. A basic knowledge of HTML is required or for advanced integration, a server side scripting language such as Java, PHP, C#. This document will provide examples to aid with your integration to ensure that the information passed between your site and Paylink is successful.
  2. Use an existing integrated shopping card/software. CityPay have teamed with various e-commerce providers that supply direct integration with the Paylink system.

Technical Requirements

To integrate with CityPay using Paylink, you will need:

  1. CityPay merchant id.
  2. Knowledge of HTML forms.
  3. Advanced integrations for shopping cart integration will require web development knowledge including server side scripting.

How does Paylink work?

  1. The shopper chooses the items to purchase on your website and populates the items into a shopping basket (a direct request without a basket is also possible such as bill payments).
  2. The shopper chooses to pay using a credit card and presses submit on a HTML form which sends a HTTP POST request to the Paylink servers. Please note that it is also possible to use JavaScript to redirect to Paylink by automating a form submission. Which ever was used, this should always be a POST requests. GET requests will not be accepted.
  3. The shopper completes the secure online payment process using the Paylink payment process
  4. The transaction is submitted for processing, passing through validation including 3d secure authentication, fraud checking and then on to the acquiring bank. (Fraud checking and 3D-Secure is dependant on your account settings)
  5. Authorisation is obtained from the bank and entered into the CityPay database for subsequent settlement and reporting. Where CSC and AVS matching is required the transaction result is checked and accepted or declined based on the outcome.
  6. The result is displayed to the shopper. If rejected or declined, an option to reprocess is enabled using a different card or amending the details.
  7. The result is returned to the merchant by returning the browser to the merchant's site. At this stage a HTTP "postback" to a Merchant URL is also performed and an email notification is sent to the merchant email address supplied with the request.

Paylink Walk Through

Initial Request

An initial request is forwarded to the Paylink application as per this specification. Paylink validates the request data and if valid displays a user interface for the session. The user interface is dependent on the user-agent. This includes a simple user interface which collects data or a more advanced web 2.0 interface which checks the bin ranges of the first 6 digits of the card number for required parameters, easing the process for the end user.

Should the request be invalid, an error message is displayed by Paylink with a message for the merchant integrating and also a message for a customer in case of a problematic request once live.

The user must first select the card type they wish to process with. The types of Cards your account can accept is controlled by CityPay and your Acquiring bank.

Card Selection


Once the user has selected a card, they are required to enter their card details.


While entering the card number, the user interface recognises the bin range (first 6 digits) and calculates what is required of the card for data entry. This allows for immediate feedback to the card holder that we are expecting 3 digits from a card security code or an issue number is required for the card.

Should the card number be different to that selected then, and if your account can accept the new range, the user interface displays the recognised logo of the card scheme and continues unaffected. Should your account not accept the bin range a screen will be displayed showing that the card is unaccepted.

Completion of Card Holder details

Once all details are collected, the user will click on the "Process Payment" button.

Paylink processing screen

On submission, the user interface will feedback to the user that the transaction is processing. The user interface will not allow for duplicate processing due to processing being controlled by a separate process. The web application checks for the state of a transaction against this process, allowing for a user to refresh their browser and not affect the processing.

The screen as shown below will poll the server to see if the transaction is ready.

3-D Secure Processing

For 3-D Secure transactions, the ACS is shown either in an embedded or in-line state within the Paylink application, allowing for a seamless integration of 3d secure. A live ACS will be provided by the card issuing bank.

An embedded ACS will appear in an iframe retaining the user on the paylink site. The Paylink application is able to determine if the browser can display iframes before embedding.

The recommended and default rendering of the ACS however is inline to the application. This means that the complete browser window will be forwarded to the ACS. This allows the card holder to trust the ACS site and also confirm the ACS validity through EV TLS.

After processing of a 3d secure transaction, the user will be returned to the processing screen awaiting full authorisation.

Authorised transaction

Should the transaction be authorised, an end screen is displayed showing the result of the transaction. Users are then advised to return to the store. This will happen automatically after 15 seconds or a value otherwise provided in the integration.

Declined transaction

Should the transaction be declined or rejected, a screen is displayed showing the resultant message such as declined or any relevant error message. The user is then given the option to start again by using another card or correcting details of the transaction or to return to the store.

Getting Started

CityPay will supply you with a Client ID and a Merchant ID for each account you wish to process using.

Client ID

Your Client ID is issued as your individual ID with CityPay. This ID allows you to login to the CityPay Merchant Panel and should be used in correspondence with CityPay.

Merchant ID

Your Merchant ID is issued by CityPay and directly maps to at least one bank merchant id. This id should not be confused with the id for your bank. The merchant ID is used to send payment information to CityPay.

Merchant Control Panel Access Information

You will be provided with access information to the CityPay Merchant Control Panel (MCP) including URL, username and a temporary password. You will be required to change your password when you first login. 

The control panel will allow you to report and manage your account.

When a customer is ready to checkout from your store, you should provide a HTML form or link that submits the required purchase information to the CityPay Paylink server. You can use whatever technology you desire however it is recommended that the page before submitting is kept to a standard HTML form.

Requests should be forward to the URL

Simple Html Form Integration

To pass information about a purchase to Paylink for payment processing, you must create a standard HTML form on your website encoded with application/x-www-form-urlencoded which will POST the required data.

Example Payment Form

Example Payment Form
<form action="" method="POST">
    <input type="hidden" name="merchantid" value="12345" />
    <input type="hidden" name="amount" value="19975" />
    <input type="hidden" name="identifier" value="YOURID" />
    <input type="hidden" name="email" value="merchant email address for payment notification" />
    <input type="hidden" name="productInformation" value="Product information regarding the payment" />
    <input type="submit" value="Pay By Card&raquo;" />

You will need to publish a page on your website similar to the example above.

You do not need to host the form on a secure server as all sensitive information is processed and obtained on the CityPay secure server. Paylink will still integrate with secure servers if you prefer to keep the checkout process secure.

When a customer is ready to pay, the customer presses a button on your site which when clicked submits the information for payment to the CityPay secure server which delivers the Paylink application. The form submission indicates a single purchase and a single total amount.

It is recommended to use a process which hides the data being sent, preventing the data being readily available using the view source feature of the browser. Paylink offers to options;

  1. A base64/xor encoding of the data
  2. A base64/AES cipher text of the data

Base64/XOR data encoding

As form details are displayed in your website source, CityPay also offer the ability to encode data between your site and Paylink using a tokenised method. This is recommended over the basic integration method to reduce the potential for tampering with the data. This method is not secure due to the simplicity of the encoding process used, for a more secure version use the AES cipher.

To be able to provide a token based integration method, integrators will provide all parameters tokenized into a simple password based xor and base64 token encoding system. Code is available in many languages for integrators to use. An example is included later in the document.

Integrators should follow the same parameter requirements as per a standard form integration however this encodes all http parameters such as: amount=9950&identifier=yourident into an xor and base64 encoded token, the end encoded string is provided as a parameter named "token".

The xor process uses the merchant licence key as the encryptor which is not known within the request.

The merchantid however must be still provided as a request parameter to ensure we are able to determine the account this is encoded for.

Example Encoded Payment Form

Example Encoded Payment Form
<form action="" method="POST">
	<input type="hidden" name="merchantid" value="12345" />
	<input type="hidden" name="token" value="GgkEFlhOFw8JGwZDXx4...VBApcdhMYGB0MQQ==" />
	<input type="submit" value="Pay By Card&raquo;" />

When submitted a request that is xor encoded, the response data will be xor encoded as a token response parameter. A post back however will remain plain text

AES Encrypted Request

Although data is encrypted to our server, data is available within the view source of the browser. For a more secure solution, it is recommended to encrypt the contents of the payment request using strong encryption.

A payment request may be forwarded by encrypting the request parameters as a value. This data should be sent as a parameter called ciphertext.

Example Encoded Payments Form

Example Encoded Payment Form
<form action="" method="POST">
	<input type="hidden" name="merchantid" value="12345" />
	<input type="hidden" name="ciphertext" value="ZDXx4GgkEFlhOFw8JGw...BApcdhMYGB0MQVA==" />
	<input type="submit" value="Pay By Card&raquo;" />

You will require the following

  1. Your merchant id
  2. Your merchant licence key
  3. A salt provided by CityPay for each merchant account. The salt is linked to your licence key and will change on a licence key change.

The cipher algorithm

  1. Password based, in accordance with RFC2898 (PKCS#5 V2.0 Scheme 2). Your merchant licence key is your password.
  2. SHA-1 is used for the H-MAC calculation function
  3. Salt is provided to you in base64 encoding and should be kept secret.
  4. Iteration count is 10
  5. Key size is 256
  6. IV size is 128
  7. uses CBC block cipher
  8. uses PKCS#7 padding
  9. the resultant cipher is base64 encoded

NOTE: You are able to forward your own base64 salt as the parameter "random". You should encrypt the cipher text using this salt and send the cipher text base64 encoded as the parameter "ciphertext". Sending no random parameter will result in the default salts being used which are generated using internal logic to CityPay.

On the response/postback only the ciphertext is returned using your original salt.

The following examples illustrate the values that should be produced. To aid in debugging, the following values are determined by this process:








Java Encryption Example

Java Encryption Example
private byte[] exampleEncryption() {

  byte[] password = "thisisapassword".getBytes("UTF-8");
  byte[] plaintext = "this is plaintext that is to be encrypted by the process".getBytes("UTF-8");
  byte[] salt = Base64.decodeBase64FromString("QF1aFl1wOVtQQCJoeGpubzVpfGhocnMzezxLJFFzT2Y=");

  // example using bouncy castle
  PKCS5S2ParametersGenerator generator = new PKCS5S2ParametersGenerator();
  generator.init(password, salt, 10);
  ParametersWithIV iv = (ParametersWithIV) generator.generateDerivedParameters(256, 128);

  RijndaelEngine engine = new RijndaelEngine();
  BufferedBlockCipher cipher = new PaddedBufferedBlockCipher(new CBCBlockCipher(engine));
  cipher.init(encrypt, iv);

  byte[] out = new byte[cipher.getOutputSize(in.length)];
  int outputLength = cipher.processBytes(in, 0, in.length, out, 0);
  outputLength += cipher.doFinal(out, outputLength);

  if (out.length == outputLength) { return out;}

  byte[] finalBytes = new byte[outputLength];
  System.arraycopy(out, 0, finalBytes, 0, outputLength);
  return finalBytes;

C# Encryption Example

C# Encryption Example
byte[] salt = Convert.FromBase64String("QF1aFl1wOVtQQCJoeGpubzVpfGhocnMzezxLJFFzT2Y=");
byte[] pass = Encoding.UTF8.GetBytes("thisisapassword");
byte[] plaintext = Encoding.UTF8.GetBytes("this is plaintext that is to be encrypted by the process");

Rfc2898DeriveBytes pkcs5 = new Rfc2898DeriveBytes(pass, salt, 10);
Rijndael aes = Rijndael.Create();
aes.Key = pkcs5.GetBytes(aes.KeySize / 8);
aes.IV = pkcs5.GetBytes(aes.BlockSize / 8);

// convert to ciphertext
MemoryStream ms = new MemoryStream();
CryptoStream cs = new CryptoStream(ms, aes.CreateEncryptor(), CryptoStreamMode.Write);
cs.Write(plaintext, 0, plaintext.Length);

// return the base64 version
return Convert.ToBase64String(ms.ToArray());

When sending an encrypted request, both the post back and redirect response data are encrypted using the ciphertext parameter. This will require decryption before obtaining the necessary data.

Paylink Payment Request Parameters

The following parameters are the basic parameters required for every purchase request.


Data Type






The merchant id issued by CityPay. Accounts that use multiple currencies may require multiple merchant ids.




The payment amount must be provided in the lowest unit of currency for the specific currency of the merchant, with a variable length to a maximum of 12 digits. No decimal points to be included. For example with USD $10.24 insert amount=1024




The identifier as set by the merchant. This field can be used to cross reference between the merchant's system and the CityPay system. The identifier can be used to lookup transactions in the system. The provided String must be between 5 and 50 ASCII characters




The email address to forward a confirmation email to. Please note that this is an email for merchant use and contains information about the transaction this should not be supplied to the shopper.




Information about the product that will be displayed back to the user. This information should be informative. The String must only be up to 50 ASCII characters




Provides the delay in seconds between redirecting from the confirmation page to your store. The default value is 7

Parameters provided are case-sensitive

Controlling the payment description

As an alternative to the productInformation field, you are able to provide the parameter productDescription. This will alow you to add text of your choice to the header of Paylink. 
Due to potential cross site scripting attacks into paylink, no html tags are permitted in this field.

Custom Parameters

You are able to create your own custom set of parameters that are passed through the Paylink system and displayed to the user for completion. Additional information such as "company" etc can be added to the site for input by the card holder.

In addition, custom parameters may be passed through the system and returned within the response mechanism. Any unregisted parameter may be used for a displayed field. A field value which should be hidden from the user and used purely for callback should be prefixed with either '_' or 'paylink_callback'. This value will remain in the user's Paylink session and never be rendered to screen.

Optional Parameters

The following parameters are in addition to the default parameter listed.


Data Type




You may pass the billing address of your customer through to the Paylink pages to save the user from completing their details



You may pass the billing postcode of your customer through to the Paylink pages to save the user from completing their details



You may pass the billing country of your customer through to the Paylink pages to save the user from completing their details



You may pass the customer name through to the Paylink pages to save the user from completing their details



You may pass the customer email address through to the Paylink pages to save the user from completing their details



For 3d secure transactions, you are provided with access to the CityPay merchant plug-in (MPI) which manages transactions through 3d secure authorisation. The subsequent access control server (ACS) may be shown embedded (iframe) or inline (as an entire page within the browser) within the page. A value of 1 will render the ACS inline and 0 embedded. The default value is inline.



You may run a test against Paylink at any point by setting a value as test = true. Other values will be live. You will notice that paylink is in test mode by a banner displaying test mode in the application. If no parameter is supplied the default is test=true.



The postback url for this request. The url may be provided to CityPay for configuration for the account however a request may override this by providing the parameter on the initial request.



The redirect URL for this request on completion or non completion of the transaction. If no alternative URL is provided to CityPay for configuration then CityPay will use the default Domain of the URL supplied for the account. However  we strongly recommend that you override this by providing the parameter on the initial request.



You may provide the ability to prevent users from entering data in certain fields. Supply multiple values to the lock value which specify the name of the field to lock. Such as locking the customerEmail and billing details, provide 4 parameters named 'lock' with the value set as the parameter name.

expireIn int

An optional value in seconds which can be provided to force a payment session to expire in a given period of time. i.e. a value of 900 would be 15 minutes.

Ordinarily sessions are maintained for 30 minutes from the last action that the user performed. This therefore could maintain the payment process over a longer than expected period should a card holder maintain session state.

Using this value forces Paylink to calculate an expiry point based on the time that the request was received. Should a request to Paylink be made from the same session (and the session still exist), Paylink will notify the user that their payment time has expired.

If no value or an invalid integer is supplied, the default session handling will be in place.


Example Field Locking

Example Field Locking
<input type="hidden" name="lock" value="customerEmail" />
<input type="hidden" name="lock" value="billToAddress" />
<input type="hidden" name="lock" value="billToPostcode" />
<input type="hidden" name="lock" value="billToCountry" />

Sending a Test Request

See  Testing Best Practices for further information

Using Pre-Auth with Paylink

Paylink can be configured using pre-authorisation allowing you to take payments which are not captured for settlement. Transactions will remain open until a corresponding completion or cancellation call is made. This may contain an amount that differs from the initial call.

The completion calls are made using other APIs other than Paylink.

Operational Policy Settings

Should you wish to bypass settings of your account, these can be provided using a bypass option. This should be provided as one or more option parameters. The following values are supported:




Will bypass any AVS postcode requirement


Will bypass any AVS address requirement


Will bypass any CSC requirement


Will bypass any 3DSecure requirement

These values are considered sensitive as it can drastically affect your fraud settings. It is therefore recommended to ensure your request is AES encrypted when using these options

In response from the processing of a transaction payment, there are two possible outcomes.

  1. The card holder has successfully completed and paid for the transaction; or
  2. The card holder has cancelled the transaction. In the instance of a declined payment request, the card holder has the option of processing using an alternative card.

In the second part, you cannot be guaranteed that the user will click cancel as they may also just leave the payment session without closing the payment.

The result of a transaction is returned to you through

  • Redirection
  • Postback
  • Email

Redirecting the user back to your store

As part of the return to your store, we supply result parameters that can be decoded and used to assess the transaction response. CityPay strongly discourage the sole use of this type of response as it is possible for a malicious user to tamper with the parameters.

Postback to a Private URL

Postback is a facility that allows a HTTP or HTTPS request to poll your server or shopping cart providing the result of the transaction. The post back is triggered when a transaction is cancelled or processed.

By using the post back feature you can confirm the integrity of the request by limiting the request to the production IP addresses. 

Merchants should configure their firewall to accept addresses from,

Post backs are limited to standard HTTP ports 80 and 443.

Postback API

CityPay uses the Postback API to inform you when a transaction has been authorised only. This is due to card holders potentially retrying a payment, using a different card or simply not proceeding with the transaction.

The Postback process sends data to your Postback URL which is configured by the CityPay Merchant Control Panel or overridden by an incoming parameter within the request. The returned data is returned as standard name/value pairs in a HTTP POST request. If a request was originally encoded using XOR encoding, the postback process will forward unencoded data.

If you wish that your URL is restricted by authorisation, the Postback process will retry an unauthorised request including the client id as the username and the merchant id as the password.

When CityPay contacts your URL and receives a 200 OK status code, CityPay accepts that the data has been successfully received. Should the callback URL be unavailable or a different HTTP status code is received, CityPay will attempt to resend the message for a total of 10 times before giving up. The system will retry every 20 minutes.
Responding to Postbacks

When receiving Postbacks from CityPay, the application should attempt to parse and process the information in the data.

To increase the security of a post back, it is recommended to wrap your service using TLS.

  1. If the application parses and processes the data successfully, the application should return a HTTP 200 response code which indicates that the POST request has succeeded. CityPay will not send any further callbacks for this response.
  2. If the application is unable to parse the data successfully, the application is required to return a HTTP response code other than 200 such as Client Errors 4xx or Server Error 5xx. This will indicate that an error has occurred. 

    On returning an error response code, CityPay will attempt to resend the notification for a short number of times. The application may terminate the request by responding a 200 OK response.

Fixed Postback

A Postback URL can be preset with your account so that the value is never exchanged over the initial request to Paylink.

Dynamic Postback

It is possible to change the postback URL on every purchase by using the paylink_postback parameter.

Emailing the response

An email notification is sent to you disclosing the details of the transaction processed including bespoke and callback parameters

Result Values

The response will contain the following list of values which will determine the outcome of your e-commerce product.


Data Type




The authorisation code as returned by the card issuer or acquiring bank for a successful transaction. Authorisation codes may contain alpha numeric characters and may be an empty String.



A Boolean definition that indicates that the transaction was authorised. Attention should be referenced to the AuthResult and Error code detailed determination of the result.



The amount of the transaction in the lowest denomination.



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



The identifier provided with the request which will match the identifier sent



Denotes the mode of the transaction by returning a live or test value.



An integer result that indicates the outcome of the transaction as specified in the table Authorisation Result Codes.



An error code associated with the transaction.



The error id appears in the format 000.000.000 which should be provided in correspondence with any support issues.



A text message relating to the result of the transaction. This field will return a String with detailed information on the outcome of a transaction, this field will also contain details concerning any errors that occur. Please consult the error code documentation for how to rectify and decode error messages.



The resulting transaction number, ordered incrementally with the MerchantID. Defaults to -99 for a test transaction or -1 for errors.



The result of the card security code checking.



The result of the avs checking.



MD5 hash of the response data. The digest is made up of the parameters:

  • auth code
  • amount
  • errorcode
  • merchantid
  • transno
  • identifier
  • licencekey



The card number masked using the recommended masking process of displaying the first 6 numbers which identify the bin range and the last 4 digits. All other digits are masked with an asterisk. For example 412312******2151.



The CAVV is a value derived by the Issuer during payment authentication that can provide evidence of payment authentication during an online purchase. If the transaction is authenticated, this value should be kept to receive chargeback protection.



The Electronic Commerce Indicator (ECI) indicates the level of security used when the Cardholder provided payment information to the Merchant. Possible ECI values are:

ECI=5. This Value is set when a transaction is Fully Authenticate using 3D Secure.

ECI=6: This value is set when an attempt is made to authenticate the Cardholder using 3D Secure, but the Card Issuer or Cardholder was not participating, or the Card Issuer ACS was not able to respond.

ECI=7: This value is set when payment authentication was unsuccessful or not attempted.



The result of an authentication process which determines whether authentication succeeded. This value is returned in response to a 3D Secure transaction. The following results are valid authentication results:

  • Authentication Successful (Y)
  • Authentication Failed (N)
  • Authentication could not be performed (U)
  • Attempts Processing Performed (A)

Encoded Response Token

If a request was originally encoded, the response data is returned as a parameter named "token" for decoding on your server side. The encoded token uses the reverse process as the encoded request of base64 decoding followed by an XOR of the decoded base64 using the licence key of the merchant account.

Error Codes

Error Codes are used to identify the result of a transaction, either successful, rejected or declined. The codes in their basic form contain an identity and a error message which provides more detailed instruction.

An exhaustive list of Error codes are available from  API Response & Error Codes

From time to time CityPay introduce new error codes, any current codes will remain intact and remain within their current scope. Please consult CityPay support for any further details regarding the use and terms of error codes.


The following AVS response codes as used by CityPay to determine result of processing using the Address Verification System.




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 CSC response codes determine the result of transactions processed using the Card Security Code fraud system.




No information


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


Authorisation Result Codes

The following authorisation codes are an exhaustive list and are required to cater for all transaction types, including e-commerce, chip and pin, MOTO and others. These values should be added to the application workflow when greater control of a terminal or application is required instead of the accepted value which is determined by the nature of these responses.






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


Validating the Digest

The digest is constructed using a hash of the concatenated values:

  • the authcode
  • the amount
  • the errorcode
  • the merchant id
  • the transaction number
  • the identifier
  • the licence key

Digests are available using the following algorithms

  • MD5 (deprecated)
  • SHA1 (deprecated)
  • SHA256

Older gateway APIs are in the progress of migrating to SHA-2.

Testing the Digest

You can test the digest using the values "A12345", "55731", "001", "12345", "2074", "os11a3v0il9f7iqfos765o1lh21250232646", "2Y9000000007" which result ina digest value of "6/6eA4PcNekKGUfhfjRvtw=="

Example C# Digest
StringBuilder sb = new StringBuilder(); 
string digest = 
Example Java Digest Generation
public String genDigest() { 
    MessageDigest digest = MessageDigest.getInstance("SHA-256"); 
    byte[] b = digest.digest(); 
    return Base64.encodeBase64ToString(b); 

Token Encryption using XOR Cipher

The XOR Cipher is a simple cipher which operates using a data input and a key which is constantly repeated. The cipher is used a a simple cross platform solution against tampering of data which travels via a user's browser.

Please note that the cipher is not used for the post back API as this is not part of the browser process.


Example Java XOR method
public static char[] xor(char[] data, char[] key) {
	CharArrayWriter w = new CharArrayWriter(data.length);
	if (data != null && key != null) {
		for (int dataIdx = 0, keyIdx = 0; dataIdx < data.length; dataIdx++, keyIdx++) {
			char xor = (char) (data[dataIdx] ^ key[keyIdx]);
			if (keyIdx == key.length - 1) {
				keyIdx = -1; // incremented on next call
	return w.toCharArray();

Once the XOR value is obtained, the data is then base64 encoded.


Example Unit Test
public void test() {
	char[] v = "name1=value1&name2=value2".toCharArray();
	char[] k = "thisisanencryptionKey".toCharArray();
	char[] xor = Xor.xor(v, k);
	assertEquals(v.length, xor.length);
	assertEquals("GgkEFlhOFw8JGwZDXx4VBApcdhMYGB0MQQ==", Base64.encodeBase64(new String(xor)));

To decipher a token, the opposite should be performed:

  • base64 decode the token
  • supply the decoded token to the xor method using the same key that encrypted the original token

Activating your account

To set your account live, please login to your merchant control panel and select the activate icon displayed for the required merchant id. This will inform CityPay support that you wish to go live who will then contact you to confirm that the account is made live.

Restricting the referrer

CityPay restricts users arriving at Paylink to be restricted by the HTTP referrer header value. The referrer header is provided as part of the HTTP/1.1 specifications so all conforming browsers should forward this information. Should no referrer information be presented such as the case of a direct request to Paylink, the application will display that an invalid request was requested (Error code P007).

The referral page should be submitted to CityPay for configuration. (This will shortly be configurable in your merchant panel). Please note that a global referrer may be provided such that if you expect transactions to come from multiple parts of your site, you may configure Paylink to accept all from a given host and directory. Such that all transactions are to be configured from and may simply provide to globally allow a request.

Please note that multiple URLs may be supplied

Please note that the referrer is not intended to be a secure mechanism that trusts where the transaction originated from as the referrer information may be easily forged. It is however a simple process to help reduce misconfiguration and produce a listing of systems configured to your Paylink configuration.

For the purpose of testing, an internal or local host address may also be supplied however this will restrict tests to your development area only.

CityPay offer merchants the ability to create an account for each processing customer and store the card details for future use. Features include:

  • Allows merchants to support and control subscription and instalment payments
  • Bill payments to credit cards such as Visa, MasterCard, Maestro, American Express, Diners.
  • Create and modify subscription accounts through the CityPay API or web based control panel
  • Control dynamic payment amounts through merchant controlled batches
  • Control fixed amount subscriptions through configurable scheduling rules
  • Transaction reporting and search capability
  • Payment notification triggering for both merchant and customer

Paylink allows merchants to request on an individual transaction basis whether a card holder account is created when a transaction is successfully authorised. The accounts are then initialised for use by other applications across the CityPay service structure allowing for repeat billing and batch processing of accounts.

Transactions in Paylink are processed and coded as e-commerce transactions including 3D-Secure, CSC and AVS allowing for full validation of the card holder. Transactions are consequently processed as continuous authority transactions by batch processing. Please note that the merchant account will need to support both for correct application of this service.


To enhance Paylink to create card holder accounts, your account will need to be setup to accept this option. 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.


Data Type






To enable a card holder account to be generated supply a HTTP request parameter of options=CREATE_CAC_ACCOUNT_ON_AUTHORISATION. This will enable the storage of data for this request only




To be able to tailor the account number for a card holder account, supply a value in this field. The value should be ASCII and a maximum of 20 characters. This account number is subsequently used for processing against this account.




The first name of the card holder




The last name of the card holder. The 2 name values differ to the card holder name as used by the Paylink processing network which should be entered by the card holder to resemble what is listed on their card.


To confirm that a card holder account has been created within the request, the response parameters will be decorated with the following parameters:


Data Type




The value of

  • 0 indicates that no action was performed
  • 1 that an account is loaded and processed (ordinarily this would not occur in Paylink)
  • 2 a card holder account was created successfully.
  • 3 a card holder account was updated correctly. This may happen if the account identifier is the same as a pre existing account
  • 4 an account is deleted (this would not occur in Paylink)
  • 5 an account was created successfully using the identifier (this is a configurable option)



Provides the value of the account id as provided by the accountNo request parameter.


Processing against a Card Holder Account.

Please note that you can't process against a CHA using the PayLink API.  You will need to submit a standard PayPOST API request constructed without card or address details. The addition of a CHA number is however mandatory to inform the API to process using that account.

+44 (0)1534 884000