hosted-fields-sdk

Hosted fields sdk

Hosted fields SDK is a toolkit that allows you generate a form/set of fields. It is published as a node-module to the public npm registry.

[!CAUTION] Migration and Deprecation Notice: Starting from version 1.0.50, it is mandatory to use the 'https://card-fields.paymentiq.io/1.1.1/index.html' as hostedfieldsurl value for production environments. Please update your configurations accordingly to avoid potential disruptions.

The old hostedfieldsurl: 'https://hostedpages.paymentiq.io/1.0.51/index.html' and well as all versions previous to 1.0.50 are deprecated. Please note that using older versions and the old domain may expose your system to potential risks. Starting with version 1.1.1, hostedpages domain will not be used anymore.

This change is meant to enhance security and future compliance with the new requirements in the Payment Card Industry Data Security Standards. We advise all users to transition to the new domain as soon as possible to maintain compliance and benefit from improved security measures.

Obs. The new domain supports versions starting with 1.0.50 and above. Make sure your implementation is updated to at least this version to ensure compatibility.

Demo

[Live demo]

Setup

  npm i hosted-fields-sdk --save

  import { HostedFields, Field, FieldType } from 'hosted-fields-sdk'

The SDK will expose three functions

• HostedFields
• Field
• FieldTypes

Field & FieldTypes

You define what fields you wish to include in your form yourself. The SDK gives you a Field-constructor to help you with this. Simply pass in the following object to the Field-constructor and it will give you back a valid Field-item.

{
    id: id,
    name: name,
    type: type,
    label: label,
    error: errorKey,
    helpKey: helpKey,
    visible: visible,
    required: required,
    noAttributeValueFormatting: true, (not mandatory, defaults to false)
    autocomplete: autocomplete
}

noAttributeValueFormatting

In order to make input fields work with autofill for creditcard information, certain attributes are needed on the fields. Due to backwards compability, the flag noAttributeValueFormatting needs to be set to true.

This will set the id and name attributes to the actual value you pass in for each field. You can also set autocomplete to the desired value according to the autofill specs

https://developers.google.com/web/updates/2015/06/checkout-faster-with-autofill

Recommended values for autocomplete are:

Creditcard number: cc-number CVC: cc-csc Expiry: cc-exp

The type-property can be one of the following:

  TEXT: 'TEXT',
  NUMBER: 'NUMBER',
  CVV: 'CVV',
  CREDITCARD_NUMBER: 'CREDITCARD_NUMBER',
  EXPIRY_MM_YYYY: 'EXPIRY_MM_YYYY'

HostedFields

HostedFields in turn will expose these functions

• setup
• get
• reset
• setClickToPayTransactionAmount
• clickToPayCheckout

setup

Setup is the first function you will call. It takes a config-object as its only parameter:

{
    merchantId: 123456789,
    hostedfieldsurl: 'https://card-fields.paymentiq.io/1.1.1/index.html',
    fields: my_fields, //fields you've generated using the Field-constructor
    renderMode: 'single', // defaults to 'multiple', separate iframes per field
    service: 'payment_method_service', // service of the payment method. Not mandatory (AstropayCard requires this)
    styles: 'any custom styles you wish to include',
    callback: () => someFunction,
    autoFocusNext: true,
    onLoadCallback: () => someFunction,
    onCardBrandChangeCallback: ({ cardBrand: string }) => unknown,
    el: A domElement to render the hosted fields in,
    // Set the config from below if need to integrate ClickToPay
    // The full list of attributes can be seen here: https://srci-docs.prod.srci.cloud.netcetera.com/sdk-config-properties
    // You can override only these attributes in Hosted Fields. These are the default values:
    clickToPayAttributes: {
        locale: "en_US",
        sandbox: "true", // Make sure to set it "false" in production
    },
    // See the full config here: https://srci-docs.prod.srci.cloud.netcetera.com/sdk-config-guide#scheme-specific-configuration
    clickToPayConfig: "<ClickToPayConfig>", 
    onRequestIframeExpandCallback: (recommendedHeight: number) => unknown,  
    onCancelIframeExpandCallback: () => unkown, 
    // Response type here: https://srci-docs.prod.srci.cloud.netcetera.com/sdk-checkout-respons
    onClickToPayCheckoutSuccessCallback: (response) => uknown, 
    onClickToPayCheckoutErrorCallback: (error) => unkown, 
}

Setup will first set the base values. After that it will loop through the fields you've passed in and create an iframe for each one.

renderMode

Choose if all fields should be returned in a single iframe (single) or separate iframes (multiple). Defaults to multiple for backwards compability.

autoFocusNext

Hosted-fields can support to auto focus on the next field when a valid value has been entered. E.g when the user has entered their creditcard number, focus will automatically be put on expiry and then on to cvc.

Defaults to false.

callback Pass in a function that you want to be called when the values from the fields are fetched.

NOTE: Callback must be a function that returns a function. This allows you to run for example your own validation on the values before you pass in your callback that will handle your formData.

