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": "https://citypay.com/Vc889/NDMwMzk6ODC0MzU2NDUzMjI3MjE"
}

Failed Paylink Response

{
  "id": "NDMwMzk6ODC0MzU2NDUzMjI3MjE",
  "result": 0,
  "errors": [
    {
      "code": "P026",
      "msg": "Identifier is not supplied"
    }
  ]
}

To create a Paylink token, a call should be made to the Paylink server at https://secure.citypay.com/paylink3/create. The call is validated, checking:

1. the source ip address of the request.
2. the content type of the request such as `application/json`
3. the validity of the data within the request.

Once these have all been met, a response object will be returned, providing either an error code or a success code and a URL to redirect the user's browser to payment.

A payment request has been broken down to the following components to understand their context and scope:

1. Merchant Authentication Fields

These fields are required to identify your CityPay account

{
  "merchantId": 12345,
  "licenceKey": "ASCnrtsona46on"
}

<paylinkTokenRequest>
    <merchantId>12345</merchantId>
    <licenceKey>ASCnrtsona46on</licenceKey>
</paylinkTokenRequest>

Processing Configuration Fields

These fields identify what is to be processed

{
  "amount": 7495,
  "identifier": "0209fcb3fe72",
  "test": true
}

<paylinkTokenRequest>
    <amount>7495</amount>
    <identifier>0209fcb3fe72</identifier>
    <test>true</test>
</paylinkTokenRequest>

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 or may be pre-populated in the initial create request.

{
  "cardholder": {
    "email": "purchaser@email.com",
    "title": "Mr",
    "firstName": "Noel",
    "lastName": "Body",
    "mobile": "+44771122334455",
    "address": {
      "address1": "1 Some Street",
      "address2": "Westminster",
      "area": "London",
      "postcode": "SW1A 2AA",
      "country": "GB"
    },
    "acceptHeaders": "text/html,applicat...;q=0.9",
    "remoteAddr": "55.44.33.22",
    "userAgent": "Mozilla/5.0(Mac...Safari/537.36"
  }
}

<paylinkTokenRequest>
    <cardholder>
        <email>purchaser@email.com</email>
        <title>Mr</title>
        <firstName>Noel</firstName>
        <lastName>Body</lastName>
        <mobile>+44771122334455</mobile>
        <address>
            <address1>1 Some Street</address1>
            <address2>Westminster</address2>
            <area>London</area>
            <postcode>SW1A 2AA</postcode>
            <country>GB</country>
        </address>
        <!-- advanced optional security -->
        <acceptHeaders>text/html,applicat ...;q=0.9</acceptHeaders>
        <remoteAddr>55.44.33.22</remoteAddr>
        <userAgent>Mozilla/5.0(Mac ...Safari/537.36</userAgent>
    </cardholder>
</paylinkTokenRequest>

The cardholder node represents a container for the following cardholder-related fields:

The billing address for the cardholder is Required if AVS address checking is enabled.

CardHolder Security Options

These security fields allow locking in the request to known details of the users browser. If these values do not match the request arriving at payment, a security error will be shown.

Note that these values are strong enforcement and consideration and may prevent easy transaction of payment due to ip addresses changing or dynamic values in the browser.

Config Fields

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

{
  "config": {
    "acsMode": "inline",
    "expireIn": 30
  }
}

<paylinkTokenRequest>
    <config>
        <acsMode>inline</acsMode>
    </config>
</paylinkTokenRequest>

Redirection URLs

Redirects by default arrive as url-form encoded HTTP POST operation however redirects may also be a GET call by prefixing the URL as VERB:URL such as GET:https://mysite.com/redirect.

If no value is specified, the Paylink form will notify the outcome of the transaction to the customer via the online form and the user will need to manually close their window.

Options

Available options are:

{
  "options": [
    "BYPASS_3DSECURE",
    "BYPASS_AVS_ADDRESS",
    "BYPASS_AVS_POSTCODE",
    "BYPASS_CUSTOMER_EMAIL"
  ]
}

<config>
    <options>BYPASS_3DSECURE</options>
    <options>BYPASS_AVS_ADDRESS</options>
    <options>BYPASS_AVS_POSTCODE</options>
</config>

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 hidden values and not displayed in the browser. A custom parameter can display as a text field, select list, checkbox or any html5 input type.

{
  "config": {
    "customParams": [
      {
        "name": "param1",
        "required": true,
        "placeholder": "Enter the value for param1"
      },
      {
        "name": "param2",
        "value": "123",
        "fieldType": "range"
      }
    ]
  }
}

If you are wishing to use session tokens or callback parameters for your integration, it is recommended to use passThroughHeaders or passThroughData instead.

fieldType Select Options

A fieldType value of select can request select items to be rendered. This is constructed by providing a list of values in the value custom parameter field. Each value should be 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. Value items delimited with a colon : can be provide a value label pair, for instance:

{
  "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
        }
      ]
    },
    "passThroughHeaders": {
      "key1": "value1",
      "key2": "value2"
    }
  }
}

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

