Home / SDKs / Client Tokens and SDKs
The Highnote Secure Inputs SDK allows customers to securely input their sensitive data into 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.
Secure Inputs uses client tokens to request the Highnote GraphQL API on your behalf. You can generate client tokens using the generatePaymentCardClientToken
mutation.
The Secure Inputs SDK follows semver and can be installed from npm or a cdn.
You can install the Secure Inputs SDK with the following:
npm i @highnoteplatform/secure-inputs
yarn add @highnoteplatform/secure-inputs
pnpm add @highnoteplatform/secure-inputs
This package ships with TypeScript definitions installed.
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
.
You must set up elements to hold each field to render Secure Inputs in your UI. You can then initialize the JavaScript library to populate those elements with input fields via iframes.
First, you must obtain a client token from your server using the generatePaymentCardClientToken
mutation. When generating the client token, you must 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. Once the token has expired, you must generate a new one to re-render the payment card details.
You must provide the Secure Inputs with the elements you want to render iframes for. The following fields are supported for Secure Inputs:
<!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>
The library will inject an iframe into each element to render the appropriate data. You can style the content inside each iframe by passing any combination of allowed styles.
You can initialize the Secure Inputs by calling renderFields
. This returns a Promise that contains a reference to the secureInputs
instance. This is useful for lifecycle management and interactions such as field submission.
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 }, });
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 don’t render error messages or update the UI inside iframes when errors occur. You must introspect and handle errors accordingly.
Error | Description |
---|---|
InvalidCredentialError | Occurs when the provided Client Token is invalid or expired. The payload will contain the requestId which can be used for support and debugging. |
SecureInputsRequestError | Represents 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. |
SecureInputsFieldsInputError | Raised when an invalid configuration is provided at runtime. |
SecureInputsError | A generic catchall error. |
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, // ... });
Property | Examples | Docs |
---|---|---|
color | #55f5a3 , rgba(85,245,163,1) , #springgreen | MDN Docs |
cursor | pointer , none | MDN Docs |
fontFamily | sans-serif , serif , monospace System fonts only | MDN Docs |
fontSize | 12px , 1em , 1.1rem | MDN Docs |
fontWeight | bold , normal | MDN Docs |
letterSpacing | normal , .2rem | MDN Docs |
lineHeight | normal , 150% | MDN Docs |
userSelect | none , auto , inherit | MDN Docs |
Highnote will inject 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
.
Only system fonts are supported.
The layout of 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. You can also set the height to accommodate your UI as needed.
#pin { margin: 1em; } /* You can target the iframe with a child combinator. */ #pin > iframe { height: 140px; }
By default, the library will make requests against the Test Environment. When you are ready to switch to 'live', set the environment
configuration option:
const { unmount } = await renderFields({ // Set this to `live` environment: 'live', // ... })
Use the unmount
method on the returned reference if you need to unmount secure inputs. 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.
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();
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: frame-src https://sdk.highnoteplatform.com/