Windcave | Hosted Fields | EFTPOS | Payment Gateway | Online Credit & Debit Card Processing

Contents

Overview
Pre-requisites: Supported Browsers; Content Security Policy
Implementing Hosted Fields: JavaScript Files; Page Layout; Hosted Fields Examples; Creating Hosted Field Components; Styling; Data Submission; 3DSecure; Hosted Fields Controller References

Overview

The Windcave Hosted Fields solution is a client-side JavaScript (JS) library which utilizes the AJAX POST functionality and enables merchants to customize the UI for accepting payments on their checkout page with their preferred layout and styling, while maintaining PCI compliance.

For detailed information about Hosted Fields and its customizable features, please review the page below.

Pre-requisites

Below outlines the pre-requisites required to implement the Hosted Fields solution.

To get started with your Windcave Hosted Fields integration you will need a REST API account, please sign up for an account, or contact us and complete the requirements gathering form to request development credentials.

Once signed up, our team will create development credentials based on the requirements provided in the above form. We will provide a API username and API Key; both of which must be securely transferred and stored on your web-server.

Supported Browsers

This table outlines the currently supported Web Browsers and versions:

Browser	Version
Chrome	70+
Edge	80+
Firefox	90+
Internet Explorer	11
Opera	85+
Safari (iOS/MacOS)	12+

Content Security Policy

The Windcave Hosted Fields solution is very dynamic and may load various resources to ensure the payment checkout functions as expected.

To ensure everything is able to load correctly, merchants may need to include additional Content Security Policies (CSP) to prevent blocking of necessary resources.

Please note merchants not using any Content Security Policies will not need to make any changes.

Outlined below are the basic directives to be whitelisted:

Directive	Production (SEC)	User Acceptance Testing (UAT)
connect-src	https://sec.windcave.com	https://uat.windcave.com
font-src	https://sec.windcave.com/fonts/	https://uat.windcave.com/fonts/
img-src	https://sec.windcave.com	https://uat.windcave.com
script-src	https://sec.windcave.com/js/	https://uat.windcave.com/js/
style-src	'unsafe-inline'	'unsafe-inline'
frame-ancestors	https://sec.windcave.com	https://uat.windcave.com

Implementing Hosted Fields

As Hosted Fields works in conjunction with Restful API, the merchant needs to create a new payment session using a Restful Create Session request.

Below is an example of the Create Session response:

For more detail on available session objects, please refer to the Windcave Rest API.

Restful API Create Session response

          {
            "id": "00001200002116585f8d891123456787",
            "state": "init",
            "links": [{
              "href": "https://sec.windcave.com/api/v1/sessions/00001200002116585f8d891123456787",
              "rel": "self",
              "method": "GET"
            }, {
              "href": "https://sec.windcave.com/pxmi3/F0AD7308709093294215B271C6E087134C33EB015769FCFBA5322EE8F69378EB1D895FD231D9A10C116A6DA19F34F460A",
              "rel": "hpp",
              "method": "REDIRECT"
            }, {
              "href": "https://sec.windcave.com/pxmi3/F5A2BEDE53131E04066A068518F8D02BC422773FE5427CE19E05A5472028EABF01AC08C38D6378B26B6FD68134DCC0FBD",
              "rel": "seamless_hpp",
              "method": "REDIRECT"
            }, {
              "href": "https://sec.windcave.com/pxmi3/F02CBA539AA694D6ECDEA85D44CCE23679B11B3ADEAE7484F34E591DF44D96E0ADC35F47CFD7AC50F0C10805AE08D964C",
              "rel": "submitCard",
              "method": "FORM_POST"
            }, {
              "href": "https://sec.windcave.com/pxmi3/F6AF0F75C5EE172E1E6C29B4AAF60023A48BFA2103B78F50DF414F5D93902847D7DAF157683429F15E53995AC645D5DA1",
              "rel": "paymentMethod:paypal",
              "method": "REDIRECT"
            }, {
              "href": "https://sec.windcave.com/mh/F105F622A16AA024CCCC4D7BCF4077B687C8E180886CF76C4DEB488635298070089E907543745D2BB7B60845E9C6BED34",
              "rel": "ajaxSubmitCard",
              "method": "AJAX_POST"
            }, {
              "href": "https://sec.windcave.com/mh/FA0F72460E5A7D66289271BBD5E7F625EE767DC8A0FEE92E8E24496D8E0C20BC3E6601EE2D2CF7E9F3074F6515D131923",
              "rel": "ajaxSubmitGooglePay",
              "method": "AJAX_POST"
            }, {
              "href": "https://sec.windcave.com/mh/FBA081BB5FC6805CD9DC88DA56A14020B01492B1C4ED273452DF9E668BD9334E07ED370DD3E7F10B007C0820A79DE415D",
              "rel": "ajaxSubmitApplePay",
              "method": "AJAX_POST"
            }
            ]
          }

