Paylink-v3 Token API Reference

Supported Types

Paylink supports XML or JSON requests. This allows for developers to integrate with languages they are familiar with. A payment request can be selected as

  1. JSON request by setting the content-type header to "application/json
  2. Xml request by setting the content-type header to "text/xml"

JSON

JSON data representation provides support for name-value pairs, array values accessed by index in a familiar yet language independent form. JSON names are case sensitive with integer and boolean  values specified in unquoted form.

Paylink Token Request
{
	"merchantId": <integer_value>,
	"licenceKey": "<string_value>",
	"identifier": "<string_value>",
	"test": "<string_value>",
	"amount": <integer_value>,
	"cardholder": {
		"title": "<string_title>",
		"firstName": "<string_value>",
		"lastName": "<string_value>",
		"address": {
			"address1": "<string_value>",
			"address2": "<string_value>",
			"area": "<string_value>",
			"postcode": "<string_value>"
		}
	},
	...
}
Paylink Token Response (Error)
{
	"id": "<string_value>",
	"result": 0,
	"errors": {
		"code": "<string_value>",
		"msg": "<string_value>"
	}
}
Paylink Token Response (Success)
{
	"id": "<string_value>",
	"result": 1,
	"url": "<string_value>"
}

XML

The XML data representation provides support for arbitrarily nested name-value pairs. Element names are case sensitive . Where values are omitted or specified in the form of an empty element such as <element/>  these values are considered as not provided or empty. 

Paylink Token Request
<paylinkTokenRequest>
	...
	<identifier>value</identifier>
	<merchantId>value</merchantId>
	<licenceKey>value</licenceKey>
	<cardholder>
		<title>value</title>
		<firstName>value</firstName>
		<lastName>value</lastName>
		<address>
			<address1>value</address1>
			<address2>value</address2>
			<area>value</area>
			<postcode>value</postcode>
		</address>
	</cardholder>
...
</paylinkTokenRequest>
Paylink Token Response (Error)
<paylinkTokenResponse>
	<id>string_value</id>
	<result>0</result>
	<errors>
		<error code="code" msg="msg" />
	</errors>
</paylinkTokenResponse>
Paylink Token Response (Success)
<paylinkTokenResponse>
	<id>string_value</id>
	<result>1</result>
	<url>url_value</url>
</paylinkTokenResponse> 


Paylink Token Request

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 of the request
  2. the content type of the request
  3. the validity of the request

Once these have all been met, a response will be returned which provides a url which should then be used to redirect the user's browser to payment.

Merchant Authentication Fields

These fields are required to identify your account


{
	"merchantId": 12345,
	"licenceKey": "ASCnrtsona46on",
	...
}
<paylinkTokenRequest>
	...
    <merchantId>12345</merchantId>
    <licenceKey>ASCnrtsona46on</licenceKey>
	...
merchantId

int, Required 

The merchant id that 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 licensed version of the Paylink service that is being run. The licensed version holds default configurations which may streamline the Required parameters for running the service.

If you are migrating from a previous version of Paylink, you will need to obtain a new licence key, if you have not been supplied with a new key, please contact support.

Processing Configuration

Fields used to identify what is to be processed


{
	"amount": 7495,
	"clientVersion": "MyApp 1.0.1",
	"email": "paylink@yourstore.com",
	"identifier": "0209fcb3fe72",
	"test": true
	...
}
<paylinkTokenRequest>
	...
    <amount>7495</amount>
    <clientVersion>MyApp 1.0.1</clientVersion>
	<email>paylink@yourstore.com</email>
	<identifier>0209fcb3fe72</identifier>
	<test>true</test>
	...
amount

int, Required

The amount field is used to specify 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) (Advanced)

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 MID and the licence key.

identifier

string, Required (5-50 characters)

The identifier field is used to identify 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.

test

string, Required (default=true)

The test field specifies mode of the transaction as follows

true: the transaction will be processed as if it was a live transaction however authorisation will be performed by 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 using an upstream Payment Card Acquirer such that, on a successful transaction, the relevant Payment Card Holder Account will be deducted the amount of the transaction on authorisation and the Merchant credited.

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.


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

cardholder

object, (Optional)

The cardholder node represents a container for the following card holder-related fields.

email

string, (Optional)

The cardholder.email field is used to for the payment card holder's email address. This field is used to send a receipt from the Paylink service direct to the payment card holder.

In any given transaction, the email address for the payment card holder may be

  1. provided through the Paylink Token Request to enable pre-population of the Paylink Payment Form; or
  2. collected through the Paylink Payment Form.
