Highnote's secure inputs SDK allows customers to securely set and update their PIN from your UI using iframes. This prevents PCI-scoped data from flowing through your servers or being accessible to scripts running on your page.
This guide provides an overview of requirements, installation steps, and usage guidelines for the secure inputs SDK.
You can install the secure inputs SDK using JavaScript package managers or CDN. For more installation information, see the SDK Installation guide.
To render secure input fields in your UI, you must configure elements to hold each field. This involves the following steps:
To use the secure inputs SDK, you must provide an element for the PIN field.
The following code sample uses a div
element to contain the iframe for the secure input field:
To obtain a client token from your server for the secure inputs SDK, use the GeneratePaymentCardClientToken
mutation.
Refer to the following guidelines when generating a payment card client token:
paymentCardId
of the payment card that needs the PIN set or updated.Use the following mutation to generate a payment card client token:
The secure inputs library works by injecting an iframe into the PIN 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 secureInputs
instance. This is useful for lifecycle management and interactions such as field submission.
The following example shows how to initialize the secure inputs SDK:
Note: The secure inputs SDK doesn’t render error messages or update your UI inside iframes when errors occur. You must introspect and handle errors accordingly.
You can pass an onError
handler to the renderFields
call. This callback will be invoked whenever an error is raised from the integration.
The following error types are supported for the secure inputs SDK:
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 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. |
The following styling options are available for use in elements for your secure inputs fields:
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 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 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:
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:
If your application enforces a content security policy, you must set the frame-src header to allow iframes from the Highnote domain: