json xml

Paylink Payment Page

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.


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.


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.


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.


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

Paylink-3 Control Flow

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.

  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"

Field Type Usage Description
merchantId int Required The merchant id you wish to process this transaction with. You will be provided with one or more merchant ids when signing up for an account.
licenceKey string Required The licenceKey field is used to identify the integration being requested.

Processing Configuration Fields

These fields identify what is to be processed

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

Field Type Usage Description
accountNo string Optional Specifies an alpha-numeric account number that the Paylink service uses when creating a Cardholder Account. The value should be no longer than 20 characters in length.
amount int Required Specifies the intended value of the transaction in the lowest denomination with no spacing characters or decimal point. This is the net total to be processed. An example of £74.95 would be presented as 7495.
clientVersion string Optional The clientVersion field is used to specify the version of your application that has invoked the Paylink payment process. This feature is typically used for tracing issues relating to application deployments, or any Paylink integration module or plugin.
email string Optional The email field is used for the Merchant to be notified on completion of the transaction . The value may be supplied to override the default stored value.
Emails sent to this address by the Paylink service should not be forwarded on to the cardholder as it may contain certain information that is used by the Paylink service to validate and authenticate Paylink Token Requests: for example, the Merchant ID and the licence key.
identifier string Required Identifies a particular transaction linked to a Merchant account. It enables accurate duplicate checking within a pre-configured time period, as well as transaction reporting and tracing. The identifier should be unique to prevent payment card processing attempts from being rejected due to duplication.
Len (5-50 characters)
test string Required Specifies the mode of the transaction:
true: the transaction will be processed using the CityPay Test Authorisation System to enable comprehensive systems integration testing. If no value is supplied then a request is assumed to be a test transaction by default.
false: the transaction will be processed and authorised within the CityPay Acquiring network. The cardholder will be deducted the amount of the transaction on successful authorisation.

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": "",
    "userAgent": "Mozilla/5.0(Mac...Safari/537.36"

            <address1>1 Some Street</address1>
            <postcode>SW1A 2AA</postcode>
        <!-- advanced optional security -->
        <acceptHeaders>text/html,applicat ...;q=0.9</acceptHeaders>
        <userAgent>Mozilla/5.0(Mac ...Safari/537.36</userAgent>

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

Field Type Usage Description
address string Optional Represents a container for address related fields.
company string Optional A company name for the cardholder.
email string Optional The cardholder's email address. This field can be used to send a receipt to the payment cardholder. If this value is not supplied, no email will be sent.
firstName string Optional The first name of the cardholder.
lastName string Optional The last name of the cardholder.
mobile string Optional The mobile number of the cardholder. This can be used for data collection via the Paylink Payment Form or to send an SMS on completion of a transaction. This feature is a licensable option and is not configured by default.
title string Optional The title for the cardholder such as Mr, Mrs, Dr etc.

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

Field Type Usage Description
address1 string Optional The first line of the address.
address2 string Optional The second line of the address
address3 string Optional The third line of the address
area string Optional The area such as city, town, parish
country string Optional The country of the billing address of the cardholder. The country code should be an ISO 3166 2 or 3 digit country code.
label string Optional A label for the address such as Head Office, Home Address
postcode string Optional The postal/zip code associated with the billing address

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.

Field Type Usage Description
acceptHeaders string Optional The accept headers string generated by the Customer Browser. This field may be used to lock the payment process to the customer's browser. If the customer were to attempt to use a different browser an error will be generated.
remoteAddr string Optional Specifies the remote IP address of the customer's browser. This field may be used to lock the payment form to the customer's IP address. Should the address change or a malicious third party attempted to hijack the transaction, an error will be generated.
userAgent string Optional Specifies the user agent string of the Customer Browser. This field may be used to lock the payment form to the browser. Should a different user agent attempt to process the transaction or a malicious third party attempted to hijack the transaction, an error is generated.

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

Field Type Usage Description
acsMode string Optional Specifies the approach to be adopted by the Paylink form when displaying a 3-D Secure challenge window. The values may be
  • iframe: shows the 3-D Secure ACS in an iframe dialog, neatly embedding it in Paylink. This provides a more seamless flow for the cardholder who is able to validate and authenticate their card using a dialog provided by their card issuer.
  • inline: an inline mode transfers the full browser window to the authentication server, allowing the payment cardholder to see their payment card issuer's URL and the certificate status in the browser.
(default = iframe)
customParams array Optional Defines custom parameters to add to the request.
descriptor string Optional Directly specify the merchant descriptor used for the transaction to be displayed on the payment page.
expireIn int Optional Specifies a period of time in seconds after which the token cannot be used. A value of 0 defines that the token will never expire. The API will convert an expiry time based on a string value. For instance:
  • s - Time in seconds, for example 90s.
  • m - Time in minutes, for example 20m.
  • h - Time in hours, for example 4h.
  • w - Time in weeks, for example 4w.
  • M - Time in months, for example 6M.
  • y - Time in years, for example 1y.
Defaults to 30 minutes
lockParams string[] Optional May be used to lock fields which are displayed in the form. For example, if the cardholder.address.postcode field were to be specified this would will prevent the customer amending the postal code for the cardholder postcode field.
merch_branding string Optional Used to customise the branding of the form. This is currently deprecated.
merch_logo URL Optional A URL of a logo to include in the form. The URL should be delivered using HTTPS.
merch_terms URL Optional A URL of the merchant terms and conditions for payment. If a value is supplied, a checkbox will be required to be completed to confirm that the cardholder agrees to these conditions before payment. A modal dialogue is displayed with the content of the conditions displayed.
options string[] Optional Specifies an array of configuration options to be applied to the transaction which complement or override default values.
passThroughData array Optional To allow for greater interoperability, Paylink offers developers the ability to include Json data in any call using a config.passThroughData field. This data will be stored with your token request for the duration of the transaction session but not with any resulting authorisation. This is useful to provide information related to the user's session or cart. A practical length of 1024 bytes is possible to be stored.
The Paylink system doesn't restrict you to simple key value pairs and allows for nested complex objects to be supplied. Pass through data will be supplied on a post back call or a post redirection.
passThroughHeaders array Optional Values can be provided in the Token Request which are added as HTTP headers in the post back such as bearer tokens or authentication data.
postback URL Optional Specifies a URL to use for a call back when the payment is completed. see Postback Handling }
postback_password string Optional A password to be added to the postback for HTTP Basic Authentication
postback_policy string Optional The policy setting for the postback see Postback Handling }
postback_username string Optional A username to be added to the postback for HTTP Basic Authentication
redirect_delay int Optional A value which can delay the redirection in seconds. A value of 0 will redirect immediately.
redirect_failure URL Optional A URL which the browser is redirected to on non-completion of a transaction.
redirect_success URL Optional A URL which the browser is redirected to on authorisation of a transaction.
renderer string Optional The Paylink renderer engine to use
return_params string Optional If a value of true is specified, any redirection will include the transaction result in parameters. It is recommended to use the postback integration rather than redirection parameters.
ui object Optional Configuration object for UI customisation

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.