onLoadCallback Optionally, you can pass in a function that will be called when all the fields you have passed in have loaded, allowing you to display some kind of loader until this callback has been triggered.

onCardBrandChangeCallback Optionally, you can pass in a function that will be called when credit card number input has changed, and will return the detected cardBrand(e.g. visa, mastercard, etc.).

This is usually used for dynamic credit card flow handling based on the card brand(e.g. for ClickToPay).

clickToPayAattributes The attributes passed to the ClickToPay instance.

clickToPayConfig The config passed to the ClickToPay instance.

onRequestIframeExpandCallback This callback is triggered when the clickToPayCheckout call is performed to inform the integrator that the iframe height should be changed to the recommendedHeight and hide all the other visible UI elements to make room for the ClickToPay iframe to expand.

onCancelIframeExpandCallback This callback is triggered when the ClickToPay checkout has finised to inform the integrator that the iframe height should be restored and show all the other previously hidden UI elements.

onClickToPayCheckoutSuccessCallback The callback triggered when receive a success response after a ClickToPay checkout.

onClickToPayCheckoutErrorCallback The callback triggered when receive an error after a ClickToPay cehckout.

Possible values for hostedfieldsurl:

For test environments use: 'https://test-hostedpages.paymentiq.io/1.1.1/index.html'.

For production environments use 'https://card-fields.paymentiq.io/1.1.1/index.html'.

Available versions for 'https://card-fields.paymentiq.io/1.1.1/index.html'(where the part 1.1.1 represents the version number):

• 1.1.1
• 1.0.61
• 1.0.60
• 1.0.58
• 1.0.57
• 1.0.56
• 1.0.55
• 1.0.54
• 1.0.53
• 1.0.52
• 1.0.51
• 1.0.50

[!NOTE]
Versions older than 1.0.50 are no longer supported.

get

If you want to get the encrypted values from the fields you can call

HostedFields.get()

This will trigger the supplied callback-function registered in HostedFields.setup() to be called with the values for each field. Note that the callback function will also be called if the user presses enter in any of the fields.

{
   cardHolder: 'Admiral Ackbar',
   encCreditcardNumber: 'ENCRYPTED_STRING',
   encCvv: 'ENCRYPTED_STRING',
   expiryMonth: '05',
   expiryYear: '2025'
}

reset

If you wish to reset the currently rendered iframes (fields) you can call HostedFields.reset() before running a new setup(). This can be required if your page that contains the fields gets re-rendered. In that case you will have registered duplicates of the fields. So it's a good idea to call HostedFields.reset() on a beforeDestroy-hook if you are using Vue or React.

//Each iframe will get an id 'hosted-field-' + the id of the field
iframe.id = 'hosted-field-' + field.id;

//hostedfieldsurl passed in config to setup
iframe.src = hostedfieldsurl + '?mid=' + merchantId;

//domEl the iframe should be appended to, also from config
var container = document.querySelector(el);

Lastly eventListener are registered to the iframe so that it picks up postMessage events.

setClickToPayTransactionAmount (used for ClickToPay integration)

It's used when the transaction amount should be dynamically changed.

Set ClickToPay transaction amount according to:
https://srci-docs.prod.srci.cloud.netcetera.com/sdk-config-guide

clickToPayCheckout (used for ClickToPay integration)

Perform ClickToPay checkout according to:
https://srci-docs.prod.srci.cloud.netcetera.com/sdk-checkout-api

Styling

Styling will mainly be handled buy the application using the hosted-fields. Each field will have some basic styling but the layout will have to be supplied.

Each field can have an appended string of css. This will be added to each field's iframe head as a style-tag.

Basic Example

Two simple text fields for first & last name

import { FieldTypes } from 'hosted-fields-sdk'

let fieldConfig = [
   {
       type: FieldTypes.TEXT,
       id: 'first-name',
       name: 'first-name',
       label: 'First name',
       error: 'First name is not valid',
       helpKey: 'First name',
       visible: true,
       required: true,
       noAttributeValueFormatting: true,
       autocomplete: 'firstname'
   },
   {
       type: FieldTypes.TEXT,
       id: 'lastname',
       name: 'lastname',
       label: 'Last name',
       error: 'Last name is not invalid',
       helpKey: 'Last name',
       visible: true,
       required: true,
       noAttributeValueFormatting: true,
       autocomplete: 'lastname'
   }
]

Generate Field-objects using the Field-constructor for each one

import { Field } from 'hosted-fields-sdk'

let fields = fieldConfig.map(conf => {
  return new Field(
      conf.type,
      conf.id,
      conf.name,
      conf.label,
      conf.error,
      conf.helpKey,
      conf.visible,
      conf.required,
      conf.noAttributeValueFormatting,
      conf.autocomplete
  )
})

Call the setup function

