Document Upload SDK
Highnote's document upload SDK allows you to collect identity verification documents from account holders when a card product application enters manual review.
This guide provides an overview of requirements, installation steps, and usage guidelines for the document upload SDK.
- A Highnote account
- A server-side integration using an API key
- Document upload session ID
- An HTML selector for injecting a DOM element
You can install the document upload SDK using JavaScript package managers or CDN. For more installation information, see the SDK Installation guide.
- JSDelivr Script Tag
To use the document upload SDK, you must fetch a document upload session ID and set up elements for each field. This involves the following steps:
- Prepare your HTML.
- Fetch document upload session ID
- Fetch a client token.
- Initialize document upload.
To use the document upload SDK, you must provide an element to append the HTMLDivElement to. The document upload library will use the HTMLDivElement to render the appropriate document upload widget. You can style the content inside the widget by passing any combination of styling options.
The following code sample shows an example how you can prepare your HTML for the document upload SDK:
- Prepare HTML
If an account holder's card product application status is IN_REVIEW , they must provide specific documents for Customer Identification Program (CIP) verification. To use the document upload SDK for document collection, you must use a document upload session ID to start a secure document upload session.
Use the following query to retrieve a card product application and fetch your document upload session ID:
To obtain a client token from your server for the document upload SDK, use the generateDocumentUploadClientToken mutation.
Refer to the following guidelines when generating a payment card client token:
- When generating the client token, you must provide the
documentUploadSessionIdof the payment card you are rendering. - The client token is only valid for 10 minutes, but can be used multiple times.
- Once a token expires, you must generate a new one to render payment card details.
Use the following mutation to generate a document upload client token:
You can initialize the document upload SDK by calling an initializeDocumentUploadSdk function. This returns a Promise containing a reference to the documentUpload instance, which includes helper methods to enact on the SDK such as unmount and endSession.
The following code sample is an example of an initializeDocumentUploadSdk function:
- Initialize Document Upload
The following error types are supported for the document upload SDK:
| 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 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. |
The following code sample provides examples of document upload errors:
- Error Examples
The following styling options are available for use in elements for your document upload widget:
| 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 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:
- Live Environment
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:
- Documents uploaded: Includes documents already uploaded
- 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.
The document upload SDK supports the following interactions:
- Allows account holder to upload documentation
- Unmount the SDK
- End the document upload session
Once the SDK is initialized, the document upload widget provides the applicant with a list of uploaded documents and a dropdown menu with outstanding, required documents.
The account holder can pick a document to upload and click 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 document upload SDK provides a call-back function for you to unmount the SDK. This allows you to decouple it with the client-token for a fresh start at any time.
