Web SDK API

The WebSDK API allows integrators to start a secure client session and to process payment method data in the browser. When Hellgate®'s SDK is loaded a global object Hellgate is available.

Create Client

This method will create and initialise the Hellgate® client using an existing session_id.

const { Hellgate } = window;

const client = await Hellgate.init('7f2c9460-7e2e-403f-a08a-bc58cdcaea83', {
  base_url: 'https://sandbox.hellgate.io',
});

Parameter	Type	Required?	Description
sessionID	String	Yes	The session id that was handed over to the integrator as part of an action requirement.
options	Object	No	Options to customise the form to specific requirements

Options

Attribute	Type	Description
base_url	String	Set custom Hellgate® backend. Default -`https://api.hellgate.io`
challenge_3ds_container	HTMLElement	Custom DOM container for rendering 3D Secure Challenge iframe. Default - `undefined`
challenge_3ds_label_text	String	Display custom label text for 3D Secure Challenge iframe

Create Card Handler

In order to process card payments (and later other payment methods as well), a handler has to be obtained from the client.

const cardHandler = await client.use('CARD');

Reset Card Handler

This method will remove the card form or card fields from the client, disconnect handlers and unmount the fields from the DOM.

cardHandler.reset();

Handling Cards

Create Card Form

This method will create a new one-line card form as shown below in the demo.

const cardForm = cardHandler.createForm(options);

Parameters

Parameter	Type	Required?	Description
options	Object	No	Options to customise the form to specific requirements.

Create Card Fields

This method will create the full set of card fields as shown below in the demo.

const { cardNumber, expiryDate, securityCode } = cardHandler.createFormFields(options);

Parameters

Parameter	Type	Required?	Description
options	Object	No	Options to customise the form fields to specific requirements. The options can be prefixed with `cardNumber: {}`, `expiryDate: {}`, and `securityCode: {}` to apply them specifically (e.g. `cardNumber: {placeholder: 'Custom Placeholder'}`).

Create Text Field

The "text" element type is a secure replacement for the <input> tag and enables collecting user string data like Cardholder Name as demonstrated.

cardHandler.createTextField({ placeholder: 'Cardholder Name' });

The created TextField can be directly passed as a property for additionalData and the value does not need to be extracted.

Parameters

Parameter	Type	Required?	Description
options	Object	No	Options to customise the form fields to specific requirements.

3D-Secure

3D Secure handling works out of the box with the SDK and usually doesn't require any extra code.

Process

This method will read the data from the card form or the card fields and send them to processing. Prerequisite is that card fields or a card form was created before. A loading indicator can be shown until the promise is resolved.

const result = await cardHandler.process({
  // cardholderTextField can be created by cardHandler.createTextField()
  // the value from the text field will be extracted automatically during processing
  cardholder_name: cardholderTextField,
});

Parameters

Parameter	Type	Required?	Description
additionalData	Object	No	Further information that needs to be passed into the processing.

Additional Data

Attribute	Type	Description
cardholder_name	String \| TextField	The name of the cardHolder
email	String \| TextField	Email address of the customer
billing_address.line1	String \| TextField	The first line of the address
billing_address.line2	String \| TextField	The second line of the address
billing_address.line3	String \| TextField	The third line of the address
billing_address.postal_code	String \| TextField	The postal code of the address
billing_address.city	String \| TextField	The name of the city
billing_address.country	String \| TextField	The three letter country code following ISO3166-Alpha3

Result

Attribute	Type	Description
status	"success" \| "failure" \| "pending"	Status of the current processing
data	Object	Result data

Result data

Attribute	Type	Required?	Description
transaction_id	String	No	ID of a 3DS transaction in Hellgate® being created as result of the processing
token_id	String	No	ID of a Hellgate® Token being created as result of the processing
reason	String	No	Will hold a human readable reason why the processing failed
reason_code	String	No	Will hold a technical code classifying the failure reason

Elements API

The Elements API allows to interact with the created card form or the card fields.

Mount Element

This operation mounts an element to the DOM at the specified element.

await cardForm.mount('#my-card-form-id');

