Skip to main content

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',
});
ParameterTypeRequired?Description
sessionIDStringYesThe session id that was handed over to the integrator as part of an action requirement.
optionsObjectNoOptions to customise the form to specific requirements

Options

AttributeTypeDescription
base_urlStringSet custom Hellgate® backend. Default -https://api.hellgate.io
challenge_3ds_containerHTMLElementCustom DOM container for rendering 3D Secure Challenge iframe. Default - undefined
challenge_3ds_label_textStringDisplay 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

ParameterTypeRequired?Description
optionsObjectNoOptions 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

ParameterTypeRequired?Description
optionsObjectNoOptions 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

ParameterTypeRequired?Description
optionsObjectNoOptions 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();

Parameters

ParameterTypeRequired?Description
additionalDataObjectNoFurther information that needs to be passed into the processing.

Additional Data

AttributeTypeDescription
cardholder_nameStringThe name of the cardHolder
emailStringEmail address of the customer
billing_address.line1StringThe first line of the address
billing_address.line2StringThe second line of the address
billing_address.line3StringThe third line of the address
billing_address.postal_codeStringThe postal code of the address
billing_address.cityStringThe name of the city
billing_address.countryStringThe three letter country code following ISO3166-Alpha3

Result

AttributeTypeDescription
status"success" | "failure" | "pending"Status of the current processing
dataObjectResult data

Result data

AttributeTypeRequired?Description
transaction_idStringNoID of a 3DS transaction in Hellgate® being created as result of the processing
token_idStringNoID of a Hellgate® Token being created as result of the processing
reasonStringNoWill hold a human readable reason why the processing failed
reason_codeStringNoWill 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

ParameterTypeRequired?Description
selectorStringYesA 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

ParameterTypeRequired?Description
optionsObjectNoThe 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

AttributeElementTypeDescription
styleAllObjectData that defines the styling of the element.
heightAllStringCSS property to customise the height of the element
disabledAllBooleanSet the disabled state of the form field(s).
autocompleteAllStringString used to set the autocomplete attribute of the input(s). Expected values are: off (default), or on.
placeholdertext, cardNumber, cardExpirationDate, cardVerificationCodeStringString to customise the placeholder attribute of the form field.
ariaLabeltext, cardNumber, cardExpirationDate, cardVerificationCodeStringString to customise the aria-label attribute of the form field.
iconcard, cardNumberStringString 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.
schemescard, cardNumberString[]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',
},
},
});
AttributeRequired?Description
fontsNoList of URLs to fonts on the Google API.
baseNoBasic styling of the element. The other variants will use it as baseline.
completeNoVariant of the baseline for an element with completed input.
emptyNoVariant of the baseline for an element with empty input.
invalidNoVariant 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": []
}
AttributeTypeDescription
validBooleanIndicates that all fields content successfully passed validation.
completeBooleanIndicates that all fields are valid and maskSatisfied properties are true
emptyBooleanForm will be empty only if all inputs are
errorsListA 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
});
ParameterTypeDescription
cardholderInfoStringInstructions 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"
}
AttributeElementTypeDescription
validAllBooleanIndicates that the content successfully passed validation.
emptyAllBooleanIndicates that the element is empty.
errorsAllListA 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.
cardBrandCardNumberStringValues 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
}
AttributeTypeDescription
keyStringIndicator of the key that was pressed. Can be Enter or Escape.
ctrlKeyBooleanIndicates if the control key was pressed when the event occurred.
altKeyBooleanIndicates if the alt / option key was pressed when the event occurred.
shiftKeyBooleanIndicates if the shift key was pressed when the event occurred.
metaKeyBooleanIndicates if the meta (e.g. command on a Mac) key was pressed when the event occurred.