Home / Clientside & SDKs

Secure Inputs SDK

Secure Data Input

The Highnote Secure Inputs SDK allows your customers to securely input their sensitive data in your UI seamlessly using input fields inside iframes. This allows you to avoid PCI-scoped data flowing through your servers or being accessible to scripts running on your page.

Note: Secure Inputs uses client tokens to make requests to the Highnote GraphQL API on your behalf. Learn how to generate client tokens using the generatePaymentCardClientToken mutation (docs).

Requirements

  1. A Highnote Account
  2. A server-side integration using an API Key
  3. Payment Card ID

Installation

The Secure Inputs SDK follows semver and can be installed from npm or a cdn.

via NPM

You can install the Secure Inputs SDK with the following

With npm: npm i @highnoteplatform/secure-inputs

With yarn: yarn add @highnoteplatform/secure-inputs

With pnpm: pnpm add @highnoteplatform/secure-inputs

Note: This package ships with TypeScript definitions installed.

via CDN

You can install the Secure Inputs SDK for use on your page directly from a CDN such as JSDelivr. This is helpful when exploring the SDK or for use in tools such as CodeSandbox.

It is recommended you select a specific version of the library to use. You can replace @latest with your chosen version (for example, @1.0.0).

Usage

To render Secure Inputs in your UI, you will need to set up elements to hold each field. You can then initialize the JavaScript library to populate those elements with input fields via iframes.

Fetch a Client Token

First, you will need to obtain a client token from your server using the generatePaymentCardClientToken mutation (docs). When generating the client token, you will need to provide the Payment Card ID of the card you will render.

The resulting token can be safely provided to your client and passed to the Highnote JavaScript SDK. It is only valid for 10 minutes but can be used multiple times within that period. Once the token has expired, you will need to generate a new one if you wish to re-render the payment card details.

Prepare Your HTML

You will need to provide the Secure Inputs with the elements you want to render iframes for. The following fields are supported for secure inputs:

  • PIN
Prepare HTML for PIN entry
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Edit Payment Card PIN</title>
  </head>
  <body>
    <p>Enter a new PIN for your Payment Card</p>
    <div id="pin">
      <!-- An iframe will be injected here -->
    </div>
  </body>
</html>

Initialize Secure Inputs

The library will inject an iframe into each of these elements to render secure inputs. You can style the input field inside of each iframe by passing any combination of allowed styles.

You can initialize the Secure Inputs by calling renderFields. This will return a Promise that, will contain a reference to the secureInputs instance (useful for lifecycle management and interactions such as field submission)

Initialize Secure Inputs
import { renderFields } from "@highnoteplatform/secure-inputs";

const secureInputs = await renderFields({
  // Specify the individual fields to render data into
  elements: {
    pin: {
      clientToken: "client token from server",
      // This is the same paymentCardId used to generate the token
      paymentCardId: "PAYMENT_CARD_ID",
      selector: "#pin",
    },
  },

  onSuccess: (element) => {
    // Inform the user on success
  },

  onError: (error) => {
    // Handle errors
  },
});

Error Handling

You can pass an onError handler to the renderFields call. This callback will be invoked whenever an error is raised from the integration.

Secure Inputs will not render error messages or update the UI inside of iframes when errors are encountered. It is up to you to introspect and handle errors accordingly.

Error Types

ErrorDescription
InvalidCredentialErrorOccurs when the provided Client Token is invalid or expired. The payload will contain the requestId which can be used for support and debugging.
SecureInputsRequestErrorRepresents errors encountered when communicating with the Highnote GraphQL API, such as an incorrect Payment Card ID. The payload will contain the requestId which can be used for support and debugging.
SecureInputsFieldsInputErrorRaised when an invalid configuration is provided at runtime.
SecureInputsErrorA generic catchall error.

Examples

Render Fields
import { 
  renderFields,
  type SecureInputsError
} from "@highnoteplatform/secure-inputs";

const handleError = (
  error: SecureInputsError
) => {
  switch (error.name) {
    case "InvalidCredentialError":
      // Handle invalid/expired credential
      // Unmount fields, fetch new client token, re-initialize
      console.error(error.context.requestId); // "some-request-id"
      break;

    case "SecureInputsRequestError":
      // Handle invalid payment card IDs
      console.error(error.context.requestId); // some-request-id
      break;

    case "SecureInputsFieldInputError":
      // Handle user input errors such as invalid pin
      console.error(error.message); // "Invalid Payment Card ID"
      break;

    default:
      console.error(error);
  }
};


const { unmount } = await renderFields({
  // ...
  onError: handleError,
  // ...
});

Styling Options

PropertyExamplesDocs
color#55f5a3, rgba(85,245,163,1), #springgreenMDN Docs
cursorpointer, noneMDN Docs
fontFamilysans-serif, serif, monospace System fonts onlyMDN Docs
fontSize12px, 1em, 1.1remMDN Docs
fontWeightbold, normalMDN Docs
letterSpacingnormal, .2remMDN Docs
lineHeightnormal, 150%MDN Docs
userSelectnone, auto, inheritMDN Docs

iframe Defaults

Highnote will inject iframes with the following defaults. Each of these can be overridden by your CSS styling.

The document and body inside the frame will have transparent backgrounds and default to margin: 0, padding: 0.

The document and body inside the frame will have transparent backgrounds and default to margin: 0, padding: 0.

Custom Fonts

Only system fonts are supported.

Layout

The layout of the payment card fields is up to you. Highnote will inject iframes into the provided container elements. The iframes will inherit the width of the container and you can also set the height to accommodate your UI as needed.

Styling
#pin {
  margin: 1em;
}

/* You can target the iframe with a child combinator. */
#pin > iframe {
  height: 140px;
}

Using the Live Environment

By default, the library will make requests against the test environment. When you are ready to switch to live, set the environment configuration option:

Live Environment
const { unmount } = await renderFields({
  // Set this to `live`
  environment: 'live',
  // ...
})

Lifecycle

Unmounting fields

If you need to unmount secure inputs, use the unmount method on the returned reference. This is useful when you are finished collecting inputs, need to “restart” the integration, or navigate to a new view client-side. Using this will ensure the cleanup of any DOM and event handlers.

Unmounting Fields
import { renderFields } from "@highnoteplatform/secure-inputs";

const { submit, unmount } = await renderFields({
  onSuccess: (field) => {
    if (field === "pin") {
      // Inform customer their PIN changed successfully.
      await unmount();
    }
  }
  // ...config
});

// ...
submit();

Content-Security Policy

If your application enforces a Content Security Policy, you will need to set the frame-src header (docs) to allow iframes from the Highnote domain.

Content-Security-Policy: frame-src https://sdk.highnoteplatform.com/

Provide Feedback

Was this content helpful?