WebSDK 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`

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' });

Parameters

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

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();

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	The name of the cardHolder
email	String	Email address of the customer
billing_address.line1	String	The first line of the address
billing_address.line2	String	The second line of the address
billing_address.line3	String	The third line of the address
billing_address.postal_code	String	The postal code of the address
billing_address.city	String	The name of the city
billing_address.country	String	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

Create 3DS Handler

3D Secure Challenge works out of the box and usually doesn't require any extra code. In case the merchant supports 3DS Decoupled authentication, you can handle it via 3DS Handler

const threeDSHandler = await client.use('3DS');
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
});

Parameters

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

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

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 client 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`.

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.

WebSDK API

Create Client​

Options​

Create Card Handler​

Reset Card Handler​

Handling Cards​

Create Card Form​

Parameters​

Create Card Fields​

Parameters​

Create Text Field​

Parameters​

Process​

Parameters​

Additional Data​

Result​

Result data​

Create 3DS Handler​

Parameters​

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​

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

Process

Parameters

Additional Data

Result

Result data

Create 3DS Handler

Parameters

Mount Element

Parameters

Update Element

Parameters

Unmount Element

Element Values / States

Focus

Clear

Blur

Element Options

Element Styles

Card Handler Events

FormStateChange

Element Events

Change

Focus

Blur

Key Down