Home

Checkout SDK

Overview

Note: The checkout SDK is a drop-in solution with fewer customization options. For a more customizable solution, use the Secure Inputs for Tokenization SDK.

Highnote's 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 provides an overview of requirements, installation steps, and usage guidelines for the checkout SDK.

Prerequisites

  1. A Highnote account
  2. A server-side integration using an API key

Installation

You can install the checkout SDK using JavaScript package managers or CDN. For more installation information, see the SDK Installation guide.

Usage

To accept payment information, you must set up elements to hold each field of the checkout iframe. This involves the following steps:

  1. Prepare your HTML.
  2. Fetch a client token.
  3. Initialize checkout.
  4. 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

Fetch a client token

Warning: 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:

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

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:

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:

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 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.
GenericErrorA 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, you can use the additionalFormSections object. These fields are optional:

  • cardHolderName
  • billingAddress

Example

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

Cardholder name setting

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

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:

Unmounting Fields

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

Provide Feedback

Was this content helpful?