CityPay Paylink

CityPay 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: CityPay Paylink caters for the entire payment process, including authorisation, payment notifications and validation.

Low latency: CityPay 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 modern web application that provides a fast, low latency user experience for the end customer.

Secure: CityPay Paylink uses the latest browser security models to protect merchant and customer data and is rigorously tested each time a new version is deployed. CityPay is a PCI Level 1 accredited service provider which streamlines your PCI accreditation process by indirectly handling sensitive cardholder data (CHD).

Flexible: CityPay Paylink is flexible by nature. It is responsive to the viewer's experience and offers various customisations.

3DSv2 Out of the Box: CityPay Paylink includes 3DS version 2 and provides frictionless and challenge-based flows. Authentication cardholder transactions for PSD2 enabled transactions.

Key Benefits

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

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.

Features

Data Representation

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

URL Based Payments

CityPay Paylink interacts with the Customer using a Payment Token embedded in a URL. Your application creates the token, calling the Paylink server /create process to generate the token. You can then present the generated URL to the cardholder via multiple methods, including HTTP redirection (GET or POST), a link on a page, SMS, email, pdf or QR Code.

CityPay 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 the configuration of the Payment Token Request or management configuration.

Notifications

Paylink can perform webhooks using an HTTP POST call to the Merchant Application known as a PostBack. If a customer does not make payment before the relevant Payment Token expires, Paylink 3 performs a PostBack to advise the Merchant Application that the appropriate Payment Token and Payment Transaction have expired.

User interface

The CityPay Paylink user interface has been developed with the following objectives in mind:

User-friendly: the user interface has been written to guide the user through the payment process logically and efficiently.

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 modern browsers and has plugins for different rendering engines. We use browserify to ensure compatibility with modern browsers.

Responsive design: CityPay Paylink built upon Bootstrap 5. The payment form will automatically scale to fit the screen area available to the customer's browser while maintaining a breadth of functionality.

Internationalisation: CityPay 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 from the Customer Browser.

Pragmatic error reporting

Under 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 implements comprehensive error management and reporting.

Auditing

CityPay 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 the user's seamless authentication experience. No further integration is required to run a seamless, authenticated transaction process, reducing exposure to fraudulent transactions.

Integration Testing

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

Custom Fields

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

Credential on File Support

Paylink supports storing account data, storing cardholder data, and allowing Merchants to process credential on file style transactions for subsequent charging.

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 may reflect the different transaction processing approaches adopted for credit and debit card transactions.

Security

We have designed CityPay 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 CityPay Paylink application is protected from any injection flaws by ensuring that all data is parameterised and input validation is performed before the application handles any data.

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

Cross Site Scripting: CityPay Paylink is protected against cross-site scripting ("XSS") attack vectors through several 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 can only 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 except 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 the latest security trends, and all of our servers are regularly patched, and vulnerability tested.

Sensitive Data Exposure: Cardholder 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. CityPay uses industry-standard strong encryption algorithms (AES256) throughout its operations and has adopted key management and rotation processes 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 as a session-based cookie when the Payment Token URL is first accessed. This cookie effectively binds 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 that allows us to validate any Payment Token before it arrives. As a server-side call generates the token, the merchant can trust the URL before forwarding the user for payment.

Technical overview

Payment processing is initiated by an API request from your servers to CityPay's token creation endpoint to generate a Paylink Token. This token is provided to you in the form of a URL

The Paylink service is a REST API over a TLSv1.2 channel for transmitting payment card data. Most HTTP clients can process TLSv1.2 and above; however, some legacy products may require specific configuration to communicate using TLSv1.2.

Data is exchanged using JSON, XML or URL encoded data allowing developers to integrate applications using various languages. We are working towards SDKs for fast developer integration.

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
2. Payment Form
   1. Paylink validates and authenticates the request and renders a Payment Form
   2. the Shopper completes the Payment Form using their browser
   3. the form is validated and processed with 3D-Secure and the CityPay acquiring network
   4. a post-back call is made by paylink to notify your application of the result
   5. Paylink generates a response which is displayed to the user
   6. the browser is transferred to the Merchant Application via redirection

Successful payment transaction control flow

1. if a redirectSuccess URL was supplied and a redirection delay has been specified, the payment form displays a dialog stating that the transaction was successful. After the delay or on the cardholder clicking on the redirect button, the Payment Form redirects the browser
2. if a redirectSuccess URL was supplied and no redirection delay has been specified, the payment form redirects the Customer Browser to the On Success URL immediately
3. if a redirectSuccess URL was not specified, the payment form displays a dialog stating that the was successful.

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 to be processed or
2. if a redirectFailure was specified, click on the return button to redirected the browser or
3. the cardholder closes the browser tab or window

Getting Started

As a pre-requisite to integrate with CityPay Paylink, you will need:

1. a CityPay ClientId. A client id is a top-level account which identifies you as a client on our systems. Each account may have multiple merchant accounts.
2. a CityPay Client Integration Licence Key. This key identifies your integration.
3. a CityPay MerchantId. To be able to process, you will need a merchant id. Each merchant id 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. For integrators, we will be able to offer test accounts.

Allowing Access

Before creating tokens, we will need to open access for your systems to process transactions. Access control is based on your IP address and can be configured as a single IP address, a subnet or a cloud service provider such as Amazon eu-west-1 or Google Cloud europe-west2. Requests that are disallowed will return a P007 error code. You will also require authenticated access provided by your Merchant Id and an Integration Licence Key within each request.

When setting up your account, please advise support to discuss your access requirements.

Recommended Integration Workflow

1. determine content type of call and add a HTTP request i.e. `Content-Type: application/json`
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 Paylink 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;

Paylink Token API Request

Constructing a Payment Request

Example Paylink Request

{
  "merchantId": 123456,
  "licenceKey": "ASCnrtsona46on",
  "amount": 11500,
  "identifier": "tx-000001"
}

Successful Paylink Response

{
  "id": "NDMwMzk6ODC0MzU2NDUzMjI3MjE",
  "result": 1,
  "version": "3.3.9",
  "url":