Available options are:

Option Description
BYPASS_AVS_POSTCODE which bypasses the AVS postcode checking policy where it is enabled by default
BYPASS_AVS_ADDRESS which bypasses the AVS address checking policy where it is enabled by default
BYPASS_CSC_REQUIRED which bypasses the CSC checking policy where it is enabled by default
BYPASS_3DSECURE which bypasses 3D secure processing where it is enabled by default. It is not possible to enforce 3D Secure as it requires further configuration by your account setup
BYPASS_CUSTOMER_EMAIL which allows bypassing of sending emails to the customer when enabled
BYPASS_CUSTOMER_SMS which allows bypassing of sending SMSs to the customer when enabled (licensed option)
BYPASS_DUPLICATE_CHECK which allows the bypassing of the duplicate checker, this is on by default and allows prevention of duplicate transactions from being processed within a time slot
BYPASS_MERCHANT_EMAIL which allows bypassing of sending emails to the merchant account
BYPASS_PREAUTH which bypasses pre-authorisation when it is enabled to pre auth by default (licensed option)
CAC_OPTIN adds a checkbox to the payment form which allows a cardholder account facility to have their card details remembered or opt not to
CAC_AUTO_UUID generates a unique ID for each cardholder account rather than having one specified
CREATE_CAC_ACCOUNT_ON_AUTHORISATION which Required where creating cardholder accounts to confirm creation is Required (licensed option)
ENFORCE_AVS_ADDRESS which enforces the AVS address checking policy where it is disabled by default
ENFORCE_AVS_POSTCODE which enforces the AVS postcode checking policy where it is disabled by default
ENFORCE_CSC_REQUIRED which bypasses the CSC checking policy where it is disabled by default
ENFORCE_PREAUTH which enforces pre-authorisation when it does not pre-auth by default (licensed option)
REQUIRE_CUSTOMER_EMAIL Enforces that the cardholder must enter an email address
  "options": [
Field Type Usage Description
addressMandatory boolean Optional whether the cardholder address is mandatory
postcodeMandatory boolean Optional whether the cardholder poostcode is mandatory
formAutocomplete string Optional specify the form autocomplete setting of the HTML form. If set to off the UI will set autocomplete="off" on the form level. Default is on
ordering int Optional A logical ordering of the UI components

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.

Field Type Usage Description
fieldType string Optional The HTML input element type which may include 'hidden' or any other permitted value. Should the fieldType be select a select list will render however requires option values, see below.
group string Optional A value which groups items for layout. The value should be a string title for rendering such as "Your Account Info". If no value is provided, the paramer is added to a default parameter group. Group names are rendered alphabetically.
label string Optional A label that should appear immediately before the field element in the generated form. If this value is not supplied, the name value will be used.
locked boolean Optional States whether the field is locked, preventing entry or amendment by the person completing the form.
name string Required Refers to the rendered HTML form element name. The value of this field is used in the postback and redirect dataset.
order int Optional A value which allows you to order the position of elements in a grouping. Values will order in ascending order. Negative values are possible.
pattern string Optional A string value which specifies the validation logic of the form element, for example a value of QA[0-9]{3,4} will require a value such as QA221 or QA4433.
placeholder string Optional A value to set as the placeholder attribute which will render in modern browsers.
required boolean Optional A boolean value that states whether the field is required or optional. When an element is required, validation will be performed on the end user's input form.
value string Optional An initial value for the parameter as it appears on the Form. If your parameter is hidden, the value will be required.

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:

"label" : "Age Group", "fieldType": "select", "value" : "Under 18|18-30|30-50|50+" ... would render as <select> <option value="Under 18">Under 18</option> <option value="18-30">18-30</option> <option value="30-50">30-50</option> <option value="50+">50+</option> </select> however, "label" : "Age Group", "fieldType": "select", "value" : "junior:Under 18|hipster:18-30|midage:30-50|senior:50+" ... would render as <select> <option value="junior">Under 18</option> <option value="hipster">18-30</option> <option value="midage">30-50</option> <option value="senior">50+</option> </select>
  "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.

Field Type Usage Description
accountNo string Optional Specifies an alpha-numeric account number that the Paylink service uses when creating a Cardholder Account. The value should be no longer than 20 characters in length.

Cart Fields

Container for cart options.

Field Type Usage Description
contents array Optional The cart.contents field represents an array containing zero, one or more cart items represented by objects of the form:
mode integer Optional The mode field specifies the behaviour or functionality of the cart as below. Defaults to 0.
productDescription string Optional Specifies a description about the product or service that is the subject of the transaction. It will be rendered in the header of the page with no labels.
productInformation string Optional Specifies information about the product or service that is the subject of the transaction. It will be rendered in the header of the page.
shipping int Optional The shipping amount of the transaction in the lowest denomination of currency
tax int Optional The tax amount of the transaction in the lowest denomination of currency

Cart Modes:

Mode Name Description
0 No cart No cart is shown
1 Read-only The cart is shown with a breakdown of the item details provided by objects in the contents array.
2 Selection cart The cart is shown as a drop-down box of available cart items that the customer can a single item select from.
3 Dynamic cart a text box is rendered to enable the operator to input an amount.
4 Multi cart The cart is displayed with items rendered with selectable quantities.

Cart Items

Field Type Usage Description
amount int Required The net amount of the item. The Paylink Payment Form does not multiply this figure by the value provided by the count value for the cart item, this is principally to avoid rounding errors to introduce discrepancies between the value of the goods charged for and the total amount represented by the collection of cart items.
brand string Optional The brand of the item such as Nike
category string Optional The category of the item such as shoes
count int Optional The count of how many of this item is being purchased, should the cart be editable, this value should be the default count required. The Paylink Payment Form assumes a count of 1 in the event that no value for the count field is provided for a cart item.
label string Optional The label which describes the item
max int Optional For an editable cart, the maximum number of items that can be purchased, defaults to 5
sku string Optional The stock control unit value
variant string Optional The variant field refers to the variant of the cart item to enable similar items to be distinguished according to certain criteria. For example, similar items may be distinguished in terms of size, weight and power. The Paylink Payment Form does not constrain the value of the variant field to a particular set of metrics.
  "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"

Field Type Usage Description
errors array Optional An array of errors which are found when attempting to create the payment token. Required (when result=0)
id string Required The id field contains the merchant unique identifier for the configured transaction.
result int Required The result field contains the result for the Paylink Token Request.
0 indicates that an error was encountered while creating the token
1 which indicates that a Token was successfully created.
url string Optional The url is the Paylink Token URL which is to be used by the Customer Browser to access the Paylink Payment Form. Required (when result=1)

Error Code Format

Field Type Usage Description
code string Required The errors[n].code field contains an error code indicating why the Paylink Token Request could not be completed successfully.
msg string Required The errors[n].msg field contains an error message indicating why the Token could not be generated.

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, and 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.


  "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

    <postcode>JE2 3NT</postcode>
    <errormessage>Test Transaction</errormessage>
    <address>la rue de home</address>

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:

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
    <AVSResponse> </AVSResponse>
    <cardScheme>Visa Debit</cardScheme>
    <errormessage>Accepted Transaction</errormessage>
    <name_on_card>MR N E PERSON</name_on_card>

Merchant Authentication Fields

Field Type Description
amount int The total amount of the transaction processed in Lowest Denomination Form, inclusive of any surcharge applied.
authcode string The authorisation code returned by the acquirer if the transaction was successful.
authorised boolean Indicates that the transaction was authorised and was successfully processed. The result and errorcode values provide further detailed information on the successful or failed transaction.
currency string The field contains the currency of the transaction as an ISO-4217 3 digit alpha-numeric value.
datetime string The UTC date and time that the transaction was processed as an ISO-8601 date and time value. For example 2021-12-03T10:15:30
errorcode string The error/result code for the resultant transaction. See API Response & Error Codes.
errorid string The full error id for the resultant transaction, in the form 000.0.0
errormessage string The human-readable error message for the resultant transaction.
identifier string The identifier provided in the originating token request.
merchantid int The CityPay merchant id that the transaction was processed with.
mode string The mode of the transaction, returning live or test.
passThroughData object An object of data provided in the request to pass through
result int The result code, indicating the outcome of the transaction.
status string The status code determines how the transaction will be handled for settlement. A value of 'O', indicates that the transaction is open for settlement. Merchants who have pre-authorisation enabled can determine that the transaction is pre-authorised by seeing a 'P' in this response.
transno int An incremented transaction number generated by the platform to produce an audited list of transactions as they are processed. If a transaction failed to process this value may be -1

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.

Value Name Description
0 Declined Result code when a transaction is declined by the acquirer and no further processing is allowed.
1 Accepted Result code when a transaction is accepted by the acquirer.
2 Rejected The transaction was rejected before sending to the acquirer for processing.
3 Not Attempted The transaction was not attempted due to a validation failure and therefore not processed (default).
4 Referred Result code when a transaction has been referred for manual authorisation.
5 Perform PIN Retry Retry the PIN entry.
6 Force Signature Verification Force Signature Verification
7 Hold Hold transaction and recheck.
8 Security Error A security error was found which prevented the transaction from processing
9 Call Acquirer The transaction was referred by the Acquirer who should be called to gain a manual authcode. N/A in an e-commerce environment.
10 Do Not Honour The transaction was declined and being rejected for consideration of processing. This may be due to the cardholder having a hold on their card, multiple denied payments in a row and therefore awaiting the cardholder to contact their issuer
11 Retain Card Your should retain the card as it is considered fraudulent.
12 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.
13 Invalid Card No The card number is invalid. This may occur after a valid LUHN check.
14 Pin Tries Exceeded The number of PIN entries have been exceeded.
15 PIN Invalid The PIN number entered is invalid.
16 Authentication Required 3DSv1 Authentication required for a transaction, in an e-commerce transaction, the system will need to refer to an ACS.
17 Authentication Failed Authentication is required for the transaction. The authorisation process failed.
18 Verified A verification request was made and the transaction waas verified
19 Cancelled A transaction has been cancelled from processing.
20 Unknown The unknown response is a value returned when the system has produced an error and the result cannot be determined.
21 Challenged The request has been challenged in association with 3DSv2 and requires the cardholder to provide authentication
22 Decoupled The transaction has been decoupled
23 Permission Denied The transaction has been denied due to a card scheme mandate or the result of fraudulent transactions

Fraud Checking Response Fields

Field Type Description
AVSResponse string The result of address verification provided by the card issuer.
CSCResponse string The result of the card security code checking by the card issuer

AVS Address Resopnse Values

Value Description
' ' (Space) No information.
A Address matches, post code does not
B Postal code not verified due to incompatible formats.
C Street address and Postal code not verified due to incompatible formats.
D Street address and postal codes match.
E AVS Error.
G Issuer does not participate in AVS.
I Address information verified for international transaction.
M Street address and Postal codes match for international transaction.
N No match on address or postcode.
P Postal codes match. Street address not verified due to to incompatible formats.
R System unavailable or Timed Out.
S Service not supported by issuer or processor.
U Address information unavailable.
W 9 digit post code matches, Address does not.
X Postcode and Address match.
Y Address and 5 digit post code match.
Z 5 digit post code matches, Address does not.

CSC Response Values

Value Description
M Card verification data matches.
N The card verification data was checked but did not match.
P The card verification data was not processed.
S The card verification data should be on a card but the merchant indicates that it is not.
U Issuer not certified, did not provide the data or both.
' ' (Space) No information.

Surcharging Additional Response Fields

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

Field Type Description
initial_amount: int The amount of the transaction provided in the originating request, in Lowest Denomination Form.
surcharge: int The surcharge amount that has been added to the transaction
surcharge_rate: int the surcharge_rate field contains the rate in which the surcharge was applied.

Card Details

Field Type Description
cardScheme string The field describes the card scheme of the Payment Card that was processed in the transaction such as Visa, MasterCard.
cardSchemeId string The field contains an id for the card scheme used for the transaction.
expMonth int The month of expiry of the card, a value between 1 and 12
expYear int The full year of expiry of the card
maskedPan string The masked version of the primary account number (PAN) used by the card holder used in the resultant transaction. For example Visa***3028
name_on_card string The name as it appears on the card such as MR N E PERSON. This value is normally requested from the cardholder and checked with 3DS.

Card Holder Details

Field Type Description
address string The billing address as a single line comma delimited address as entered by the cardholder at the time of completing payment.
country string The field contains the ISO-3166 2 character country code of the cardholders billing address.
email string The field contains the cardholder email address entered within the online form.
firstname string The first name of the cardholder as entered within the online form.
lastname string The last name of the cardholder as entered within the online form.
postcode string The postcode that the cardholder entered when completing the online payment form.
title string The title of the cardholder as entered on the payment form.

3DSecure Result Codes

Field Type Description
cavv string
eci string
authenticationResult string

Authentication Result

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

Visa MasterCard Description
7 0 set when transaction authentication was not authenticated, unsuccessful or not attempted
6 1 set when an attempt is made to authenticate the cardholder using 3DSecure, but the Payment Card Issuer or the payment cardholder were not participating in the 3DSecure scheme, or the Payment Card Issuer ACS was not able to respond to the request
5 2 set when a transaction has been fully authenticated

Cardholder Account Fields

Field Type Description
cac int The field contains the results of the control path in response to card holder account actions. 0 indicates that no action has been taken
1 indicates that the account was loaded and processed
2 indicates that a new account was created
3 indicates that an account was updated with details such as the billing address submitted by the card holder using the payment form
4 indicates that the accountwas deleted
cac_id string Contains the identifier of the Cardholder Account associated with the transaction.

Transaction Response Digests

Field Type Description
digest string Deprecated The field contains an MD5, base64 encoded string of the result parameters. Will be removed from future versions.
sha1 string Deprecated The field contains an SHA-1, base64 encoded string of the result parameters. Will be removed from future versions.
sha256 string The field contains an SHA-256, base64 encoded string of the result parameters.

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:

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", 

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:

Email bypassed

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.

Customer Email Receipt

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.


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

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.

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

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.

Paylink QR Code

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.

Parameter Data Type Default Description
type string qrcode Specifies the type of barcode to produce. As we are encoding Urls we only support the following types.
  • qrcode.
  • datamatrix.
h int 256 Specifies the height of the image generated a minimum of 32 pixels up to a maximum of 512 pixels.
w int 256 Specifies the width of the image generated a minimum of 32 pixels up to a maximum of 512 pixels.


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.


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.

Magento Opencart woocommerce wordpress

Alternate Payment Methods

Paylink Payment Page

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.


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:

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:

AuthCode Behaviour
A12345 Sale transaction.
B12345 PreAuth sale transaction.
C12345 Completion/Capture call.
R12345 Refund transaction.
V12345 Void transaction.

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:

Amount CSC Behaviour Response
3333 333 Returns a declined transaction 090
3344 344 Returns an AVS Address Failure, regardless of configuration for AVS and the address value supplied. 095
3355 355 Returns an AVS Postcode Failure, regardless of configuration for AVS and the address value supplied. 096
3366 366 Returns a Card Security Failure, regardless of configuration for CSC and the value supplied. 094
3377 377 Returns a Fraud decline. 091
4444 444 Returns a Referral. 089
6666 666 Returns a communication error. F006
5544 544 Returns an AVS Address Failure only if AVS is configured or enforced via the API. A value of 99 will reject the address any other value is accepted. 095
5555 555 Returns an AVS Postcode Failure only if AVS is configured or enforced via the API. A value of 99 will reject the postcode, any other value is accepted. 096
5566 566 Returns a Card Security Failure only if CSC matching is configured or enforced via the API. A value of 999 will reject the CSC, any other value is accepted. 094

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.

Card Number Scheme Type CSC Length
3743 871880 19714 Amex Credit 4
3014 445396 5469 Diners Credit 3
3528 0000 0000 0007 JCB Credit 3
4000 0000 0000 0002 Visa Credit 3
4659 0100 0000 0005 Visa Debit 3
5100 0000 0000 0008 MasterCard Credit 3
5573 4700 0000 0001 MasterCard Debit 3
6333 1100 0000 0002 Maestro Debit 3
4508 7500 0000 0009 Visa Electron Debit 3
4857 7900 0000 0002 Visa Business Debit 3

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.


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.

ErrorCode Error Message Further Information
000 Accepted Transaction The transaction was accepted.
001 Test Transaction The transaction was marked as being a test transaction and was successfully returned.
002 Accepted Refund The refund was successful.
003 Accepted Void Transaction The transaction was successfully voided.
011 Signature Verification
012 Hold
013 Pin Invalid
014 Pin Retry
015 Pin Tries Exceeded
030 Cannot Authorise Invalid Card Number The card number was rejected on authorisation although the card was of a good format.
031 Cannot Authorise Expired Card The card was rejected on authorisation as the card has been expired by the issuer.
032 Processing Server Unavailable A delegating processing server was unavailable and failover servers were retried, processing cannot continue Retry the transaction, if the transaction continues to fail, please consult support stating this error code.
040 Transaction verification passed The transaction returned was verified succesfully.
041 Transaction verification failed The transaction returned has failed to be verified.
050 Waiting Authorisation If a transaction requires authentication using 3-D Secure, it will be marked as 050 waiting for authorisation. Should the transaction never be authorised i.e. the user decided not to continue with the transaction then the transaction will remain with the status set. This value will help to define whether authorisation was not fully processed at the time of the transaction.
071 Transaction already voided The transaction was previously voided.
072 Transaction already refunded The transaction was previously refunded to the full amount.
080 Transaction cancelled The transaction was cancelled.
081 Transaction timed out The transaction timed out while processing Occurs when the transaction queues for processing and the transaction reaches a timeout period before a processing slot becomes free. Increasing the time out period for concurrency processing will lower the likely hood of receiving this type of error.
082 Terminal allocation timed out The transaction timed out while allocating a terminal id Occurs when the transaction queues for allocation of a terminal id. Tids are unavailable if there are too many concurrent transactions for the number of terminal ids allocated.
083 Transaction timed out The transaction timed out while connecting to the acquirer Occurs when the transaction processing to the acquirer times out before being able to conect for processing
084 Transaction timed out The transaction timed out while awaiting a response from the acquirer Occurs when the transaction processing to the acquirer connects however there is no response in the time allocated
088 Retain Card
089 Referred The bank has referred the transaction, which results in a declined payment on the internet. This is usually caused by the following reason, a request for further information, such as authorised signature or card holder identification, frequent use of the card within the last 24 hours or a random referral.
090 Declined Transaction The transaction was declined by the card issuer. The customer should consult their card issuer to confirm the reason of the decline.
091 Declined Transaction The transaction was declined due to the card failing the fraud check The customer should consult their card provider.
092 Declined Refund The refund was declined
093 Declined Void Transaction The void transaction was declined
094 Declined Transaction Transaction Declined. CSC Failure The transaction was declined due to the CSC number not matching that on record.
095 Declined Transaction Transaction Declined. AVS Failure The transaction was declined due to the AVS numerics of the address not matching.
096 Declined Transaction Transaction Declined. AVS Failure The transaction was declined due to the AVS numerics of the postcode not matching.
097 Declined Transaction Transaction Declined. AVS Failure The transaction was declined due to the AVS numerics not matching.
098 Declined Transaction Transaction Declined. Authentication Failure The transaction was declined due to an authorisation failure.

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.

ErrorCode Error Message Further Information
C001 Card number contains non-numeric character.
C002 LUHN Check failure Consider the possibility that the card number was keyed incorrectly.
C003 Card number missing.
C004 Card number is an invalid length.
C005 Card is not yet valid The start date is in the future. Check the validity of the card start date.
C006 Card has expired The expiry date is in the past. Check the validity of the card expiry date.
C007 Card expiry month is not a valid month Months should be an integer value between 1 and 12.
C008 Card expiry year is not a valid year Year values should be either a 2 digit or 4 digit number.
C009 Expiry date is not YYMM When providing an expiry date as a String the format should be 2 digit YEAR and 2 digit MONTH (YYMM) for example 0412.
C010 Expiry data missing
C011 Issue number is not numeric
C012 CSC Not an Integer
C013 CSC is longer than 4 characters
C014 CSC Not Present
C015 Start date is not YYMM When providing an expiry date as a String the format should be 2 digit YEAR and 2 digit MONTH (YYMM) for example 0412.
C016 Card start date month is not a valid month Months should be an integer value between 1 and 12.
C017 Card start date year is not a valid year Year values should be either a 2 digit or 4 digit number.
C018 Card has previously been charged back
C019 Invalid expiry date The expiry date is so far in the future that it is considered invalid. By default, this error is logged for expiry dates more than 7 years in the future; this offset may be changed by contacting support. Check the validity of the card expiry date and consider changing the Override Expiration Period.
C020 Invalid Start Date The card start date contains an invalid date, invalid characters or has not been entered when required. Some card details may contain 2 digits and others 4 digits. Occasionally an invalid issue number may affect the start date.
C021 Card number is invalid The card number is not a valid number.
C022 Bin range not found The card number provided cannot be used for this transaction.
C023 Unexpected Issue Number An unexpected issue number is present in the card details.
C024 Expected Issue Number An expected issue number is not present in the card details.
C025 Invalid Issue Number An invalid issue number is present in the card details.
C026 CSC Length is invalid for Card The length of the card security code (CSC,CV2,CVV2) is invalid for the given card type. Visa and Mastercard, generally require a 3 digit code where as American Express require 4 digits.
C027 Card has expired The card is recognised as being expired. The cardholder is required to check with the card issuer as the authorisation returned the expiry response.
C028 Card holder name is mandatory The card holder name is mandatory and is not supplied. The card holder's name is mandatory by this acquirer and should be supplied before continuing.

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.

ErrorCode Error Message Further Information
D001 Gateway Not Configured Error The gateway is not available as there is no configuration data available. Contact CityPay support.
D002 Gateway Configuration Error The gateway is not available as there is a problem with the configuration. Contact CityPay support.
D003 Fraud Module Configuration Error The fraud module is not available as there is a problem with the configuration. Contact CityPay support.
D004 Class Instantiation Error An internal gateway problem. Contact CityPay support.
D005 Class Illegal Access Error An internal gateway problem. Contact CityPay support.
D006 Unkown Terminal The terminal configuration information is invalid. Contact CityPay support.
D007 Unauthorised to use this Terminal The user is not authorised to use this terminal. Contact CityPay support.
D008 Terminal Inactive The terminal being used is currently inactive. Contact CityPay support.
D009 Password Invalid The password being used is invalid. Contact CityPay support.
D010 User Invalid The user is invalid. Contact CityPay support.
D011 User does not have permission to perform this operation User does not have permission to perform this operation. Contact CityPay support.
D012 Hostile card list is not available The system cannot retrieve details from the hostile card list. Contact CityPay support.
D013 Merchant is not found The merchant number is invalid. Contact CityPay support.
D014 Card holder must be present The card holder must be present for this transaction. Contact CityPay support.
D015 Invalid Currency Code The currency code provided is not a valid currency code. Contact CityPay support.
D016 Card type or currency for merchant not found The card bin range or currency code is not valid for the given merchant. Contact CityPay support.
D017 Cardholder must be present The cardholder must be present for this transaction. Contact CityPay support.
D018 Card must be present The card must be present for this transaction. Contact CityPay support.
D019 Manual entry not allowed for this merchant The merchant is not allowed to perform a manual entry. Contact CityPay support.
D020 Invalid Transaction Type The transaction type requested is invalid. Contact CityPay support.
D021 Transaction not allowed for card The transaction is not allowed for the given card. Contact CityPay support.
D022 Transaction not found for merchant with given transaction number A transaction cannot be found for the merchant using the given transaction number. Contact CityPay support.
D023 Transaction not found for merchant with given identifier A transaction cannot be found for the merchant using the given identifier. Contact CityPay support.
D024 Decryption currently unavailable The crypto server cannot be contacted for decryption, decryption requests are unavailable. Contact CityPay support.
D025 Encryption currently unavailable The crypto server cannot be contacted for encryption, encryption requests are unavailable. Contact CityPay support.
D026 No batch id presented A batch id was required to perform the action and was not preset. Batch ids are required when batching transactions for processing and are generally unique. Consult the integration documentation for exact requirements on the data required.
D027 No client id presented A client id was required to perform the action and was not preset. Client ids are required when batching transactions and should be presented, consult your documentation for details on the requirement.
D028 None ASCII characters found in data none ASCII encoded data was found when the data is restricted to the ASCII type. Data is restricted to an ASCII character set, ensure that none ASCII characters are not present.
D029 Invalid Encoding Error The data contains an invalid encoding that is not allowed for the resource. Confirm that the encoding of the data is restricted to the character set required within the specifications documentation. Data should be restricted to the required encoding.
D030 Batch does not contain transactions The batch presented for processing does not contain any transactions. Check that the batch contains transactions.
D031 Store is not found The store id is invalid. Contact CityPay support.
D032 Store is inactive The store defined by the store id is inactive. Contact CityPay support.
D033 Field value is an invalid signed integer value The maximum integer value is 0x7fffffff. The provided value is too large. Contact CityPay support.
D034 Field value is an invalid signed long value The maximum integer value is 0x7fffffffffffffff. The provided value is too large. Contact CityPay support.
D035 Field value is an invalid signed short value The maximum integer value is 32767. The provided value is too large. Contact CityPay support.
D036 The Card Scheme could not be determined Check the card pan to confirm that the pan number is correct and that the bin range entry for this card is available. Contact CityPay support.
D037 Acquirer is unavailable The acquirer for this request is currently unavailable Contact CityPay. Contact CityPay support.
D038 Gateway route is unavailable The gateway route for this transaction is currently unavailable. This may be caused by a configuration change, technical fault or planned works. Contact CityPay support.
D039 No Terminal ID available A terminal id is required to process a transaction. Dependant on the acquirer this may be due to a limitation of concurrency in processing against the number of allocation terminal IDs to the account. Contact CityPay support.
D040 Acquirer Dataset is not found for transaction No acquirer dataset is configured to handle this transaction. Contact CityPay support.
D041 3DSecure Currently Unavailable The ecommerce transaction requires 3DSecure for processing and the Merchant Plug In is currently unavailable. Please retry later The MPI is currently unavailable either due to a period of maintenance or a system error. Please contact CityPay support for information.
D042 3DSecure Enrollment Error The account is not enrolled fully for 3DSecure.
D043 3DSecure Configuration Error The account contains invalid or no configuration information which prevented a 3DSecure session from continuing.
D044 3DSecure Merchant URI Invalid The Merchant URI is either blank or invalid for 3DSecure authentication.
D045 3DSecure Accept Headers Invalid The Accept Headers is either blank or invalid for 3DSecure authentication.
D046 3DSecure User Agent Invalid The User Agent is either blank or invalid for 3DSecure authentication.
D047 3DSecure Directory Server Comms Failure A communication failure was realised while contacting the 3dsecure directory server.

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.

ErrorCode Error Message Further Information
F001 Unknown Error
F002 Data Error
F003 System Error
F004 Null error occurred
F005 Unknown Transaction Type
F006 Communication Error

Request Error

ErrorCode Error Message Further Information
P001 Response type not set
P002 Merchant ID Not Supplied
P003 Merchant ID Is Invalid
P004 Amount is not supplied
P005 Amount is invalid The transaction amount sent in the transaction request is invalid because it is too long or contains characters other than digits. Check the validity of the amount field.
P006 Amount is not supplied in the lowest denomination
P007 The request is not from an accepted source
P008 The referal source is unknown This error occurs when the system cannot identify the source of the request (IP or HTTP Header).
P009 AVS Postcode is not supplied
P010 AVS Postcode greater than 8 characters The AVS value contains too many numeric values.
P011 AVS Address is not supplied
P012 AVS Address greater than 8 characters The AVS value contains too many numeric values.
P013 Transaction Id or Identifier not Present
P014 Transaction Id not Numeric The transaction ID should be a numeric value.
P015 Ceiling Limit Exceeded The transaction amount for this transaction request is above the ceiling limit for the relevant Merchant.
P016 Identifier is greater than 50 characters The identifier must be an alphanumeric value up to 50 characters in length.
P017 LicenceKey is greater than 255 characters The licencekey value must be an alphanumeric value up to 255 characters in length.
P018 Invalid transaction type The transaction type is not allowed for this merchant.
P019 Validation Code Error The request failed the validation code test and is deemed to be an insecure request.
P020 Cashback amount is invalid The cash amount sent in the transaction request is invalid because it is too long or contains characters other than digits.
P021 Cashback transaction not permitted Transaction requested cashback and the Merchant does not allow cashback transactions for the credit/debit card tendered. Establish whether cashback is permitted for this card type in your merchant agreement.
P022 Cashback ceiling limit exceeded The cash amount for this transaction request is above the ceiling limit for the relevant MerchantID.
P023 Invalid transaction type code The transaction request does not have a valid Transaction Type code.
P024 Void Transaction failed, invalid orginal transaction The request for a void transaction failed due to the original transaction not being valid.
P025 Void Transaction failed, no valid original authcode The request for a void transaction failed due to the original transaction not hvaing a valid authorisation code.
P026 Identifier is not supplied The transaction identifier was not supplied by the merchant. A valid identifier should be supplied by the merchant.
P027 Email address is not supplied The email address is required and was not supplied by the merchant. A valid email address should be supplied by the merchant within the request.
P028 Product information is not supplied Product Information is required for this transaction and was not supplied by the merchant. A valid product information string should be supplied by the merchant within the request.
P029 Authorisation key is not supplied An authorisation key is required for this request and was not supplied A valid authorisation key string should be supplied by the merchant within the request. If you do not possess this key, please contact support.
P030 Authorisation invalid
P031 Unsupported transaction type The transaction type requested is not supported by the gateway.
P032 Transaction type not available for processing The transaction type is not configured for the merchant.
P033 Card scheme not available for processing The card scheme is not configured for the merchant.
P034 Invalid Currency The currency specified is invalid.
P035 Licence key is not supplied The Licence key is required for processing and was not supplied.
P036 Licence key does not match The Licence key was supplied but did not match the key required for processing.
P037 Licence key invalid The Licence key was supplied and was not a valid key.
P038 Floor limit not reached The floor limit was not reached for processing the transaction. Increase the amount charged or reduce the floor limit.
P039 Identifier is less than 4 characters The identifier must be an alphanumeric value greater than 4 characters in length.
P040 Account Number Not Supplied A card holder account number was not supplied and therefore the transaction cannot continue.
P041 Account Number is an invalid length A card holder account number is an invalid length.
P042 Account Number contains invalid characters A card holder account number contains non ascii characters or contains spaces surrounding the value.
P043 Account Number not found A card holder account was not found for the given request. Please check the account number and/or password is correct.
P044 Field not provided The given field was not provided and is required. Please check the documentation provided with your installation instructions.
P045 Field value invalid The given field value is invalid. Please check the documentation provided with your installation instructions.

Refund Errors

ErrorCode Error Message Further Information
R001 Could not identify the original transaction.
R002 Transaction Exceeds original value.
R003 Transaction has already been refunded.
R004 Error retrieving original amount.
R005 The amount to refund exceeds the amount available to refund.
R006 Refund not permitted for MerchantID. Transaction requested a refund and the Merchant does not allow refunds on the credit/debit card tendered.
R007 Transaction number is not a valid number. The transaction number provided is invalid for the request and must be a valid integer.
R008 Refund Security Code invalid. The refund security code was provided but did not match the required security code for the provided merchant id.
R009 Refund Security Code Not Provided. The refund security code was not provided and is required to perform a refund.
R010 Original transaction is not a valid purchase. The transaction cannot be refunded because the original transaction is not a valid purchase.
R011 Original transaction was not accepted. The transaction cannot be refunded because the original transaction was not accepted.

Security Error

ErrorCode Error Message Further Information
S001 Invalid Client ID The client id provided is invalid Check the client id supplied is the correct CityPay client id.
S002 Invalid Merchant ID The merchant id provided is invalid Check the merchant id supplied is the correct CityPay merchant id.
S003 Invalid Merchant and Client ID Combination Either the merchant id or client id provided is invalid for this request Check the client id and merchant id that are supplied are the correct CityPay ids.
S004 General Authentication Failure The authentication failed for the requested service. Check the authentication requirements of the service and ensure that the values are correct.
S005 Not Authorised You are not authorised to perform the operation Check your authentication properties and contact CityPay support to ensure that these values are correct
S006 Not Licenced You are not licenced to perform this operation Contact CityPay support or sales for confirmation on your licencing requirements and provision.
S007 Authentication Required Authentication is required to perform this operation and no authentication was presented for authorisation. Check the values you are submitting are provided as this error is generally thrown when no data is presented for authorisation.
S008 Invalid Licence Key The given licence key is invalid. Check the given licence key is the same that was provided by CityPay or that the key has not been superseded by a newer version.

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.

ErrorCode Error Message Further Information
T001 Duplicate Transaction Error A transaction with the same transaction reference and card details has been provided.
T002 Transaction exceeds required level
T003 Transaction is not a valid capture An invalid capture request was requested. Check the request to ensure the capture request matches the documentation.
T004 Transaction is not a valid reversal An invalid reversal request was requested. Check the request to ensure the reversal request matches the documentation.
T005 3D Secure Authentication Error Caused when the PARes fails digital signature validation. Cardholders should try another form of payment.
T006 3D Secure Authentication Required A transaction is required to be fully authorised using 3d secure by returning a valid CAVV and AuthenticationResult=Y Transactions are blocked if the transaction is not fully authenticated, this includes card schemes not participating. To allow this transaction to process, 3d secure must be bypassed or processed using a different coding.
T007 Pre-Auth not available for card scheme Caused when the card scheme is not able to perform pre-authorisation requests. Cardholders should try another form of payment.
T008 Pre-Auth not available for Acquirer Caused when the Acquirer is not able to perform pre-authorisation requests. Cardholders should try another form of payment.
T009 Transaction already cancelled Caused when the transaction has already been cancelled A previous request for cancelling the transaction has been succesfully obtained.
T010 Cannot cancel pre-auth transaction Caused when the transaction is not available to be cancelled Normally occurs when a transaction is not set as pre-authorised and does not allow for cancellation to occur.
T011 Transaction already completed Caused when the transaction has already been completed A previous request for completing the transaction has been succesfully obtained.
T012 Cannot complete pre-auth transaction Caused when the transaction is not available to be completed Normally occurs when a transaction is not set as pre-authorised and does not allow for completions to occur.
T013 Transaction was not authorised A post authoriation action has found that the original transaction was not authorised and therefore the action cannot be completed The action cannot be completed on a non authorised transaction.

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.

ErrorCode Error Message Further Information
W001 Tokens amount not present
W002 Tokens Amount Not an Integer
W003 Email Address Not Supplied
W004 PostCode/ZipCode Not Supplied
W005 Country Not Present
W006 Town/City Not Present
W007 First Address Line Not Supplied
W008 Last Name Not Supplied
W009 First Name Not Supplied
W010 Password not supplied
W011 Password Must be at least 8 chars
W012 An error occurred creating the account
W013 Could not find a wallet from the given criteria
W014 An error occurred obtaining the wallet
W015 Wallet is de-activated
W016 Password contains illegal characters The password can only contain alphanumeric characters with no spaces
W017 Ceiling Limit Exceeded
W018 Error purchasing tokens
W019 Error redeeming tokens
W020 Redirect address is invalid
W021 Merchant ID is invalid
W022 Merchant ID is not supplied
W023 Request was from an invalid source
W024 Terms and conditions were not agreed to The customer failed to check the terms and conditions checkbox.
W025 Floor limit not reached The amount is not greater than the floor limit set for your account.
json xml