Developer Documents

In order to protect your application from receiving unexpected or unwanted card details in the event that the CardLock library is either misconfigured or not supported (e.g. by users without JavaScript enabled in their browser), the default submission action of the payment form should be updated to the
Pay360 landing page at:

https://secure.pay360.com/cardlock/fallback

This is a secure page which explains to the cardholder that their payment could not be processed, reassures them that their card details are safe, and advises them to contact you for assistance.

Using the example above, the form element would be changed to the following:

<form id="paymentForm" method="post" action="https://secure.pay360.com/cardlock/fallback">

A new hidden field needs to be added to the form which will pass the generated CardLock token into the form submission. For example:

<input id="token" type="hidden" name="token" value="" />

This field can have any id or name; the id is specified when invoking the JavaScript library, and the name should correspond to one that your application will be expected to receive and process.

The CardLock JavaScript library can be loaded from the Pay360 domain directly; you don’t need to store a local copy. The library should be loaded from:

https://secure.pay360.com/cardlock/scripts/v2/cardLock.min.js

<script type="text/javascript" src="https://secure.pay360.com/cardlock/scripts/v2/cardLock.min.js" crossorigin="anonymous"></script>

Once included onto the page, CardLock is invoked as follows:

<script type="text/javascript">
	new CardLock({
		publishableId: '',
		formElementId: '',
		panElementId: '',
		tokenElementId: '',
		merchantAction: ''
	});
</script>

The mandatory fields for this call are:

https://merchant.example.com/process-payment

You can optionally provide details of:

It is up to you to ensure that the library is invoked after the form is rendered onto the page; either a conventional event listener (e.g. window.onload) can be used, or a JavaScript library (such as jQuery) may be used to hook into this. It is also possible to include the script after the form in the relevant HTML.

Example CardLock Library request:

<script type="text/javascript" src="https://secure.pay360.com/cardlock/scripts/v2/cardLock.min.js" crossorigin="anonymous"></script>

<script type="text/javascript">
	new CardLock({
		publishableId: 'phLDye-NTA-TdcUk0jkpfg',
		formElementId: 'paymentForm',
		panElementId: 'cardNumber',
		cvvElementId: 'securityCode',
		tokenElementId: 'token',
		merchantAction: 'https://merchant.example.com/process-payment'
	});
</script>

When an error occurs during tokenisation, for example, invalid input or bad credentials were provided, the error is shown in a standard alert dialogue box on our site.

Example error display:

If you would prefer to keep error handling in line with the user experience on your site then you should implement a custom error handler. For example, you may want to use a different alert-style dialog, use custom styling or inject validation messages into the form to reflect missing or invalid values.

To do this you will need to pass a function pointer into the configuration when invoking the CardLock library.

For example:

<script type="text/javascript">
	var errorHandler = function( response ) {
		alert( "Received a status " + response.status + " response, with message " + response.message );
	};

	new CardLock({
		publishableId: 'phLDye-NTA-TdcUk0jkpfg',
		formElementId: 'paymentForm',
		panElementId: 'cardNumber',
		cvvElementId: 'securityCode',
		tokenElementId: 'token',
		merchantAction: 'https://merchant.example.com/process-payment',
		errorHandler: errorHandler
	});
</script>

The error handler function will receive a single argument, which has the following properties:

In addition to the error handler, you can also implement a pre-submission callback. This is called when the form is submitted, but prior to the tokenisation request. This can be used to implement additional client-side validation, for instance.

To do this you will need to pass a function pointer into the configuration when invoking the CardLock library.

For example:

<script type="text/javascript">
	var preSubmitCallback = function() {
		alert( "Submitting tokenisation request" );
		return true;
	};

	new CardLock({
		publishableId: 'phLDye-NTA-TdcUk0jkpfg',
		formElementId: 'paymentForm',
		panElementId: 'cardNumber',
		cvvElementId: 'securityCode',
		tokenElementId: 'token',
		merchantAction: 'https://merchant.example.com/process-payment',
		preSubmitCallback: preSubmitCallback
	});
</script>

The pre-submission callback can return true to allow tokenisation to continue, and false to prevent the form submission.