Advisory: 3DSv2 Browser Extension Service
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.
Usage
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.
<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.
| Basic Call | Options Object |
|---|---|
citypay('bx') |
citypay('bx', {}) |
This call will target document.forms[0] appending a hidden form element called
cp_bx
|
|
|
|
|
citypay('bx', 1) |
citypay('bx', { 'form': 1 }) |
This call will target document.forms[1] appending a hidden form
element called cp_bx |
|
|
|
|
citypay('bx', "my_form") |
citypay('bx', { 'form': 'my_form' }) |
This call will target <form name="my_form" action="..." > appending a hidden form
element called cp_bx
|
|
|
|
|
citypay('bx', "my_id") |
citypay('bx', { 'id': 'my_id' }) |
This call will target <input type="hidden" id="my_id" /> and set the value of the
field
element to the generated bx value
|
|
|
|
|
citypay('bx', (data) => log(data)) |
citypay('bx', { 'fn': (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.
Reducing Risk
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.
cc-input to the options object
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.
|
|
|
|
|
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.
|
|
|
|
|
Options
The following options are available
| 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.