firstName

string, (Optional)

The cardholder.firstName field refers to the first name of the card holder.

lastName

string, (Optional)

The cardholder.lastName field refers to the last name of the card holder.

mobile

string, (Optional)

The cardholder.mobile field refers to a known mobile number of the card holder. This can be used for

  1. Data collection via the Paylink Payment Form; or
  2. Optionally send an SMS on completion of a transaction. This feature is a licensable option and is not configured by default.
title

string, (Optional)

The cardholder.title field refers to the title for the card holder

address

(Optional)

The cardholder.address entity represents a container for the following address-related fields.

address1
address2
area

string, (Optional)

The cardholder.address.address1 , cardholder.address.address2 and cardholder.address.area fields are used for to the billing address of the payment card holder. The billing address for the payment card holder is Required if AVS address checking is enabled.

In any given transaction, the billing address for the payment card holder may be

  1. provided within the Paylink Token Request to enable pre-population of the Paylink Payment Form; or
  2. collected through the Paylink Payment Form.
postcode

string, (Optional)

The cardholder.address.postcode field is used for the postal/zip code associated with the billing address of the payment card holder. The postal code is Required if AVS postcode checking is enabled.

In any given transaction, the postal code associated with the billing address for the payment card holder may be

  1. provided through the Paylink Token Request to enable pre-population of the Paylink Payment Form; or
  2. collected through the Paylink Payment Form.
country

string, (Optional) (RFA)

The cardholder.address.country field is used to specify the country of the billing address of the payment card holder.

In any given transaction, the country of the billing address for the payment card holder may be

  1. provided through the Paylink Token Request to enable pre-population of the Paylink Payment Form using an ISO 3166 two or three character country code.; or
  2. collected exclusively through the Paylink Payment Form.

Advanced CardHolder Security Options

These fields are used only where the user of your site should be restricted to the same browser.

acceptHeaders:

string, (Optional) (Advanced)

The cardholder.acceptHeaders field may be used to specify the accept headers string generated by the Customer Browser on GET and POST requests. This field may be used to lock the Paylink Payment Form to the Customer Browser such that, if the Customer were to attempt to use a different browser to conclude the Payment transaction or a malicious third party was to attempt to hijack the Payment transaction, an error will be generated.

remoteAddr:

string, (Optional) (Advanced)

The cardholder.remoteAddr field may be used to specify the remote IP address of the customer's browser. This field may be used to lock the payment process to the shopper by referencing the IP Address from which the original requests emanate. Should the shopper use a different source address or a malicious third party was to attempt to hijack the transaction, an error will be generated.

While locking a Payment transaction to an IP Address may reduce the risk of Payment transaction hijacking, Customers that access the Merchant Application from mobile broadband services, domestic broadband services or indirectly through a proxy cache may change their IP address on each GET or POST operation.

userAgent:

string, (Optional) (Advanced)

The cardholder.userAgent field may be used to specify the user agent string of the Customer Browser. This field may be used to lock the Paylink Payment Form to the Customer Browser such that, if the Customer were to attempt to use a different browser to conclude the Payment transaction or a malicious third party was to attempt to hijack the Payment transaction, an error is generated.

Some browsers may vary this value depending on installed plugins. Paylink only supports values that may be directly compared.

Configuration Fields

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


{
	"config": {
		"acsMode": "inline",
		...
	}
}
<paylinkTokenRequest>
	...
    <config>
    	<acsMode>inline</acsMode>
	</config>
	...
config

(Optional)

Container for config options. When specified, config items will override any stored account values.

acsMode

string, (Optional) (default = iframe)

The config.acsMode field specifies the approach to be adopted by the Paylink payment form when displaying a 3-D Secure authentication window. The values may be as follows

iframe: shows the 3-D Secure ACS in an iframe dialog, neatly embedding it in Paylink. This provides a more seamless flow for the card holder who is able to validate and authenticate their card through the dialog provided by their bank.

inline: an inline mode transfers the full browser window to the ACS which allowing the payment card holder to see their payment card issuer's details and the accompanying SSL connection status and certificate in the address bar of the Customer Browser.

If you request an iframe mode and the browser width is deemed as being small (< 768px) then an inline mode will be enforced. This is to ensure that mobile users have an improved user experience.

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 secrets and not be displayed in the browser, for instance a session token on your server. A custom parameter can display as a text field, select list, checkbox or any html5 input type.

customParams

array, (Optional)

The config.customParams field may be use to add custom fields to the Paylink Payment Form to collect additional information for Merchant use.

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

