Checkout SDK

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.

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

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

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.

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:

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:

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:

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:

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.

The following error types are supported for the secure inputs SDK for tokenization:

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.

To add additional fields to the checkout form, you can use the additionalFormSections object. These fields are optional:

• cardHolderName
• billingAddress

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

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

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:

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