Cardholder Account Fields

To be able to use credential on file (COF) services. A cardholder account may be created once the payment has been authorised, this is then stored "on file" for subsequent charging for example re-authorisation, unscheduled payment, delayed charges, incremental authorisation, recurring payments, resubmission or no-show style agreements.

Cart Fields

Container for cart options.

Cart Modes:

Cart Items

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

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

Paylink Token API Response

On successful validation, authentication and processing of the Paylink Token Request a response of result 1 is returned whilst a value of 0 indicates an error.

Paylink Token Response Example

{
  "id": "ND4NjIzNzA4NzQyNjA0NTU",
  "result": 1,
  "url": "https://pl.citypay.com/RV1FFV4/ND4NjIzNzA4NzQyNjA0NTU"
}

<paylinkTokenResponse>
    <id>ND4NjIzNzA4NzQyNjA0NTU</id>
    <result>1</result>
    <url>https://pl.citypay.com/RV1FFV4/ND4NjIzNzA4NzQyNjA0NTU</url>
</paylinkTokenResponse>

Error Code Format

Postback Handling

On processing a Transaction Request, Paylink will 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). A postback is a pseudonym for a Webhook or Callback.

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

A Postback does contain SHA256 integrity information which should also be checked to confirm that it is sent from a valid source. We also provide a sha1 value for backwards compatibility however integrators should consider this as deprecated.

Examples

{
  "sha1": "+Yz7zrgtzI4AN1b9UOa7th2u+/4=",
  "cardScheme": "Visa Debit",
  "expYear": 2020,
  "authenticationResult": "?",
  "CSCResponse": "M",
  "digest": "BxNq3NffJGzVfqFLYfjm+w==",
  "email": "email@mail.com",
  "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
}

<paylinkTransactionResult>
    <sha1>RHKJeRJn+EBSaaowXce4KcKTCIw=</sha1>
    <cardScheme>Visa</cardScheme>
    <expYear>2023</expYear>
    <authenticationResult>?</authenticationResult>
    <CSCResponse></CSCResponse>
    <digest>8pEXNXUcCF6YQ4FQnMT4bg==</digest>
    <email>your@email.com</email>
    <identifier>xmlTest</identifier>
    <firstname>Joe</firstname>
    <AVSResponse></AVSResponse>
    <cavv></cavv>
    <postcode>JE2 3NT</postcode>
    <result>1</result>
    <datetime>2018-01-06T15:40:15.807Z</datetime>
    <errormessage>Test Transaction</errormessage>
    <country>AU</country>
    <amount>123412</amount>
    <sha256>QhoBrnywFG4Vl8T5wOVwAPZslVrbL0kac9FzktxRw00=</sha256>
    <maskedPan>400000******0002</maskedPan>
    <lastname>Blogs</lastname>
    <expMonth>7</expMonth>
    <cac>0</cac>
    <status>O</status>
    <errorid>001</errorid>
    <currency>GBP</currency>
    <address>la rue de home</address>
    <errorcode>001</errorcode>
    <mode>test</mode>
    <authcode>A12345</authcode>
    <cardSchemeId>VE</cardSchemeId>
    <eci>7</eci>
    <title></title>
    <authorised>true</authorised>
    <cac_id></cac_id>
    <transno>65191</transno>
    <merchantid>12345678</merchantid>
