@highnoteplatform/document-upload

Note: This library is in a pre-release phase. Prior to the release of version 1.0.0, breaking changes may be introduced.

Document Upload SDK simplifies our Subscriber’s integration.

It minimizes impact for Subscriber to changes in Highnote’s manual reviews.

It expands the secured document upload capability.

Requirements

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

Installation

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 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.

<script src="https://cdn.jsdelivr.net/npm/@highnoteplatform/document-upload@latest/lib/in

Usage

Step 1: Get your documentUploadSessionId

Get your documentUploadSessionId

GraphQL query

query getApplication($id: ID!) {
  node(id: $id) {
    ... on AccountHolderCardProductApplication {
      id
      accountHolderSnapshot {
        ... on USPersonAccountHolderSnapshot {
          currentVerification {
            requiredDocuments {
              ... on AccountHolderApplicationRequiredDocument {
                documentUploadSession {
                  ... on USAccountHolderApplicationDocumentUploadSession {
                    id
                  }
                }
              }
            }
          }
        }
        ... on USBusinessAccountHolderSnapshot {
          primaryAuthorizedPerson {
            currentVerification {
              requiredDocuments {
                ... on AccountHolderApplicationRequiredDocument {
                  documentUploadSession {
                    ... on USAccountHolderApplicationDocumentUploadSession {
                      id
                    }
                  }
                }
              }
            }
          }
          businessProfile {
            currentVerification {
              requiredDocuments {
                ... on AccountHolderApplicationRequiredDocument {
                  documentUploadSession {
                    ... on USAccountHolderApplicationDocumentUploadSession {
                      id
                    }
                  }
                }
              }
            }
            ultimateBeneficialOwners {
              currentVerification {
                requiredDocuments {
                  ... on AccountHolderApplicationRequiredDocument {
                    documentUploadSession {
                      ... on USAccountHolderApplicationDocumentUploadSession {
                        id
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Input variables

{
  "id": "APPLICATION_ID"
}

Response

{
  "data": {
    "node": {
      "id": "ap_22bflm1504f70a9d624437aee126cccbee3c80",
      "accountHolderSnapshot": {
        "primaryAuthorizedPerson": {
          "currentVerification": {
            "requiredDocuments": [
              {
                "documentUploadSession": {
                  "id": "du_22aspapae536c062aa644a7b147e34997016a81"
                }
              }
            ]
          }
        },
        "businessProfile": {
          "currentVerification": {
            "requiredDocuments": [
              {
                "documentUploadSession": {
                  "id": "du_22ahbapcadfaa2085314a8f8fdde89a2b101c98"
                }
              }
            ]
          },
          "ultimateBeneficialOwners": []
        }
      }
    }
  },
  "extensions": {
    "requestId": "331f81c8-f28b-9975-9abe-d85eaab69a1a",
    "rateLimit": {
      "limit": 30030,
      "remaining": 30016,
      "cost": 14
    }
  }
}

Step 2: Generate a client token

On your server, generate a client token using the GraphQL API.

See the generateDocumentUploadClientToken docs.

GraphQL query

mutation GenerateDocumentUploadClientToken(
  $input: GenerateDocumentUploadClientTokenInput!
) {
  generateDocumentUploadClientToken(input: $input) {
    ... on ClientToken {
      value
      expirationDate
      usage
    }
  }
}

Input variables

{
  "input": {
    "documentUploadSessionId": "DOCUMENT_UPLOAD_SESSION_ID_FROM_ABOVE",
    "permissions": ["MANAGE_DOCUMENT_UPLOAD_SESSION"]
  }
}

Response

{
  "data": {
    "generatePaymentCardClientToken": {
      "value": "TOKEN",
      "expirationDate": "2022-02-07T20:04:50.633Z",
      "usage": "UNTIL_EXPIRATION"
    }
  },
  "extensions": {
    "requestId": "example-request-id"
  }
}

Step 3: Prepare your HTML

You must provide the Document Uploader with an element to which the new HTMLDivElement can be appended.

document-upload-component

<!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>
    <script src="index.ts" type="module"></script>
  </body>
</html>

The library will append a HTMLDivElement into this element to render the appropriate widget. You can style the content inside of each iframe by passing any combination of allowed styles.

You can initialize the Document Upload by calling initializeDocumentUploadSdk. This will return a Promise that, will contain a reference to the HTMLDivElement instance.

Error Handling

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.	name: "InvalidCredential" context: object requestId: string
*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.	name: "DocumentUploadRequestError" message: string context: object requestId: string
*DocumentUploadConfigError* This error is raised when an invalid configuration is provided at runtime.	name: "DocumentUploadConfigError" message: string

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,
});