Each custom parameter consists of the following properties

name

string, Required

refers to the name of the parameter used to specify the HTML form element name. This value can be referred back through the PostBack data.

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

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

placeholder

string, (Optional)

a value to set as the HTML5 placeholder attribute which will render in modern browsers.

label

string, (Optional)

a label that should appear immediately before the field element in the generated HTML form, describing what the form is used for. If this value is not supplied, the name value will be used

locked

boolean, (Optional)

refers to a boolean value that states whether the field is a locked field that prevents entry or amendment by the person completing the form.

pattern a string value which specifies the HTML5 validation logic which is checked before submitting the form for payment for example a value of "PC[0-9]*" will require a value such as PC1, PC123.
group

a value which can allow grouping of custom elements. If no value is provided, a default addition parameters group is rendered.

This allows logical grouping to the payment form for multiple elements. For example, 3 elements with the group of "Your Details" would be displayed with a heading of "Your Details" and each form element displayed under this heading. Any items not within this group will be displayed in their respective group titles or the default group.

Groups are rendered alphabetically.

order a value which allows you to order the position of elements in a grouping. For instance a value which has 1 will order first. Defaults to 0. Items can be pushed in front by using negative values.
fieldType

string, (Optional)

refers to the type of HTML 5 field entry and which may include ' hidden ' to represent a hidden field, or any other permitted value for the ' type ' attribute of the HTML 5 input element.

Should the fieldType be 'select' a select list will render however it will require populating with option values. Values can be constructed by providing a list in the value parameter, 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. To provide a different value and label to an item, you can delimit further with a colon ':'.

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>


expireIn

int, (Optional)

The config.expireIn field specifies a period of time in seconds after which the Payment Token or the associated transaction will expire. A default value of 30 minutes is specified by the Paylink service.

There is presently no limit imposed as to how long a given Payment Token may be held open; the technical limit being the period of time representable by a signed integer value.

The API can also convert an expiry time based on a string value. The following values are accepted

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
merch_branding

string, (Optional)

The config.merch_branding field may be used to specify a URL for a custom cascading style sheet ("CSS") for the Merchant Application that the Payment Form may use to customise the appearance of the Payment Form.

merch_logo

string, (Optional)

A URL of a merchant logo to include. The URL should be delivered using HTTPS.

merch_terms

string, (Optional)

A URL of the terms of payment that you wish to be confirmed. If provided, a link and checkbox will be added that will be Required to be checked before payment may continue.

lockParams

string, (Optional)

The config.lockParams field may be used to lock fields which are displayed in the form.

For example, if the cardholder.address.postcode field were to be specified in the config.lockParams field, this would will prevent the customer amending the postal code for the billing address of the payment card holder.

Field locking may be specified on a fine-grained parameter level such as cardholder.address.postcode, or cardholder.address.address1; or alternatively on a more coarsely-grained, container-level basis such as cardholder.address and cardholder which operates to lock all of the address-related fields and all the payment card holder-related fields respectively on any Paylink Form.

The following fields that may be locked are as follows

"cardholder": {
  "firstname": "John",
  "lastname": "Smith",
  "email": "test@citypay.com",
  "address": {
   "address1": "12 New Street",
   "address2": "Old Plaza",
   "area": "",
   "country": "AU",
   "postcode": "4110"
  }
 },

JSON

The value of config.lockParams is specified as an array of string, using the JSON form.

      "lockParams" :[ "cardholder.address.postcode", "cardholder.address.country" ]
    

XML

The value of config.lockParams is specified as a string list value, delimited by a comma

      <lockParams>cardholder.address.postcode</lockParams>
<lockParams>cardholder.address.country</lockParams>
    

(Optional)

The config.options field specifies a list of configuration options to be applied to the transaction which provide, complement or override default values or the MID configuration for these options. Available options are

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);

CREATE_CAC_ACCOUNT_ON_AUTHORISATION : which Required where creating card holder 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 card holder must enter an email address;

JSON

Options are provided as an array of strings, i.e.

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

XML

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

If BYPASS and ENFORCE options for the same underlying functionality exist or are supplied in the config.options array, the BYPASS option will be take precedence.

passThroughData:

Nested Key Pairs, (Optional)

To allow for greater inoperability, 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.

"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
                }
            ]
        },
...

The Paylink system doesn't restrict you to simple key value pairs and allows for nested complex objects to be supplied as demonstrated in the example above.

Pass through data will be supplied on a post back call or a post redirection.

passThroughHeaders:

string pairs, (Optional)

