Card Viewer SDK

The Highnote Card Viewer SDK lets you embed sensitive card data into your UI using iframes. This prevents PCI-scoped data from flowing through your servers or from being accessible to scripts running on your page.

1. A Highnote account
2. A server-side integration using an API key
3. Payment card ID

The Highnote Card Viewer 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.

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

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 the Card Viewer 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.

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

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

To render card details in your UI, you must set up elements to hold each field as follows:

1. Prepare your HTML with card detail elements.
2. Fetch a client token.
3. Initialize card viewer.

To use the Card Viewer SDK, provide an element for each field you want to render in an iframe. The following example uses Card number, CVV, Expiration date.

To obtain a client token from your server for the Card Viewer SDK, use the generatePaymentCardClientToken mutation.

Refer to the following guidelines when generating a payment card client token:

• Provide the paymentCardId of the payment card you are rendering.
• The client token is only valid for 10 minutes, but can be used multiple times.
• Once a token expires, you must generate a new one to render payment card details.

Use the following mutation to generate a payment card client token:

The card viewer library works by injecting an iframe into each provided element to render the appropriate data. You can style the content inside each iframe by passing any combination of styling options.

You can initialize the card viewer by using a renderFields function. This returns a Promise that contains a reference to the cardViewer instance. This is useful for lifecycle management and interactions such as card number masking.

The following example shows how to initialize the card viewer:

Note: The card viewer doesn’t render error messages or update your UI inside iframes when errors occur. You must introspect and handle errors accordingly.

When initializing the card viewer, you can pass an onError handler to the renderFields function. This callback is invoked whenever an error is raised from the integration.

The following error types are supported for the Card Viewer SDK:

The following code sample provides examples of card viewer errors:

The following styling options are available for use in elements for your card viewer:

Highnote injects card viewer iframes with the following defaults. Your CSS styling can override each of these:

• border: none
• width: 300px (browser default)
• height: 150px (browser default)

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

The Card Viewer SDK only supports system fonts.

The layout of payment card fields in the card viewer is customizable. Highnote injects iframes into the provided container elements, which will inherit the width of the container.

You can customize the width and height of the container to accommodate your UI as needed.

The following code sample provides an example of custom layout styling:

By default, the card viewer library will make requests against the test environment. When you are ready to switch to the live environment, set the environment configuration option using the following function call:

The Card Viewer SDK has a lifecycle that consists of a loading state, which resolves with payment card details. You can also unmount payment card details as needed.

When rendering card viewer fields, the library writes the required iframes into your UI and renders them in a loading state. While in the loading state, the fields will be populated with placeholder characters:

• Card number: •••• •••• •••• ••••
• CVV: •••
• Expiration Date: ••/••

You can't change these values. Once the configuration has been validated and the fields rendered, the library will request the card details from the Highnote API and replace the loading values with the corresponding data.

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

The Card Viewer SDK supports the following end-user interactions:

• Account holders can toggle sensitive data via card number masking
• Account holders can copy their payment card details to their clipboard to complete payments

By default, the payment card number will be masked (•••• •••• •••• ••••). Only the last four digits will be shown when the card number is available.

You can toggle the masking on and off using the toggleCardNumberMask method on the returned card viewer reference.

The following code sample is an example of a card number masking configuration:

By default, users can select and copy payment card detail values to their clipboard. You can use the enableClipboard configuration property to toggle the "copy to clipboard" feature on or off.

When enabled, clicking the card number, expiration date, or CVV field will copy the underlying value to the account holder's clipboard. This results in a copy event.

In addition to the copy event, two callback functions allow customization when a user copies or fails to copy a value:

The following code sample is an example of a copy to clipboard configuration:

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