Skip to main content

Getting Started

In the example below, we explain in detail how to tokenize card data using the Web SDK.

Hellgate® supports your payment experiences on the web with the headless Web SDK. The approach gives you the ultimate control over the user experience and visual design.

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

Step 1 - Create Session​

As a first step, it is required that you create a session for the tokenization. We offer a simple API for this:

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

This will return the session_id of the created session.

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

Step 2 - Use the SDK​

The second step is to send the session_id to your web application running in the customer's browser. The session_id is secret that you can safely share with the client.

danger

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 was handed over to the client, you can initialise the headless SDK.

Load the SDK​

The SDK is distributed via our CDN or from NPM.

npm install --save @starfish-codes/hellgate

Initialise the SDK​

With the session_id and the loaded SDK resources, you can now initialise a head-less client for your browser session.

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 head-less client keeps a secure connection to the Hellgate® backend and allows to communicate and to receive instructions if needed. In order to make use of the client, you need to connect it with the your application.

Step 3 - Tokenize Card Data​

📘 PCI/DSS

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.

In order to tokenize cardholder data, you need to use the CARD handler.

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

Based on the handler two types for forms can be rendered in your front-end.

One-Line Card Form​

This is a very compact way to request a customer to enter their card details. It technically consists of separated entry fields, but they are rendered as one unit into your web application. You can test the input:

The following is an example of how you can integrate such a simple card form into your web application.

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

// get the handler for card payments
const cardHandler = await client.use('CARD');

// create the one-line form
const cardForm = cardHandler.createForm({
  // customize styles
  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' },
    },
  },
});
// and mount it
cardForm.mount('#my-form-element');

// use an existing button to process the data
const submitButton = document.getElementById('my-submit-button');

submitButton.addEventListener('click', async () => {
  const result = await cardHandler.process();

  const resultElement = document.getElementById('result');
  const errorElement = document.getElementById('error');

  // handle the result
  if (result.status === 'success') {
    resultElement.textContent = 'Processing is successfully finished';
    errorElement.textContent = '';
  } else {
    resultElement.textContent = '';
    errorElement.textContent = result.data.reason;
  }
});

Separated Card-Data Fields​

In situation where you want to have more flexibility with respect to the design and the arrangement of the form fields required to accept card payments, you can also create individual elements and mount them accordingly. You can see a working example below.

The form with individual form fields requires slightly more boilerplate code.

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

// get the handler for card payments
const cardHandler = await client.use('CARD');

// create the form fields
const { cardNumber, expiryDate, securityCode } = cardHandler.createFormFields({
  // customize styles
  style: {
    base: {
      color: '#111',
      fontSize: '14px',
    },
  },
});
// and mount them
await Promise.all([
  cardNumber.mount('#my-card-number-element'),
  expiryDate.mount('#my-expiry-date-element'),
  securityCode.mount('#my-security-code-element'),
]);

// use an existing button to process the data
const submitButton = document.getElementById('my-submit-button');
const resultElement = document.getElementById('result');
const errorElement = document.getElementById('error');

submitButton.addEventListener('click', async () => {
  const result = await cardHandler.process();

  // handle the result
  if (result.status === 'success') {
    resultElement.textContent = 'Processing is successfully finished';
    errorElement.textContent = '';
  } else {
    resultElement.textContent = '';
    errorElement.textContent = result.data.reason;
  }
});