Paylink-v2 Integration

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.

+44 (0)1534 884000