Browser Extension Service (cp_bx)
The browser extension service is a JavaScript plugin that enables integrators to simplify their 3DSv2 browser based authentication requirements by collecting and fingerprinting browser data and appending the encoded data to a HTMLElement within the DOM of your page. This data is then forwarded to the authorisation server as part of the data requirements to process with CityPay's 3DSS server.
The citypay.js script is designed to be asynchronous by not blocking your browser onload. There is a small initialisation required which queues desired commands until the actual script loads.
The script should be included in your document by adding a script element. This can be added to the head or end of your document.
JavaScript
<script>
window.citypay=window.citypay||function(){(citypay.q=citypay.q||[]).push(arguments);};
citypay('bx');
</script>
<script async src="https://api.citypay.com/js/citypay.js"></script>
With this setup, the script will create the browser data and add the value to the first form in your page at document.forms[0]
To target different forms or elements, you can provide a basic call or an options object. The options object is required if you are utilising the risk extensions.
| Call | Options |
|---|---|
citypay('bx') | This call will target document.forms[0], appending a hidden form element called cp_bx. |
citypay('bx', 1) | This call will target document.forms[1], appending a hidden form element called cp_bx. |
citypay('bx', "my_form") | This will target <form name="my_form">, appending a hidden form element called cp_bx. |
citypay('bx', "my_id") | This call will target <input id="my_id"> and set the value of the field element to the generated bx value. |
citypay('bx', (data) => log(data)) | This call will process the value to a callback function for manual intervention. |
Once the user has pressed the submit button on your form, the data will be forwarded in your POST field elements as cp_bx.
This value is base64 encoded and should be sent by your server to the authorise or charge operation of the server. There is no need to store this value.
The bx function contains a risk extension which helps to facilitate transaction risk assessments by enabling 3DS Method Data handling.
In effect this allows for the Authorisation Control Server (ACS) to fingerprint or touch the user's browser before authentication is performed. This is performed by:
- Attaching an event listener to the card entry field
- when 8 numerics (bin) have been entered, an async call is made to a CityPay endpoint to check whether the card supports 3DS Method Data
- Should the card be supported, a hidden iframe is added to the page and a hidden POST call is made to the 3DS Method URL provided by the card issuer.
- CityPay's servers then receive a notification response which is collated on the authentication request message subsequently sent to the card schemes at the authentication stage.
To enable 3DS Method Data handling, you should add cc-input to the options object
Targeting form
citypay('bx', { 'form': 1, 'cc-input': 'id_or_name' })
This call will target document.forms[1] appending a hidden form element called cp_bx and applying the risk handler to the input field based on the given id.
Targeting id
citypay('bx', { 'id': 'my_id', 'cc-input': 'id_or_name' })
This call will target <input type="hidden" id="my_id" /> and set the value of the field element to the generated bx value and applying the risk handler to the input field based on the given id.
| Element | Type | Usage | Description |
|---|---|---|---|
| cc-input | string | Optional | The id of the HTML input field where card data is input for attaching risk assessments. |
| cc-logo | boolean | Optional | If true will enable the cc-input field to add a card scheme logo when a bin range is realised |
| cc-callback | function | Optional | A function that can be targeted when validation on the card data is achieved or bin range data is assessed. |
| id | string | Optional | The id of the HTML element normally an input field |
| encode | boolean | Optional | Whether the value is encoded. Should be set to this to forward data to processing. Defaults to true. |
| form | string or int | Optional | The name or numeric of the HTML form being targeted |
| name | string | Optional | The name of the HTML input element |
Working Example The example form runs the script against your current browser, generating the base64 encoded packet. For those concerned with data exposure, an unpacked version is also displayed. Please note that the IP address and accept headers are encoded in the form.
The following example provides an example usage where the risk assessment logic is applied with a callback luhn check and card no logo applied
CityPay Browser Extension Service example. For further information please consult support@citypay.com