When sending a post back, it may be necessary to include authentication information or similar to the application you are calling. Values can be provided in the Token Request which are added as HTTP headers in the post back. For example

"config" {
        "passThroughHeaders": {
            "key1": "value1",
            "key2": "value2"
        },

will result in HTTP headers being sent

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

The pass through headers are only actioned on a post back and not redirection.

postback:

string, (Optional)

The config.postback field specifies a URL which is used by the Paylink service to inform the Merchant Application of the outcome of the transaction. This URL must be a valid URL which is accessible by the Paylink service on ports 80 or 443. Merchant internal or localhost addresses often used for development testing cannot be used unless made publicly available.

Within development we suggest using a product such as ngrok.com to create a secure tunnel for building your web hook.

In any given transaction, a postback URL may be provided through each Token Request or fallback to a default configured value in your panel.

If a URL is specified by the Paylink Token Request, it will take precedence over the configured value.

A valid URL is considered

  1. not an empty string
  2. is RFC1738 compliant
  3. is a valid, reachable port

A preconfigured URL may be expressly disabled by forwarding a value of none in your Token Request.

Testing HTTPS connections.

Paylink supports POSTback URLs where the endpoints use self signed certificates, or certificates signed by a private Certification Authority.

postback_policy:

string, (Optional) (default = async)

The config.postback_policy field is used to specify a policy for POSTback URL handling, the options for which are as follows

sync: the operation will be performed before a Response is returned to the Customer Browser to ensure that the transaction may be authoritatively confirmed as successful by the Merchant Application before the outcome of the transaction is communicated to the customer.

async : the operation will be performed in the background whilst a response is returned to the customer's browser effectively speeding up the communication of the result to the customer

none: no operation will be performed.

No value or any other value will trigger the default setting.

redirect:

string, (Optional) deprecated - see redirect_success and redirect_failure

The config.redirect field may contain a Redirection URL which the Customer Browser is redirected to, by the Paylink Payment Form, using a POST operation on successful or failed processing of a transaction; subject to MID configuration.

In any given transaction, the Redirection URL may be

  1. provided by the MID configuration; or
  2. provided to the Paylink through the Paylink Token Request.

If no config.redirect value is specified by MID configuration, or through the Paylink Token Request, the Paylink Payment Form will not return to the Merchant Application. The Payment Form will provide advice of the outcome of the transaction to the Customer and leave the Customer Browser in a state where the Customer must close the relevant browser tab or window.

The config.redirect field has been superseded by the config.redirect_success and config.redirect_failures fields, respectively.

redirect_delay:

int, (Optional)

The config.redirect_delay field may be used to specify a delay in seconds before the Customer Browser is redirected by the Paylink Payment Form on conclusion of a successful transaction. If the transaction fails, subject to MID configuration, the customer may be given the opportunity to resubmit the transaction with amended details for reprocessing.

If no value is set or is a negative value, the Paylink Payment Form will not redirect the Customer Browser until a Customer has clicked on a button to return to the store.

If config.redirect_delay is set to 0, the Customer Browser will be redirected immediately on a successful transaction; there will be no delay.

If config.redirect_delay is set to a value greater than 0, the Paylink Payment Form will display a modal dialog in the Customer Browser and redirect after the number of specified number of seconds have elapsed.

redirect_success:

string, (Optional)

The config.redirect_success field may contain a Redirection URL which the Customer Browser is redirected to, by the Paylink Payment Form, using a POST operation on successful payment processing of a transaction; subject to MID configuration.

In any given transaction, the Redirection URL may be

  1. provided by the MID configuration; or
  2. provided to the Paylink through the Paylink Token Request.
  3. If no redirect_success field is provided, the value from the config.redirect field will be used

If no config.redirect_success value is specified by MID configuration, or through the Paylink Token Request, the Paylink Payment Form will not return to the Merchant Application on successful conclusion of a transaction, but will instead provide advice of the outcome of the transaction to the Customer and leave the Customer Browser in a state where the Customer must close the relevant browser tab or window.

redirect_failure:

string, (Optional)

The config.redirect_failure field may contain a Redirection URL which the Customer Browser is redirected to, by the Paylink Payment Form, using a POST operation on failed payment processing of a transaction; subject to MID configuration.

In any given transaction, the Redirection URL may be

  1. provided by the MID configuration; or
  2. provided to the Paylink through the Paylink Token Request.
  3. If no redirect_success field is provided, the value from the config.redirect field will be used

If no config.redirect_failure value is specified by MID configuration, or through the Paylink Token Request, the Paylink Payment Form will not return to the Merchant Application on a failed transaction that the Customer has not attempted to resubmit, but will instead leave the Customer Browser in a state where the Customer may only close the relevant browser tab or window.

return_params:

boolean, (Optional)

The config.return_params field is used to determine whether the Paylink Payment Form should return the results of the transaction using a POST operation on redirection of the Customer Browser to the Merchant Application.

If a config.return_params value of true is specified, the POST operation will be accompanied by the results for the transaction passed as the body of the request.

If no value is specified for the config.return_params field, or any other value is specified, the POST operation will not be accompanied by the results for the transaction.

It is not recommended for a Merchant Application to rely on values it receives indirectly from the Paylink Payment Form via the Customer Browser as there is a risk that the values may have been adjusted immediately before the request is made to the Redirection URL. The Merchant Application can, however, validate the values it receives through the Redirection URL POST operation by submitted them to a suitable a SHA1 or SHA256 cryptographic hash function.

renderer:

string, (Optional) (default = main)

The config.renderer field specifies the Paylink Payment Form to use for the transaction. The available options are

main : which refers to the main renderer, the default responsive design for the Paylink Payment Form which will adapt its layout to the Customer Browser in use such as mobile or desktop.

Card Holder Account Fields

accountNo:

string, (Optional) (Required with Card Holder Account Integration)

The accountNo field is used to specify a Client unique account number that the Paylink service should use when creating a Cardholder Account. The value of the accountNo field is an alpha-numeric string generated by the Merchant and should be no longer than 20 characters in length.

Cart Fields

cart:

(Optional)

Container for cart options.

The shopping cart represented in the cart.contents field group is not cross checked with the amount field

productInformation:

string, recommended

The cart.productionInformation field specifies information about the product or service that is the subject of the transaction. It will be rendered by the Paylink Payment Form in the header of the page.

productDescription:

string, (Optional)

The cart.productDescription field provides full text to the payment header and overrides the productInformation field.

mode:

integer, (Optional)

The mode field specifies the behaviour or functionality of the cart as follows --

Value Meaning
0 No cart functionality applies. This is the default value for the mode field.
1 Read-only cart functionality applies: the cart is shown with a breakdown of the item details provided by objects contained in the the contents array.
2 Selection cart functionality applies: the cart is shown as a drop-down box of available cart items that the customer can a single item select from.
4 "Dynamic" cart functionality applies: a text box is rendered to enable the operator to input an amount.
5 "Multiple item" cart functionality applies: the cart is displayed with items rendered with selectable quantities
contents:

array, (Optional)

The cart.contents field represents an array containing zero, one or more cart items represented by objects of the form --

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

string, recommended

The sku field refers to the stock control unit identifier for the cart item.

label:

string, recommended

The label field refers to a descriptive label for the cart item.

category:

string, (Optional)

The category field refers to the category or classification of the cart item. For example, items may be categorised as food or non-food items, fancy goods, beverages and so forth. The Paylink Payment Form does not constrain the value of the category field to a particular set of categories; these are defined by the Merchant.

brand:

string, (Optional)

The brand field refers to the brand of the cart item. The Paylink Payment Form does not constrain the value of the category field to a particular set of brands; these are defined by the Merchant.

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; these are defined by the Merchant.

count:

integer, (Optional)

The count field refers to the quantity of units that, taken together, represent the cart item. 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.

amount:

integer, (Optional)

The amount field refers to the monetary amount chargeable in respect of the cart item, expressed in "lowest denomination form" ("LDF"). 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.

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

Paylink Token Response

JSON Example

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

XML Example

<paylinkTokenResponse>
    <id> ND4NjIzNzA4NzQyNjA0NTU </id>
    <result>1</result>
    <url> https://secure.citypay.com/paylink3/RV1FFV4/ND4NjIzNzA4NzQyNjA0NTU </url>
</paylinkTokenResponse>
Merchant Authentication Fields

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 which is either

0 which indicates that an error was encountered while creating the token; or

1 which indicates that a Token was successfully created.

On successful validation, authentication and processing of the Paylink Token Request

url:

string, Required (when result=1)

The url is the Paylink Token URL which is to be used by the Customer Browser to access the Paylink Payment Form.

On failure of the Paylink Token Request

errors:

Required (when result=0)

An array of errors which are found when attempting to create the payment URL

[n] code:

string, Required (when result=0)

The errors[n].code field contains an error code indicating why the Paylink Token Request could not be completed successfully.

[n] msg:

string, Required (when result=0)

The errors[n].msg field contains an error message indicating why the Token could not be generated.

+44 (0)1534 884000