Getting Started

Installing the web SDK

Run one of the following commands at the root of your javascript project to install the SDK.

Using npm:

npm install --save @payscore/web-widget-sdk

Using yarn:

yarn add @payscore/web-widget-sdk

Please make sure your package version is at least 1.0.0

Selecting an Appropriate Environment

Payscore provides two environments for usage with the web-widget-sdk.

staging is used to develop and test your integration.

production is used for your application’s live environment.

Developers should be aware that API calls to create an applicant group and widget token will require you to use the same environment you are passing into the widget configuration.

Obtaining an Access Token

To interact with the Payscore API, you must first generate an access token and attach the token to the Authentication header to authenticate requests. To accomplish this, follow the instructions found in the Authentication Documentation.

Creating a Applicant Group for the Applicant

Before you load the embedded widget, an applicant group needs to be created for the applicant. For instructions on creating an Applicant Group, please see our Applicant Group Documentation. Make sure you set the is_invitation_disabled parameter to true to avoid sending an email or a text message invite to the applicant.

Once an applicant group is created, store the applicant IDs for each applicant within the group. That applicant id is how Payscore knows which applicant’s verifications to show in the embedded widget.

To generate a widget token, you make a GET request to the /api/v1/applicants/{applicant_id}/widget_token endpoint from your back-end with the following headers, and will receive the following response. We recommend adding a proxy endpoint in your backend that your front-end calls to obtain the widget token.

// Path
https://app.staging.payscore.com/api/v1/applicants/{applicant_id}/widget_token

// Headers
Method: 'GET'
Accept: 'application/json'
Content-Type: 'application/json'
Authorization: 'Bearer {accessToken}'


// Response
{
    'widget_token': '1234'
}

Incorporating the SDK

To use the widget, see the code example below. We recommend producing a new widget token every time you open the embedded widget.

import {
    IncomeVerificationWidget,
    PayscoreEventType,
    PayscoreEvent
} from '@payscore/web-widget-sdk'

const onEvent = (event: PayscoreEvent, widget: IncomeVerificationWidget) => {
    const { type, timestamp } = event;

    switch(type) {
        case PayscoreEventType.IncomeVerificationLoaded:
            // Your code here
            break;
        case PayscoreEventType.IncomeVerificationStarted:
            // Your code here
            break;
        case PayscoreEventType.IncomeVerificationCompleted:
            widget.unmount();
            // Your code here
            break;
    }
};

const { widgetToken } = // Your code here

const incomeVerificationWidgetOptions = {
    widgetToken,
    applicantId,
    environment: 'staging' | 'production'
    onEvent
};

const incomeVerificationWidget = new IncomeVerificationWidget(payscoreWidgetOptions);

incomeVerificationWidget.load();

import {
    IncomeVerificationWidget,
    PayscoreEvent,
    PayscoreEventType
} from '@payscore/web-widget-sdk';
import { FunctionComponent, useCallback, useEffect, useRef } from 'react';

export interface IncomeVerificationWidgetProps {
    applicantId: string;
    environment: 'staging' | 'production';
    widgetToken: string;
}

export const IncomeVerificationWidgetComponent: FunctionComponent<IncomeVerificationWidgetProps> = ({
    applicantId,
    environment,
    widgetToken,
}) => {
    const widgetRef = useRef<IncomeVerificationWidget | null>(null);

    const onEvent = useCallback(
        (event: PayscoreEvent, widget: IncomeVerificationWidget) => {
            const { type, timestamp } = event;

            switch (type) {
                case PayscoreEventType.IncomeVerificationLoaded:
                    // Your code here
                    break;
                case PayscoreEventType.IncomeVerificationStarted:
                    // Your code here
                    break;
                case PayscoreEventType.IncomeVerificationCompleted:
                    widget.unmount();
                    // Your code here
                    break;
            }
        },
        []
    );

    useEffect(() => {
        if (!widgetToken || !applicantId) {
            return;
        }

        const incomeVerificationWidgetOptions = {
            environment,
            onEvent,
            screeningId: applicantId,
            widgetToken,
        };

        const incomeVerificationWidget = new IncomeVerificationWidget(incomeVerificationWidgetOptions);
        widgetRef.current = incomeVerificationWidget;

        incomeVerificationWidget.load();

        return () => {
            if (widgetRef.current) {
                widgetRef.current.unmount();
                widgetRef.current = null;
            }
        };
    }, [applicantId, environment, onEvent, widgetToken]);

    return null;
};

PreviousEmbedded Widget NextEvents

Last updated 28 days ago

hashtagInstalling the web SDK

hashtagSelecting an Appropriate Environment

hashtagObtaining an Access Token

hashtagCreating a Applicant Group for the Applicant

hashtagGenerate an Authenticated Widget Token for the Current Applicant

hashtagIncorporating the SDK

Installing the web SDK

Selecting an Appropriate Environment

Obtaining an Access Token

Creating a Applicant Group for the Applicant

Generate an Authenticated Widget Token for the Current Applicant

Incorporating the SDK