HostedFields.setup({
  merchantId: 123456789,
  hostedfieldsurl: 'https://card-fields.paymentiq.io/1.1.1/index.html',
  fields: fields,
  service: 'some service',
  styles: '* .hosted-input-container .input-container input { color: green; }',
  callback: () => formCallbackHandler,
  onLoadCallback: () => formHasLoadedCallbackHandler,
  el: '#hosted-fields-wrapper'
})

Adding the callback handler and including the domElement stated as 'el'

<!--index.html--->
<html>
    <head></head>
    <body onload=setupHostedFields()>
        <button onClick=fetchFormData()>Get form data</button>
	<div id="hosted-fields-wrapper"></div>
    </body>
</html>

// scripts.js
import { HostedFields, Field, FieldTypes } from 'hosted-fields-sdk'

const setupHostedFields = () => {
    HostedFields.setup(...the setup config)
}

const formCallbackHandler = (formData) => {
    // do stuff
}

const formHasLoadedCallbackHandler = () => {
    // all hosted fields has loaded
}

const fetchFormData = () => {
    HostedFields.get() //will trigger formCallbackHandler
}

Styling rules You can set comments in your custom css style file to render the input in a certain way.

Available rules / comments: (Copy/paste the comment in it's exact form, one extra whitespace won't make it work.)

/* RenderAsFloatingLabel */

The RenderAsFloatingLabel rule will render the input placeholder as a floating label instead of a fixed one.

Basic styling Each field will get wrapped by a div with the class .hosted-field-container and an id suffixed with the stated id for that field.

By adding the following styles a basic layout will be created:

//style.css

#hosted-fields-wrapper {
   width: 600px;
}

#hosted-fields-wrapper .hosted-field-container {
   height: 65px;
}

#hosted-fields-wrapper .hosted-field-container iframe {
   width: 100%;
   border: 0px;
}

Full checkout form

import { HostedFields, Field, FieldTypes } from 'hosted-fields-sdk'

// Configure your fields
let fieldConfig = [
  {
      type: FieldTypes.TEXT,
      id: 'cardholder-name',
      name: 'cardholder-name',
      label: 'Cardholder name',
      error: 'Cardholder not valid',
      helpKey: 'Cardholder name',
      visible: true,
      required: true
  },
  {
      type: FieldTypes.CREDITCARD_NUMBER,
      id: 'creditcard',
      name: 'creditcard',
      label: 'Credit card',
      error: 'Credit card number is invalid',
      helpKey: 'Credit card',
      visible: true,
      required: true,
      noAttributeValueFormatting: true,
      autocomplete: 'cc-number'
  },
  {
      type: FieldTypes.EXPIRY_MM_YYYY,
      id: 'date-expire',
      name: 'date-expire',
      label: 'Expiry date',
      error: 'Expire date not valid',
      helpKey: 'Expire date',
      visible: true,
      required: true
      noAttributeValueFormatting: true,
      autocomplete: 'cc-exp'
  },
  {
      type: FieldTypes.CVV,
      id: 'cvv',
      name: 'cvv',
      label: 'CVV',
      error: 'CVV not valid',
      helpKey: 'CVV',
      visible: true,
      required: true,
      noAttributeValueFormatting: true,
      autocomplete: 'cc-csc'
  }
]

// Construct your fields
let fields = fieldConfig.map(conf => {
  return new Field(
      conf.type,
      conf.id,
      conf.name,
      conf.label,
      conf.error,
      conf.helpKey,
      conf.visible,
      conf.required,
      conf.noAttributeValueFormatting,
      conf.autocomplete
    )
})

// And finally the setup

HostedFields.setup({
  merchantId: 123456789,
  hostedfieldsurl: 'https://card-fields.paymentiq.io/1.1.1/index.html',
  fields: fields,
  service: 'some service',
  styles: '.hosted-input-container .input-container input { color: red; }',
  callback: () => formCallbackHandler,
  onLoadCallback: () => formHasLoadedCallbackhandler,
  el: '#hosted-fields-wrapper'
})

// When you want to fetch the form information:
HostedFields.get()

Returns an object of key-values for your fields.
Fields that are to be encrypted (Card number + CVV) will return the encrypted value.
If any errors are detected, an error message will be returned as the value of that field, prefixed with ERROR

Notes

Minimum Supported Version

Version 1.0.50 or later is required. Older versions are no longer supported.

New Domain:

Domain: card-fields.paymentiq.io/1.1.1/

Compatibility Note:

Supported Versions: This domain supports versions starting with 1.0.50 and above. Make sure your implementation is updated to at least this version to ensure compatibility.

Why Change?

• Security and Compliance: The new domain aligns with the latest PCI DSS requirements and offers enhanced security features.
• Future-proofing: By migrating to the new domain, users avoid potential disruptions caused by the deprecation of the old domain.

Action Required:

Upgrade Your Version: Ensure your integration uses version 1.0.50 or later. Migrate to the New Domain: Begin using the new domain by updating your configurations accordingly.

Deprecation Timeline:

Old Domain: The old domain is deprecated and no longer supported.

Additional Notes:

Reach out to our support team if you encounter any issues during the transition or require further assistance.