Checkout SDK

Loading SDK demo...

Overview

checkout vs secure inputs

The Checkout SDK is a drop-in solution with some customization options. For a more customizable solution, use the Secure Inputs for Tokenization SDK.

The Highnote Checkout SDK is a checkout UI that you can embed in your application or website to accept payment card information. The Checkout SDK uses an iframe that prevents PCI-scoped data from flowing through your system or being accessible to scripts running on your page.

This guide explains how to install and use the Checkout SDK.

Prerequisites

A Highnote account
A server-side integration using an API key

Installation

The Highnote Checkout SDK follows semver and can be installed using the following:

JavaScript package manager: npm, yarn, or pnpm
Content Delivery Network (CDN) via traditional <script> tag or ECMAScript module.

Install by package manager

The Checkout SDK supports the following JavaScript package managers: npm, yarn, and pnpm.

npm
npm i @highnoteplatform/checkout

yarn
yarn add @highnoteplatform/checkout

pnpm
pnpm add @highnoteplatform/checkout

Install by CDN

install by @version-number

To ensure stability and avoid potential issues caused by updates, replace @latest with a specific version number such as @1.0.0.

You can install Checkout SDK directly from a content delivery network (CDN) such as JSDelivr.

The SDK supports both traditional script tags and ECMAScript module imports. ESM imports require modern browsers. To support older browsers, use the traditional script tag approach with appropriate polyfills.

Script tag

To install the Checkout SDK by <script> tag, add the following to your HTML file:

Script tag for Checkout SDK
<script src="https://cdn.jsdelivr.net/npm/@highnoteplatform/checkout@latest/lib/index.js"></script>

ESM import

To install the Checkout SDK by ESM module, add the following to your HTML file:

ESM import for Checkout SDK
<script type="module">
  import { Checkout } from "https://cdn.jsdelivr.net/npm/@highnoteplatform/checkout@latest/lib/index.js";

  // Initialize the Checkout
  const checkout = new Checkout({
    // configuration options
  });
</script>

Usage

To accept payment information, configure elements to hold each field of the checkout iframe as follows:

Prepare your HTML
Fetch a client token
Initialize checkout
Charge payment method.

Prepare your HTML

You must provide the Checkout SDK with an HTML selector for the element the checkout UI is rendered in. This element must be mounted before initializing the Checkout SDK.

The following example uses a <div> element to mount the Checkout SDK iframe:

Prepare HTML for checkout
<!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>Checkout</title>
  </head>
  <body>
    <div id="checkout">
      <!-- An iframe will be injected here -->
    </div>
  </body>
</html>

Fetch a client token

info

A payment method tokenization client token can only be used one time.

To obtain a client token from your server for the Checkout SDK, use the following generatePaymentMethodTokenizationClientToken mutation:

GeneratePaymentMethodTokenizationClientToken

Query

mutation GeneratePaymentMethodTokenizationClientToken(
  $input: GeneratePaymentMethodTokenizationClientTokenInput!
) {
  generatePaymentMethodTokenizationClientToken(input: $input) {
    __typename
    ... on ClientToken {
      expirationDate
      usage
      value
    }
  }
}

Variables

{
  "input": {
    "permissions": [
      "TOKENIZE_PAYMENT_METHOD"
    ]
  }
}

⚠️ Please login to execute queries. Visit the dashboard to authenticate.

Result

{
  "data": {
    "generatePaymentMethodTokenizationClientToken": {
      "__typename": "ClientToken",
      "expirationDate": "2024-01-01T00:00:00.000Z",
      "usage": "UNTIL_EXPIRATION",
      "value": "TOKEN"
    }
  },
  "extensions": {
    "requestId": "REQUEST_ID",
    "rateLimit": {
      "cost": 10,
      "limit": 60060,
      "remaining": 60049
    }
  }
}

Initialize checkout

You can initialize the Checkout SDK by using a renderCheckout function. This returns a Promise that contains an object with an unmount method that can be used to remove the checkout UI. The client token and selector you fetched previously must be passed to this function as part of the configuration. Invalid configuration values will return a CheckoutConfigInputError message.

The onTokenizeSuccess method passes a payload object that contains a token field. This field is the PaymentMethodToken object. You can call your server endpoint with the payload.token to create an authorization using the chargePaymentMethodToken mutation.

Use the following code snippet to initialize checkout:

Initialize checkout
import { renderCheckout } from "@highnoteplatform/checkout";

try {
  const { unmount } = await renderCheckout({
    selector: "#checkoutForm",
    clientToken: "client token from server",

    onTokenizeError: (error) => {
      // handle error from tokenization call
    },

    onTokenizeSuccess: (payload) => {
      // handle success
    },
  });
} catch (error) {
  console.log(error.errors);
}

Charge payment method

To create an authorization using the payload.token, you must make a server-side call to the chargePaymentMethod mutation and pass the token ID returned when initializing checkout.

Use the following mutation to charge a payment method:

ChargePaymentMethodToken

Query