</paylinkTransactionResult>

Providing a Postback URL

A default URL can be provided within your Paylink profile. Any value supplied in the Token Request, will override the stored profile 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 based on the result of the transaction.

A URL can only be on ports HTTP 80 and HTTPS 443. If you wish to utilise multiple applications or use a different port, we recommend reverse proxying your calls via Apache or Nginx or cloud services such as AWS Application Load Balancer.

Merchant internal or localhost addresses often used for development testing cannot be used unless made publicly available. Whilst in an integration phase we suggest using a product such as ngrok.com to create a secure tunnel for building your post back.

A valid URL is considered:

• to not be an empty string.
• to be RFC 1738 compliant.
• is a valid, reachable port such as port 443.

Paylink optionally supports postback URLs where the endpoints use self-signed certificates.

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 a 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 whilst not recommended for integration 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. If these timeout values are too short, please contact support who can alter these values as appropriate.

Postback Response Handling

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

Synchronization Strategy

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

The config parameter postback_policy should be set to - none defines that no postback is to be sent - sync defines that the postback is synchronous - async defines that the postback is 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 cardholder. The call is attempted by default only once. This is to ensure that Paylink can respond to the browser session 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.

Paylink Transaction Response Reference

Transaction Response parameters are returned in a postback and optionally in a redirection URL.

{
    "AVSResponse": " ",
    "CSCResponse": "M",
    "address": "",
    "amount": 11056,
    "authcode": "021079",
    "authenticationResult": "Y",
    "authorised": "true",
    "cac": 0,
    "cac_id": "",
    "cardScheme": "Visa Debit",
    "cardSchemeId": "VD",
    "cavv": "AJkBBQNSNgAAACswgmICdAAAAAA=",
    "country": "",
    "currency": "GBP",
    "datetime": "2021-07-21T08:34:46.065Z",
    "digest": "i0JoTkP2Q3Ah3mGr7qeqqg==",
    "eci": "5",
    "email": "transactions@citypay.com",
    "errorcode": "000",
    "errorid": "000",
    "errormessage": "Accepted Transaction",
    "expMonth": 8,
    "expYear": 2025,
    "firstname": "",
    "identifier": "RT-00000-181",
    "lastname": "",
    "maskedPan": "Visa***3028",
    "merchantid": 123456,
    "mode": "live",
    "name_on_card": "MR N E PERSON",
    "postcode": "",
    "result": 1,
    "sha1": "+DVBFjo5qw2PT6tYy9CkzBv8uJE=",
    "sha256": "JnJ/J456xCEnCeb2cCgROG7rsxF2HMBJiJRN4qkehz0=",
    "status": "O",
    "title": "Mr",
    "transno": 82101
}

<paylinkTransactionResult>
    <AVSResponse> </AVSResponse>
    <CSCResponse>M</CSCResponse>
    <address></address>
    <amount>11056</amount>
    <authcode>021079</authcode>
    <authenticationResult>Y</authenticationResult>
    <authorised>true</authorised>
    <cac>0</cac>
    <cac_id></cac_id>
    <cardScheme>Visa Debit</cardScheme>
    <cardSchemeId>VD</cardSchemeId>
    <cavv>AJkBBQNSNgAAACswgmICdAAAAAA=</cavv>
    <country></country>
    <currency>GBP</currency>
    <datetime>2021-07-21T08:34:46.065Z</datetime>
    <digest>i0JoTkP2Q3Ah3mGr7qeqqg==</digest>
    <eci>5</eci>
    <email>transactions@citypay.com</email>
    <errorcode>000</errorcode>
    <errorid>000</errorid>
    <errormessage>Accepted Transaction</errormessage>
    <expMonth>8</expMonth>
    <expYear>2025</expYear>
    <firstname></firstname>
    <identifier>RT-00000-181</identifier>
    <lastname></lastname>
    <maskedPan>Visa***3028</maskedPan>
    <merchantid>123456</merchantid>
    <mode>live</mode>
    <name_on_card>MR N E PERSON</name_on_card>
    <postcode></postcode>
    <result>1</result>
    <sha1>+DVBFjo5qw2PT6tYy9CkzBv8uJE=</sha1>
    <sha256>JnJ/J456xCEnCeb2cCgROG7rsxF2HMBJiJRN4qkehz0=</sha256>
    <status>O</status>
    <title>Mr</title>
    <transno>8210</transno>
