Home / SDKs / Client Tokens and SDKs
The Document Upload SDK allows you to collect identity verification documents from your Account Holders when an Application for your Card Product enters manual review. The Document Upload SDK will enable you to seamlessly embed a UI for document upload collection into your customer onboarding experience. You can initialize the SDK when an application has an IN_REVIEW
status, and you have retrieved the application’s document upload session ID(s) and generated the necessary client token(s).
The Document Upload SDK uses client tokens to request the Highnote GraphQL API on your behalf. You can generate client tokens using the GenerateDocumentUploadClientTokenPayload
mutation.
The Document Upload SDK follows semver and can be installed from npm or a cdn.
You can install the Document Upload SDK with the following:
npm i @highnoteplatform/document-upload
yarn add @highnoteplatform/document-upload
pnpm add @highnoteplatform/document-upload
This package ships with TypeScript definitions installed.
You can install the Document Upload SDK directly from a CDN such as JSDelivr on your page. This is helpful when exploring the SDK or using tools such as CodeSandbox.
We recommend that you select a specific version of the library to use. You can replace @latest
with your chosen version, for example, @1.0.0
.
<script src="https://cdn.jsdelivr.net/npm/@highnoteplatform/document-upload@latest/lib/index.js"></script>
If an Account Holder's card application status is IN_REVIEW
, they must provide specific documents for Customer Identification Program (CIP) verification. To allow Account Holders to upload documentation, you must refer to your document upload session ID to begin a private and secure document upload and verification session.
Use the following query to retrieve an Application and fetch your document upload session ID:
After fetching the document upload session ID, you must obtain a client token from your server using the generateDocumentUploadClientToken
mutation. When generating the client token, you must provide the document upload session ID for collecting documents.
You can safely provide the resulting token to your client and pass the token to the Highnote JavaScript SDK. The token 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 document upload session.
You must provide the Document Uploader with an element to which you can append the new HTMLDivElement
. The library will append an HTMLDivElement
into this element to render the appropriate widget. You can style the content inside each iframe by passing any combination of allowed styles.
<!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>Document-Upload</title> </head> <body> <div class="side-rail"> <form id="documentUploadConfig"> <label for="clientToken">Client Token</label> <input type="text" name="clientToken" id="clientToken" placeholder="Client Token" /> <div class="margin-top"> <label for="documentUploadSessionId" >Document Upload Session ID</label > <input type="text" name="documentUploadSessionId" id="documentUploadSessionId" placeholder="Document Upload Session ID" /> </div> <button type="submit"> Initialize Document Upload </button> </form> </div> <div id="document-upload-component"> <!-- An new DOM element will be appended here --> </div> </body> </html>
You can initialize the DocumentUpload SDK by calling initializeDocumentUploadSdk
. This will return a Promise containing a reference to the documentUpload
instance which includes helper methods to enact on the SDK, such as unmount
and endSession
.
import { initializeDocumentUploadSDK } from "@highnoteplatform/document-upload"; const { unmount, endSession } = await initializeDocumentUploadSdk({ clientToken: "client-token", documentUploadSessionId: "document-upload-session-id", environment: "test", documentUploadComponent: { selector: "#document-upload-component" }, onSuccess: handleSuccess, onError: handleError });
Error | Description |
---|---|
InvalidCredentialError | This error occurs when the provided Client Token is invalid or expired. The payload will contain the requestId , which can be used for support and debugging. |
DocumentUploadRequestError | This error represents errors encountered when communicating with the Highnote GraphQL API. The payload will contain the requestId , which can be used for support and debugging. |
DocumentUploadConfigurationError | This error is raised when an invalid configuration is provided at runtime. Example messages include: |
Invalid client token | |
Invalid Document Upload Session ID | |
Invalid environment. Please provide test or live. | |
GenericDocumentUploadError | All unknown and unexpected errors. |
import { initializeDocumentUploadSDK } from "@highnoteplatform/document-upload"; const handleError = ( error: Error ) => { switch (error.name) { case "InvalidCredential": // Handle invalid/expired credential // Unmount fields, fetch new client token, re-initialize console.error(error.context.requestId); // "some-request-id" break; case "DoumentUploadRequestError": console.error(error.context.requestId); // some-request-id break; case "DocumentUploadConfigError": console.error(error.message); // "Invalid Session ID" break; default: console.error(error); } }; const handleOnLoad = (component: Element) => { console.log(`[Integrator log]: ${component.id} value appended to selector!`); }; const handleOnSuccess = (onSuccess: boolean) => { if (onSuccess) { console.log(`[Integrator log]: All documents uploaded and session closed.`); } }; await initializeDocumentUploadSdk({ clientToken: "client-token", documentUploadSessionId: "document-upload-session-id", environment: "test", documentUploadComponent: { selector: "#document-upload-component" }, onLoad: handleOnLoad, onSuccess: handleOnSuccess, onError: handleError, });
The SDK renders HTML content of the following types whose style you can customize to match the aesthetic of your UI. For each element, you can provide a styles object with JavaScript CSSProperties.
HTML Element | id | Description |
---|---|---|
<div> | document-upload-component | The selector provided during initialization of the SDK. |
<div> | inner-document-upload-component | The <div> that is rendered by the SDK. |
<div> | reloaded-document-upload-component | The <div> that contains documents required and documents uploaded. This <div> reloaded on each new upload. |
<div> | stagnant-document-upload-component | The <div> that contains all elements that are not reloaded. |
<input> | file-upload-component | The file selector for uploads. |
<select> | document-type | The list of documents to be uploaded. |
<button> | document-upload-button | Button to upload required documents. |
<h4> | All section headings. | |
<p> | All informational text. |
By default, the library will make requests against the Test Environment. When you are ready to switch to the Live Environment, set the environment
configuration option:
const { unmount, endSession } = await initializeDocumentUploadSdk({ clientToken: "client-token", documentUploadSessionId: "document-upload-session-id", environment: "live", documentUploadComponent: { selector: "#document-upload-component" }, onSuccess: handleSuccess, onError: handleError });
When the Document Upload SDK initializes, it automatically renders the required document upload widget and closes the sessions once all requirements are met. You are required to handle onSuccess
and onError
behavior as you wish. The rendered widget contains two sections:
The widget guides the user through the document upload process with reloaded components triggered by an upload event on subsequent steps. When no more documents are left to be uploaded, the SDK will end the document upload session and submit uploads for review.
The Highnote Document Upload SDK allows you to create an experience for Account Holders to upload documentation when onboarding to your Card Product.
Once the SDK is initialized, the <HTMLDivElement>
provides the applicant with a list of uploaded documents and a dropdown select bar with required documents. By picking a document to upload and clicking on the Upload button, the applicant must be able to successfully upload all required documents until no document type options remain to select from the dropdown.
The SDK provides a call back function for you to unmount the SDK and decouple it with the client-token for a fresh start at anytime.
The SDK provides a call back function for you to end a document session at any time. This action will submit the documents already uploaded for review.