mutation ChargePaymentMethodToken($input: ChargePaymentMethodTokenInput!) {
  chargePaymentMethodToken(input: $input) {
    __typename
    ... on CardCaptureStepSummary {
      transaction {
        __typename
        id
        createdAt
        accountingDirection
        authorizedAmount {
          value
          currencyCode
        }
        authorizedRemainingAmount {
          value
          currencyCode
        }
        canceledAmount {
          value
          currencyCode
        }
        networkTransactionIdentifier
        settledAmount {
          value
          currencyCode
        }
        disbursedAmount {
          value
          currencyCode
        }
        canceledAmount {
          value
          currencyCode
        }
        refundedAmount {
          value
          currencyCode
        }
        responseCode {
          processorResponseCode
          addressCode
          postalCode
          securityCode
        }
      }
    }
  }
}

Variables

{
  "input": {
    "paymentMethodTokenId": "tkpmc_01",
    "merchantAcceptorId": "acqma_01",
    "amount": {
      "value": 1000,
      "currencyCode": "USD"
    },
    "idempotencyKey": "00000000-0000-0000-0000-000000000000",
    "paymentInitiator": "CUSTOMER_INITIATED_VIA_WEB"
  }
}

⚠️ Please login to execute queries. Visit the dashboard to authenticate.

Result

{
  "data": {
    "chargePaymentMethodToken": {
      "__typename": "CardCaptureStepSummary",
      "transaction": {
        "__typename": "PaymentDebitTransactionSummary",
        "id": "acqpt_01",
        "createdAt": "2024-06-24T18:16:15.297Z",
        "accountingDirection": "CREDIT",
        "authorizedAmount": {
          "value": 1000,
          "currencyCode": "USD"
        },
        "authorizedRemainingAmount": {
          "value": 0,
          "currencyCode": "USD"
        },
        "canceledAmount": null,
        "networkTransactionIdentifier": null,
        "settledAmount": null,
        "disbursedAmount": null,
        "refundedAmount": null,
        "responseCode": {
          "processorResponseCode": "APPROVED",
          "addressCode": "NOT_PROVIDED",
          "postalCode": "NOT_PROVIDED",
          "securityCode": "NOT_VERIFIED"
        }
      }
    }
  },
  "extensions": {
    "requestId": "REQUEST_ID",
    "rateLimit": {
      "cost": 19,
      "limit": 60060,
      "remaining": 60040
    }
  }
}

Error handling

Refer to the following guidelines for handling Checkout SDK errors:

Input validations are handled implicitly by the SDK and shown as errors inline.
For tokenization errors, the checkout UI will show a default error state.
Optional - Pass an onTokenizeError callback to the renderCheckout function if you want to perform custom error handling.

Error types

The following error types are supported for the Secure Inputs SDK for tokenization:

Error	Description
InvalidCredentialError	The provided client token is invalid or expired. Use the `requestId` in the payload for support and debugging.
SecureInputsRequestError	Represents errors encountered when communicating with the Highnote API, such as an incorrect payment card ID. Use the `requestId` in the payload for support and debugging.
SecureInputsFieldsInputError	Raised when an invalid configuration is provided at runtime.
GenericError	A generic catchall error.

Checkout form

The checkout form uses the following default fields:

Card number
Expiration date
CVV/CVC
Postal code

Default fields are required to tokenize a payment method and always rendered.

Additional fields

To add additional fields to the checkout form, use the additionalFormSections object:

cardHolderName — renders a full name input field
billingAddress — renders address fields for street address, extended address, city, state, postal code, and country

Required for INT transactions

When tokenizing for Instant Network Transfers (INT), cardHolderName and billingAddress are required for OFAC and AVS compliance checks. Set both to true.

Example

The following code snippet is an example configuration for a checkout form:

Cardholder name setting
const { unmount } = await renderCheckout({
  selector: "#checkoutForm",
  clientToken: "client token from server",

  additionalFormSections: {
    cardHolderName: true,
    billingAddress: true,
  },

  onTokenizeError: (error) => {
    // handle error from tokenization call
  },

  onTokenizeSuccess: (payload) => {
    // handle success
  },
});

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 renderCheckout({
  // Set this to `live`
  environment: "live",
  // ...
});

Lifecycle

If you need to unmount payment card fields, use the unmount method on the returned reference. This is useful when you are finished with tokenization, 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.

The following code sample provides an example function to unmount fields:

import { renderFieldsForTokenization } from "@highnoteplatform/secure-inputs";

const { unmount } = await renderCheckout({
  onTokenizeSuccess: async (tokenPayload) => {
    // Send token to your server to make charge
    await unmount();
  },
  // ...config
});

Content security policy

If your application enforces a content security policy, you must set the frame-src header to allow iframes from the Highnote domain:

Content security policy
Content-Security-Policy: frame-src https://cdn.highnote.com

Overview​

Prerequisites​

Installation​

Install by package manager​

Install by CDN​

Script tag​

ESM import​

Usage​

Prepare your HTML​

Fetch a client token​

GeneratePaymentMethodTokenizationClientToken​

Initialize checkout​

Charge payment method​

ChargePaymentMethodToken​

Error handling​

Error types​

Checkout form​

Additional fields​

Example​

Using the Live environment​

Lifecycle​

Content security policy​