Parameters

Parameter	Type	Required?	Description
selector	String	Yes	A CSS-selector that identifies the container in the DOM to where the element will be mounted

Update Element

This operations allows to change the options on an element. Please note that not all options can be changed.

cardNumberField.update({ icon: 'none' });

Parameters

Parameter	Type	Required?	Description
options	Object	No	The options to customise the element.

Unmount Element

This operation removes an element from the DOM.

cardNumberField.unmount();

Element Values / States

Focus

Set the focus on an element's input.

cardNumberField.focus();

Clear

Clear the value of an element.

cardNumberField.clear();

Blur

Blur an element's input.

cardNumberField.blur();

Element Options

Attribute	Element	Type	Description
style	All	Object	Data that defines the styling of the element.
height	All	String	CSS property to customise the height of the element
disabled	All	Boolean	Set the disabled state of the form field(s).
autocomplete	All	String	String used to set the autocomplete attribute of the input(s). Expected values are: off (default), or on.
placeholder	text, cardNumber, cardExpirationDate, cardVerificationCode	String	String to customise the placeholder attribute of the form field.
ariaLabel	text, cardNumber, cardExpirationDate, cardVerificationCode	String	String to customise the aria-label attribute of the form field.
icon	card, cardNumber	String	String to determine the position of the icon in the cardNumber field. `left` is the default value. It can be overwritten to `right` and to `none` in order to hide the icon entirely.
schemes	card, cardNumber	String[]	Whitelist of card schemes which are supported by the merchant. Available schemes: `visa`, `mastercard`, `american-express`, `discover`, `diners-club`, `jcb` `unionpay`. The input of a restricted scheme will lead to a validation error in the form. All schemes are supported by default.

Element Styles

The form fields are encapsulated into iframes to allow for maximum protection of sensitive data. This means that CSS from the embedding page cannot be propagated directly into the form or the fields.

cardNumberField.update({
  style: {
    fonts: ['https://fonts.googleapis.com/css2?family=Playfair:wght@300&display=swap'],
    base: {
      color: '#fff',
      fontWeight: 500,
      fontFamily: '"Playfair"',
      fontSize: '16px',
      '::placeholder': {
        color: '#6b7294',
      },
      ':disabled': {
        backgroundColor: '#ffff3b',
      },
    },
    invalid: {
      color: '#ffa474',
    },
  },
});

Attribute	Required?	Description
fonts	No	List of URLs to fonts on the Google API.
base	No	Basic styling of the element. The other variants will use it as baseline.
complete	No	Variant of the baseline for an element with completed input.
empty	No	Variant of the baseline for an element with empty input.
invalid	No	Variant of the baseline for an element with invalid input.

You can customise the elements using these pseudo-classes and pseudo-elements inside each variant using a nested object:

:hover
:focus
:disabled
::placeholder
::selection

These CSS properties are supported in terms of styling:

backgroundColor
color
fontFamily
fontSize
fontSmooth (will be mapped to user-agent naming automatically)
fontStyle
fontVariant
fontWeight
lineHeight
letterSpacing
textAlign
padding
textDecoration
textShadow
textTransform

Events

Both the clients and the elements send out events so that solutions can actively react to changes in state.

Card Handler Events

FormStateChange

This event notifies every time the card form fields state changes.

cardHandler.onStateChange((state) => {
  // handling logic
});

The handler receives an aggregated stateobject that is derived from all card fields states.

{
  "valid": false,
  "complete": false,
  "empty": true,
  "errors": []
}

Attribute	Type	Description
valid	Boolean	Indicates that all fields content successfully passed validation.
complete	Boolean	Indicates that all fields are valid and maskSatisfied properties are true
empty	Boolean	Form will be empty only if all inputs are
errors	List	A list of ElementErrors, which consist of source ID of the field causing the error and a classification if the input is either `invalid` or `incomplete`.

3D-Secure Events

In standard cases 3D Secure handling works out of the box with the SDK and usually doesn't require any extra code. However, there are some events that can be used to handle the 3DS Challenge experience in the UI.

