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

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 a screening 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 Screening Group for the Applicant

Before you load the embedded widget, a screening group needs to be created for the applicant. For instructions on creating a Screening Group, please see our Screening 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 a screening group is created, store the screening IDs for each applicant within the group. That screening id is how Payscore knows which applicant’s screening to show in the embedded widget.

Generate an Authenticated Widget Token for the Current Applicant

To generate a widget token, you make a GET request to the /api/v1/screenings/{screening_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://api.staging.payscore.com/api/v1/screenings/{screening_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,
    screeningId,
    environment: 'staging' | 'production'
    onEvent
};

const incomeVerificationWidget = new IncomeVerificationWidget(payscoreWidgetOptions);

incomeVerificationWidget.load();