Events

All events will have the following format, that includes a type and timestamp on the object. Certain events have a payload property with more event properties. See Specific Event Payloads for more details.

{
   type: 'payscore/incomeVerification/loaded',
   timestamp : "2011-12-19T15:28:46.493Z",
   payscore: true,
   methods: IncomeVerificationMethod[]
   payload?: Object
}

Event Type	Description
payscore/incomeVerification/loaded	Triggers when the widget loads. Can be used to provide your own “widget loading” experience prior to widget mount.
payscore/incomeVerification/widgetClosed	Triggers when the embedded widget is manually closed by the applicant.
payscore/incomeVerification/started	Triggers when the applicant interacts with the workflow for the first time.
payscore/incomeVerification/institutionSelected	Triggers when an applicant selects a bank, payroll provider, or employer.
payscore/incomeVerification/institutionConnected	Triggers when an applicant successfully connects to their bank, payroll provider, or employer.
payscore/incomeVerification/loginAttempt	Triggers when an applicant attempts to login via bank or payroll provider
payscore/incomeVerification/loginAttemptFailed	Triggers when an attempted login fails. Most commonly seen with incorrect credentials, or an MFA challenge. Bank login attempt failures include: 1. Incorrect credentials 2. Incorrect security answer 3. MFA challenge 4. Security questions expired 5. Account locked 6. Additional authorization required 7. User action required
payscore/incomeVerification/providerError	Triggers when an attempted login fails, or a connection to the provider cannot be made, for reasons outside of general login failure.
payscore/incomeVerification/documentUploaded	Triggers when an applicant uploads a document.
payscore/incomeVerification/completed	Triggers when the applicant completes the workflow, fills out the feedback (or skips it), and submits the report. The widget should be closed after this event.

Specific Event Payloads

Certain events contain payloads of data pertaining to the event that occurred. When using typescript, you can use the generic PayscoreBaseEvent type to narrow the payload value for your object.

Payload resolution:

payscore/incomeVerification/institutionConnected	{ institution: string; method: IncomeVerificationMethod }
payscore/incomeVerification/institutionSelected	{ institution: string; method: IncomeVerificationMethod }
payscore/incomeVerification/loginAttempt	{ institution: string; method: IncomeVerificationMethod; }
payscore/incomeVerification/loginAttemptFailed	{ institution: string; method: IncomeVerificationMethod; }
payscore/incomeVerification/providerError	{ institution: string; method: IncomeVerificationMethod; errorMessage: string; }

Example:

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

    switch (type) {
        case PayscoreWidgetEventType.InstitutionConnected: {
            // Cast to narrow payload
            const { payload } = event as PayscoreBaseEvent<PayscoreWidgetEventType.InstitutionConnected>;
            console.log(payload.institution);
            break;
        }
    }
};

Pass the event type as the generic argument and TypeScript will enforce the correct payload shape — or undefined for event types that carry no payload.