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.0.51/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 will be deprecated starting 15 March 2025. Please note that using older versions and the old domain may expose your system to potential risks.
>
> This change is meant to enhance security and future compliance with the new requirements in the Payment Card Industry Data Security Standards. The old domain is scheduled for deprecation. 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 three functions
* setup
* get
* reset

setup

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

``js
{
merchantId: 123456789,
hostedfieldsurl: 'https://card-fields.paymentiq.io/1.0.51/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
}
``

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).

Possible values for hostedfieldsurl:

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

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

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

> [!WARNING]
> Please note that previous versions(older than 1.0.50), as well as old domain name hostedpages will be deprecated and must be updated by 15 March 2025.


get

If you want to get the encrypted values from the fields you can call
`js
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.

`js
{
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.

``js
//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.

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
``js
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
``js
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
``js
HostedFields.setup({
merchantId: 123456789,
hostedfieldsurl: 'https://card-fields.paymentiq.io/1.0.51/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'
``html




Get form data





``

``js
// 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:
``css
//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


``js
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.0.51/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

``

$3

#### Domain Change Explanation and Disclaimer

Overview of Change:
We have recently updated the domain used for our card fields to enhance security and compliance with current standards. The old domain, while PCI DSS compliant, is scheduled for deprecation. We advise all users to transition to the new domain as soon as possible to maintain compliance and benefit from improved security measures.

#### New Domain:
Domain: card-fields.paymentiq.io/1.0.51/`

#### 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 will be deprecated on 15 March, after which it will no longer be supported.

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