The merchant needs to select the link with rel set to ajaxSubmitCard. This must be passed to the Hosted Fields controller object when triggering a submission.
Note: Hosted Fields does not require the session to be created immediately; it can be deferred to the point of submission if the merchant chooses.

JavaScript Files

In order to implement Hosted Fields into the payment checkout, merchants need to load the Windcave JS files onto the <head> element of the checkout page:

Important: All JS files MUST be referenced from the Windcave domain, merchants are not permitted to download and serve these files from their own servers.

          

             <script src="https://sec.windcave.com/js/lib/hosted-fields-v1.js"></script>
             <script src="https://sec.windcave.com/js/windcavepayments-hostedfields-v1.js"></script>

To improve the page loading times, these scripts can be safely marked as async or defer per the below example:

          

             <script async src="https://sec.windcave.com/js/lib/hosted-fields-v1.js"></script>
             <script async src="https://sec.windcave.com/js/windcavepayments-hostedfields-v1.js"></script>

Page Layout

Hosted Fields allows merchants to define the layout and styling of their checkout page; to prepare this, the merchant needs to prepare for the Hosted Fields elements.

Each individual card form element must have its own container therefor containers that are provided are dependent on the use case.

If using one-off / initial card tokenization the minimal set of fields must include:

Card Number
Expiry Date
- Components can be separated if required:
  - Expiration Date - to capture MM/YY in a single field
  - Expiry Month + Expiry Year - to capture expiry month and expiry year in separate fields

For Rebilling, an additional verification CVV can be included.

Supported Fields for Hosted Fields

Below are the full set of fields currently supported by Hosted Fields:

Card Number
Expiration Date
Expiration Month
Expiration Year
CVV
Cardholder Name
Billing Street Address 1
Billing Street Address 2
Billing Street Address 3
Billing City
Billing Country
Billing Postal Code
Shipping Street Address 1
Shipping Street Address 2
Shipping Street Address 3
Shipping City
Shipping Country
Shipping Postal Code

Although there are no requirements of page container placements, merchants should use caution to avoid scenarios that may cause UX issues.

Hosted Fields Examples

Below is a simple example of the Hosted Fields solution for demonstration purposes only; integrations are not required to follow this design/format.

Merchant is using Bootstrap 4 and wants to accept the payment on their checkout page. This example uses only Card Number, Cardholder Name, Card Expiry and CVV in a 2x2 grid (or a single column on a smaller screen):

The following markup is used for the example above:

Sample code

          

          <div class="container panel">
            <div class="row">
              <div class="centered col-lg-6">
                <p>Card Number</p>
                <div class="field-container" id="number-div"></div>
              </div>
              <div class="centered col-lg-6">
                <p>Card Expiry Date</p>
                <div class="field-container" id="expiration-date-div"></div>
              </div>
              <div class="centered col-lg-6">
                <p>CVV</p>
                <div class="field-container" id="cvv-div"></div>
              </div>
              <div class="centered col-lg-6">
                <p>Cardholder Name</p>
                <div class="field-container" id="cardholder-name-div"></div>
              </div>
            </div>
          </div>

The field-container CSS class is Windcave's custom class that adds padding and a dark bottom border

Sample CSS

          

          .field-container {
             border-botton: 2px solid #000;
             padding: 6px;
             display: inline-block;
             width: 80%;
             height: 48px;
          }

Hosted Fields requires element containers to have unique IDs. These are passed into the Hosted Fields construction call to reference containers.

Hosted Fields can run 3D Secure if dictated by the transaction processing. If engaged, this will be displayed as a popup.

Creating Hosted Field Components

Once all JS files have been loaded, the REST Session created and the layout has been defined, the next step is to create the Hosted Fields component for the checkout page.

To do this, the merchant needs to call the WindcavePayments.HostedFields.create method, this method returns a Hosted Field controller that should be stored in a variable for future use.

The interface of the WindcavePayments.HostedFields.create method is as follows:

          

             WindcavePayments.HostedFields.create(options, loadTimeout, onSuccess, onFailure)

Where:

