Home / SDKs / Client Tokens and SDKs

Document Upload SDK

Document Upload

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.

Requirements

  1. A Highnote Account
  2. A server-side integration using an API Key
  3. Document Upload Session ID
  4. A HTML selector for injecting a DOM Element

Installation

The Document Upload SDK follows semver and can be installed from npm or a cdn.

via NPM

You can install the Document Upload SDK with the following:

  • With npm - npm i @highnoteplatform/document-upload
  • With yarn - yarn add @highnoteplatform/document-upload
  • With pnpm - pnpm add @highnoteplatform/document-upload

This package ships with TypeScript definitions installed.

via CDN

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.

JSDelivr Script Tag
<script src="https://cdn.jsdelivr.net/npm/@highnoteplatform/document-upload@latest/lib/index.js"></script>

Fetch Document Upload Session ID

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:

Fetch a Client Token

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.

Prepare your HTML

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.

Prepare HTML
<!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>

Initialize Document Upload

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.

Initialize Document Upload
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 Types

ErrorDescription
InvalidCredentialErrorThis 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.
DocumentUploadRequestErrorThis 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.
DocumentUploadConfigurationErrorThis 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.
GenericDocumentUploadErrorAll unknown and unexpected errors.
Error Examples
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,
});

Styling Options

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 ElementidDescription
<div>document-upload-componentThe selector provided during initialization of the SDK.
<div>inner-document-upload-componentThe <div> that is rendered by the SDK.
<div>reloaded-document-upload-componentThe <div> that contains documents required and documents uploaded. This <div> reloaded on each new upload.
<div>stagnant-document-upload-componentThe <div> that contains all elements that are not reloaded.
<input>file-upload-componentThe file selector for uploads.
<select>document-typeThe list of documents to be uploaded.
<button>document-upload-buttonButton to upload required documents.
<h4>All section headings.
<p>All informational text.

Using the Live Environment

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:

Live Environment
const { unmount, endSession } = await initializeDocumentUploadSdk({
  clientToken: "client-token",
  documentUploadSessionId: "document-upload-session-id",
  environment: "live",
  documentUploadComponent: { selector: "#document-upload-component" },
  onSuccess: handleSuccess,
  onError: handleError
});

Lifecycle

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:

  1. Documents uploaded
  2. Documents required - Includes a drop-down of the required documents and a method for uploading them

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.

Documents uploaded.png

Interactions

The Highnote Document Upload SDK allows you to create an experience for Account Holders to upload documentation when onboarding to your Card Product.

Upload Document

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.

Unmount SDK

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.

End Session

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.

Provide Feedback

Was this content helpful?