</paylinkTransactionResult>

Merchant Authentication Fields

Result Codes

The following result codes are an exhaustive list and cater for all transaction types, including e-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.

Fraud Checking Response Fields

AVS Address Resopnse Values

CSC Response Values

Surcharging Additional Response Fields

If surcharging is enabled on the merchant account and applied to the transaction.

Card Details

Card Holder Details

3DSecure Result Codes

Authentication Result

• 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 liability shift from Merchant to cardholder 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.

ECI Values

Cardholder Account Fields

Transaction Response Digests

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:

• concatenate the following response fields, in order authcode, amount, errorcode, merchantid, transno, identifier, licencekey.
• apply through the hash function.
• encode the byte array result from the hash function as a base64 string.
• compare the generated value to the value returned by Paylink.
• if the both digests are the same, the integrity of the data is correct.
• 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.

Example values are:

authcode: 88A123, amount: 1500, errorcode: 000 ,merchantid: 123456 ,transno: 8601, identifier: TX-0001 ,licencekey: BWCG00WES4JSH0Q6

Results in - SHA-1: DIVLXJ4HcKg4K6u51a+e8yhk9Bo - SHA-256: xnKflRW1tqa9BTgu79sGZsES7e3c+LpJ4+hJHt8VfwI=

Redirection Handling

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 through a HTTP POST containing application/x-www-form-urlencoded data 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": "https://mysite.com/payment/result", 
    "redirect_failure": "https://mysite.com/payment/failed"
}

whilst an enforced GET call can be preceded

{
    "redirect_success": "GET:https://mysite.com/payment/result", 
    "redirect_failure":"GET:https://mysite.com/payment/failed"
}

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.

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 the payload data will be URL encoded regardless of the request content-type.
   2. the payload data will be URL encoded regardless of the request content-type.

Notifications and Messaging

Email Handling

Paylink will optionally forward an email to - a merchant email to a specified merchaant email address asnotification of payment completion - a customer email to a cardholder's email address as a receipt.

Emails are generated in multipart/alternative format containing both HTML and Plain Text MultiPart messages.

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 <transactions@citypay.com> 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.

ChatOps

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

Advanced Topics

Surcharging Support in Paylink

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.

Credential on File Functionality in Paylink

Paylink provides cardholder account support for storing payment card details for future use. This can be used to facilitate incremental bill and subscription payments made as 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
2. update payment card information for use with a particular Cardholder Account.

To enhance Paylink to create cardholder accounts, your account will need to be activated to accept this option.

A cardholder account is identified using an accountNo parameter 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 cardholder 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 cardholder using 3D-Secure, CSC and AVS. Subsequent transactions are ordinarily coded as continuing authority transactions using batch processing through the CityPay API.

Enabling CardHolder 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.

CardHolder Account Extensions to the Response

cac values

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

Pre-Authorisation Support in Paylink

Paylink supports pre-authorisation processes that involve:

1. an initial pre-authorisation of a transaction, earmarked 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'.

QR Codes

Paylink 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 pl.citypay.com/{mid}/{token} where mid is an encoded version of your processing merchant account and token is a randomised token 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 amended by using http query string parameters. This allows you to control the size and format of the barcode.

Usage

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.

Security

The token generated is considered an offer for a cardholder to take payment. No card data or sensitive information is linked to this QR code. Should multiple users link to Paylink 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 set 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.

Paylink Integrations

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.

Alternate Payment Methods

Merchants have the option to provide their customers with alternate payment methods such as Apple Pay, Google Pay™ and PayPal. Merchants will need to request this feature to be enabled by CityPay by providing some extra information depending on which alternate methods are required.

Apple Pay