In order to use the 3DS Handler, it has to be obtained from the client:

const threeDSHandler = await client.use('3DS');

Decoupled Authentication

Decoupled authentication can be supported by the SDK with a specific event.

threeDSHandler.onDecoupledAuth((cardholderInfo) => {
  // handle decoupled flow here and display `cardholderInfo` on the UI to inform the customer
  // how they should complete 3DS authentication outside of the merchant's side
});

Parameter	Type	Description
cardholderInfo	String	Instructions from the card issuer what method the customer should use to complete 3DS authentication. For example, mobile banking app

Start Challenge

This event is called once the 3DS Challenge is started. It can be used to show a loading indicator or to inform the customer about the ongoing process.

threeDSHandler.onStartChallenge(() => {
  // called once 3DS Challenge is started
});

Challenge Finished

This event is called once the 3DS Challenge is finished. It can be used to hide the loading indicator or to inform the customer about the result.

threeDSHandler.onChallengeFinished(() => {
  // called when 3DS Handler finishes the task
});

Element Events

Change

This event notifies that the value of an element has changed. By default this event is emitted onBlur which can be overwritten with the element options.

cardNumberField.on('change', (changeEvent) => {
  // handling logic
});

The handler receives a ChangeEvent with information about the state of the element.

{
  "complete": true,
  "valid": true,
  "empty": false,
  "errors": [],
  "cardBrand": "amex"
}

Attribute	Element	Type	Description
valid	All	Boolean	Indicates that the content successfully passed validation.
empty	All	Boolean	Indicates that the element is empty.
errors	All	List	A list of ElementErrors, which consist of source ID of the field causing the error and a classification if the input is either `invalid` or `incomplete`.
cardBrand	CardNumber	String	Values are `amex`, `visa`, `mastercard`, `diners`, `jcb`, and `unionpay`.

Focus

This event indicates that an element is focussed.

cardNumberField.on('focus', () => {
  // handling logic
});

Blur

This event indicates that an element lost focussed.

cardNumberField.on('blur' () => {
  // handling logic
})

Key Down

This event indicates that a key was pressed on the element.

cardNumberField.on('keydown', (keyDownEvent) => {
  // handling logic
});

The handler receives a KeyDownEvent with information about the state of the element.

{
  "key": "enter",
  "ctrlKey": false,
  "altKey": false,
  "shiftKey": false,
  "metaKey": false
}

Attribute	Type	Description
key	String	Indicator of the key that was pressed. Can be `Enter` or `Escape`.
ctrlKey	Boolean	Indicates if the control key was pressed when the event occurred.
altKey	Boolean	Indicates if the alt / option key was pressed when the event occurred.
shiftKey	Boolean	Indicates if the shift key was pressed when the event occurred.
metaKey	Boolean	Indicates if the meta (e.g. command on a Mac) key was pressed when the event occurred.

Create Client​

Options​

Create Card Handler​

Reset Card Handler​

Handling Cards​

Create Card Form​

Parameters​

Create Card Fields​

Parameters​

Create Text Field​

Parameters​

3D-Secure​

Process​

Parameters​

Additional Data​

Result​

Result data​

Elements API

Mount Element​

Parameters​

Update Element​

Parameters​

Unmount Element​

Element Values / States​

Focus​

Clear​

Blur​

Element Options​

Element Styles​

Events

Card Handler Events​

FormStateChange​

3D-Secure Events​

Decoupled Authentication​

Start Challenge​

Challenge Finished​

Element Events​

Change​

Focus​

Blur​

Key Down​

Create Client

Options

Create Card Handler

Reset Card Handler

Handling Cards

Create Card Form

Parameters

Create Card Fields

Parameters

Create Text Field

Parameters

3D-Secure

Process

Parameters

Additional Data

Result

Result data

Mount Element

Parameters

Update Element

Parameters

Unmount Element

Element Values / States

Focus

Clear

Blur

Element Options

Element Styles

Card Handler Events

FormStateChange

3D-Secure Events

Decoupled Authentication

Start Challenge

Challenge Finished

Element Events

Change

Focus

Blur

Key Down