options is a JS object that contains settings for the Hosted Fields component (details in the next section)
loadTimeout is a time in seconds the Hosted Field constructor will wait for all the components to notify of their successful initialization before giving up. 'null' can be entered to give elements the time it takes to construct, in place of a finite value.
onSuccess is a callback that is triggered when all the Hosted Fields elements are successfully constructed.
onError is a callback that is triggered when constructing of any of Hosted Fields elements has failed. This calledback gets called with two parameteres - stage and errorMesseage. Currently the only acceptable value for stage the merchant can expect is setup.

Please note that onSuccess and onError callbacks passed to the create method are strictly to indicate the result of Hosted Fields component constructing. The onSuccess and onError callbacks are NOT used to indicate the payment outcome.

options Object

This object has a variety of different fields that can be included, some fields are required while others are optional:

Required Fields

Field Name	Description
fields	The subobject containing the configuration for Hosted Fields elements

Optional Fields:

Field Name	Description
env	The environment the Hosted Fields should work with. Default value is sec Possible values are: uat sec
styles	Subobject used to define styles to apply to the Hosted Fields elements
threeDsIFrame	Subobject used to define settings for the 3D Secure iframe

Field Name

Description

env

The environment the Hosted Fields should work with. Default value is sec

Possible values are:

styles

Subobject used to define styles to apply to the Hosted Fields elements

threeDsIFrame

Subobject used to define settings for the 3D Secure iframe

options.fields subobject

The subobject defines the configurations for the Hosted Fields elements. Available fields are:

Card Number
ExpirationDate
ExpirationMonth
ExpirationYear
CVV
CardholderName
BillingStreetAddress 1
BillingStreetAddress 2
BillingStreetAddress 3
BillingCity
BillingCountry
BillingPostalCode
ShippingStreetAddress 1
ShippingStreetAddress 2
ShippingStreetAddress 3
ShippingCity
ShippingCountry
ShippingPostalCode

Each field in the options.fields subobject is also a subobject carrying options for an individual field. Individual fields may have additional options on top of common fields.

options.fields.* subobject

Listed below are common fields available across all fields subobjects:

Field Name	Description
container	Holds an ID of the element container
placeholder	Defines the input placeholder when no entry was input into the field
disableAutoComplete	Specifies whether the field auto-completion should be disabled. If this option is omitted, the input element will be constructed with auto-completed on.
tabOrder	A numeric value that defines the order of the element in the Hosted Fields set.
validationHandlers	The subobject holding callbacks for field validation events. Available callbacks are: onValidationCleared - Triggered when the current validation state is cleared onValid - Triggered when the validation check is finished and indicated a valid input onInvalid - Triggered when the validation check is finished and indicates an invalid input. This callback gets an optional argument extraData which is an array of validation errors as string values. Current validation errors include: LuhnCheck - The input card number value does not pass the required Luhn check CardSupport - The input card type is not supported based on the Hosted Fields parameters ValidDateEntered - The input value is not a valid expiry date ValidCountryEntered - The selection is not a valid country patternMismatch
eventHandlers	The subobject holding callbacks for different non-validation events: onFocus - Triggered when the input value is focused onBlur - Triggered when the input element loses focus onEmptied - Triggered when the input is cleared onFilled - Triggered when the input is being populated
length	The object defined settings for the input related to the length of the input: minimumValidLength - A numeric value defining the minimal length for the input to be considered valid maximumValidLength - A numeric value defining the maximum length for the input to be considered valid minimumBeforeTrigger - A numeric value defining the minimal length for the input to start the validation jumpToPreviousField - A boolean value specifying whether the input should automatically jump to the previous element on pressing Backspace on an empty field jumpToNextField - A boolean value specifying whether the input should automatically jump to the next element on finishing the required input
styles	The subobject defining the styling parameters for the input. This overrides the global style if one was provided.

options.fields.CardNumber subobject

The CardNumber field allows for additional options as below:

Field Name	Description
cardSchemaImagePlacement	Defines the location for the card brand logo. When omitted or the value is an empty string, there will be no logo. Possible values are: left right
supportedCards	Defines the list of supported card brands. List needs to be populated or validation on the card will fail. If the integration should accept any card, input should be 'other'. Possible values are: visa masterCard amex jcb discover diners unionpay farmlands other

Field Name

Description

cardSchemaImagePlacement

Defines the location for the card brand logo. When omitted or the value is an empty string, there will be no logo. Possible values are:

left
right

supportedCards

Defines the list of supported card brands. List needs to be populated or validation on the card will fail. If the integration should accept any card, input should be 'other'.

Possible values are:

visa
masterCard
amex
jcb
discover
diners
unionpay
farmlands
other

The CardNumber allows for additional callback in the eventHandlers:

Field Name	Description
detectSchema	Triggered when the detected card brand has changed. This callback gets a single argument schemaName

options.fields.CVV subobject