Merchants that opt to provide Apple Pay as a payment option for their customers must request this feature to be enabled by CityPay.
CityPay will register a merchant with Apple in order to allow for the merchant to take payments via Apple Pay.

Google Pay™

Google Pay is available to all CityPay Clients that integrate with Paylink v4 hosted form, without additional costs.
To enable Google Pay please contact your account manager directly or request this feature by emailing CityPay Support

SCA and PSD2

Google Pay supports both a tokenized solution, which will always be preferred. Most issuers will accept this as being SCA, and hence not result in the need for completion of 3D-Secure.
In case it is not the tokenized solution that is used, or the issuer declines the transaction for missing SCA, CityPay will automatically continue with the 3DS flow to ensure the payment can succeed.

PayPal

In order to take payments via PayPay, merchant will need to register for a PayPal Business account.

Testing Best Practices

CityPay offer a test facility for client testing and integration development on this API all testing should be geared within the sandbox service. This service models an acquirer and produces test transactions for testing of post authorisation processes.

Test transactions are available for reporting purposes for up to 3 months.

Our test gateway includes:

• Test Authorisation processing
• Test Refund processing
• Test ThreeDSecure ACS for integrating the full authentication process in to your application
• Test Pre-auth processes such as authorisation, completion/capture and cancellation/voids
• Test Charge processing

Authorisation Codes on the Test Gateway

Authorisation codes are static to allow the integrator to easily identify an actual authorisation code and a test code. The returned authorisation codes by the test gateway are:

Modelling behaviour

To model different behaviours, we have enabled both an amount mapping and a csc mapping process which will return different responses based on these values, values are:

For American Express cards requiring 4 digit CSC values, the last 3 digits of the CSC will be considered i.e. 0333, 1333 would result in the same behaviour.

Test Card Numbers

The following test card numbers could be used for transaction testing.

AVS Checking

AVS checks the numeric values of the address and postcode via the card issuer and card schemes. Our test gateway will only validate whether values are supplied where required.

Test ACS

As part of the test suite, the test ACS provides a simple screen confirmation page similar to an actual ACS page. It will model the response (PaRes) from a standard ACS call using your payment details. To use:

1. click on Authorise to mimic an authorised response.
2. click on Cancel to mimic a failed authorisation response.

Error Codes Reference

When processing a transaction through the CityPay APIs an error code value is returned indicating the result of processing the transaction. Each error code combines a code, an error message and error id parameter.

A CityPay error code is presented in the format of an alpha character followed by a 3 digit numeric. The alpha character represents the error grouping i.e. C001 is a card validation error and the 3 digit numerics the code number of 001. The system group does not contain a character and is therefore the only code that appears as a 3 digit numeric.

An error message is a textual String describing the error. The error message field may include additional information pertaining to the thrown error which will aid in resolving the error.

An error id is also known as a complete error identifier. This code is in the format of error code.system code.location code where the system code and location code are internal codes to CityPay that aid in deciphering the origination of an error message. This identifier should be included with the error message in any support requests.

System

The System group defines a group that determines the outcome of processing transactions. This code is the result of an authorised transaction and defines further details on why a transaction may be authorised or declined. Should a transaction result in a sytem error code, it is expected that this transaction has reached authorisation through to the acquirer or card issuer and the result is determined by the contacted authorisation network.

Card Validation Errors

Card validation errors are caused by invalidity of a card. This is generally related to processing errors when cards are presented for authorisation. Cards are checked against standard specifications and card scheme specifications, therefore you may find errors occur against certain card types than others.

Data Error

The data error group determines that configuration and variable data is invalid. Commands or actions cannot be completed until data errors are ammended.

Fatal Error

Fatal errors are errors that have prevented authorisation from occurring such as communications errors or application errors. An engineer will be alerted whenever a fatal error occurs to investigate occurrences of these error types.

Request Error

Refund Errors

Security Error

Transaction Error

The Transaction error group defines a group of codes that identify that an error was found which could be a potential tranactional problem such as duplication. These errors are in place to protect both merchants and card holders from causing invalid processing.

Wallet Error

The Wallet group defines a group of codes that identify errors related purely to wallet style transactions. These codes identify relationships to processing, generation and loading of wallet accounts.