Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developer.hellgate.io/llms.txt

Use this file to discover all available pages before exploring further.

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

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

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

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

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'),
]);