Overview

In order to make use of the Web SDK you need to create a client-sharable, short-lived secret. This secret is called a session as it represents a session between your web application and the Hellgate®.

Create Session

Create a session for tokenization using the session API.

Example: Create session

curl --request POST \
  --url https://api.hellgate.io/tokens/session \
  --header 'content-type: application/json'

The response includes the session_id of the created session.

Example: Session response

{
  "session_id": "7f2c9460-7e2e-403f-a08a-bc58cdcaea83"
}

Want to confirm the session works before writing any browser code? Paste the session_id into the WebSDK testing page to run the full card flow against it.

Use the SDK

Send the session_id to your web application in the customer’s browser. The session_id is safe to share with the client.

You must not distribute your server-side API keys to the clients. Use the provided session_id, which is short-lived (with a default of 15 minutes) and has a very limited scope. This protects you from malicious acts.

After the session_id is handed over to the client, initialise the headless SDK.

Load the SDK

The SDK is distributed via our CDN or from NPM.

Example: Install via NPM

npm install --save @starfish-codes/hellgate

Example: Load via CDN

<script src="https://sdk.hellgate.io/web/v3.10.0/hellgate-sdk.min.js"></script>

Initialise the SDK

With the session_id and the loaded SDK, initialise a headless client for your browser session.

Example: Initialise client

import { Hellgate } from '@starfish-codes/hellgate';

// Create the Hellgate client. Make sure you await the result of the
// asynchronous initialisation, as subsequent actions will rely on it.
const client = await Hellgate.init('7f2c9460-7e2e-403f-a08a-bc58cdcaea83', {
  base_url: 'https://sandbox.hellgate.io',
});

The headless client keeps a secure connection to the Hellgate® backend. Connect it with your application to proceed.

Tokenize Card Data

Hellgate’s Headless SDK enables secure card payment data entry, yet is fully embedded in your web application. The secure communication channel between the SDK and the Hellgate® allows the sensitive card data to be exchanged for so-called tokens. These are made available to you as a payment method.

Use the CARD handler to tokenize cardholder data.

Example: Get card handler

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

Based on the handler, two form types can be rendered in your front-end.

One-Line Card Form

A compact way to collect card details: separate entry fields rendered as one unit.

Example: One-line card form integration

const { Hellgate } = window;
const client = await Hellgate.init('d5529f03-e84a-4a43-867c-b3412a097e63', {
  base_url: 'https://sandbox.hellgate.io',
});

const cardHandler = await client.use('CARD');
const cardForm = cardHandler.createForm({
  style: {
    fonts: ['https://fonts.googleapis.com/css2?family=Nunito:wght@300;400;500;600;700;800&display=swap'],
    base: {
      fontFamily: 'Nunito, sans-serif',
      color: '#111',
      fontSize: '16px',
      '::placeholder': { color: '#6b7280' },
    },
  },
});
const cardholderField = cardHandler.createTextField();

cardForm.mount('#my-form-element');
cardholderField.mount('#cardholder-element');

const submitButton = document.getElementById('my-submit-button');
submitButton.addEventListener('click', async () => {
  try {
    const result = await cardHandler.process({
      cardholder_name: cardholderField,
    });
    const resultElement = document.getElementById('result');
    const errorElement = document.getElementById('error');
    if (result.status === 'success' || result.status === 'pending') {
      resultElement.textContent = 'Processing has been successfully completed';
      errorElement.textContent = '';
    } else {
      resultElement.textContent = '';
      errorElement.textContent = result.data.reason;
    }
  } catch (err) {
    // handle error (e.g. network issue or backend error)
  }
});

Separated Card-Data Fields

For more flexibility in layout, create individual elements and mount them separately.

Example: Separated card fields

const { Hellgate } = window;
const client = await Hellgate.init('d5529f03-e84a-4a43-867c-b3412a097e63', {
  base_url: 'https://sandbox.hellgate.io',
});

const cardHandler = await client.use('CARD');
const { cardNumber, expiryDate, securityCode } = cardHandler.createFormFields({
  style: {
    base: {
      color: '#111',
      fontSize: '14px',
    },
  },
});

await Promise.all([
  cardNumber.mount('#my-card-number-element'),
  expiryDate.mount('#my-expiry-date-element'),
  securityCode.mount('#my-security-code-element'),
]);

const submitButton = document.getElementById('my-submit-button');
submitButton.addEventListener('click', async () => {
  try {
    const result = await cardHandler.process({
      cardholder_name: 'Cardholder Name',
    });
    const resultElement = document.getElementById('result');
    const errorElement = document.getElementById('error');
    if (result.status === 'success' || result.status === 'pending') {
      resultElement.textContent = 'Processing has been successfully completed';
      errorElement.textContent = '';
    } else {
      resultElement.textContent = '';
      errorElement.textContent = result.data.reason;
    }
  } catch (err) {
    // handle error
  }
});

Separated expiration month and year

Use expiryDateElement: 'separate' to get distinct month and year fields.

Example: Separate month and year fields

const { cardNumber, expiryMonth, expiryYear, securityCode } = cardHandler.createFormFields({
  style: {
    base: {
      color: '#111',
      fontSize: '14px',
    },
  },
  expiryDateElement: 'separate',
});

await Promise.all([
  cardNumber.mount('#my-card-number-element'),
  expiryMonth.mount('#my-expiry-month-element'),
  expiryYear.mount('#my-expiry-year-element'),
  securityCode.mount('#my-security-code-element'),
]);

SDKs

Testing

Load the SDK

Initialise the SDK

One-Line Card Form

Separated Card-Data Fields

Separated expiration month and year

​Load the SDK

​Initialise the SDK

​One-Line Card Form

​Separated Card-Data Fields

​Separated expiration month and year

Load the SDK

Initialise the SDK

One-Line Card Form

Separated Card-Data Fields

Separated expiration month and year