Paylink-v3 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;
+44 (0)1534 884000