> For the complete documentation index, see [llms.txt](https://docs.payscore.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payscore.com/embedded-widget/events.md).

# 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](#specific-event-payloads "mention") for more details.

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

<table><thead><tr><th width="513.6015625">Event Type</th><th width="442.14453125">Description</th></tr></thead><tbody><tr><td><code>payscore/incomeVerification/loaded</code></td><td>Triggers when the widget loads.<br>Can be used to provide your own “widget loading” experience prior to widget mount.</td></tr><tr><td><code>payscore/incomeVerification/widgetClosed</code></td><td>Triggers when the embedded widget is manually closed by the applicant.</td></tr><tr><td><code>payscore/incomeVerification/started</code></td><td>Triggers when the applicant interacts with the workflow for the first time.</td></tr><tr><td><code>payscore/incomeVerification/institutionSelected</code></td><td>Triggers when an applicant selects a bank, payroll provider, or employer.</td></tr><tr><td><code>payscore/incomeVerification/institutionConnected</code></td><td>Triggers when an applicant successfully connects to their bank, payroll provider, or employer.</td></tr><tr><td><code>payscore/incomeVerification/loginAttempt</code></td><td>Triggers when an applicant attempts to login via bank or payroll provider</td></tr><tr><td><code>payscore/incomeVerification/loginAttemptFailed</code></td><td>Triggers when an attempted login fails. Most commonly seen with incorrect credentials, or an MFA challenge.<br><br>Bank login attempt failures include:<br>1. Incorrect credentials<br>2. Incorrect security answer<br>3. MFA challenge<br>4. Security questions expired<br>5. Account locked<br>6. Additional authorization required<br>7. User action required</td></tr><tr><td><code>payscore/incomeVerification/providerError</code></td><td>Triggers when an attempted login fails, or a connection to the provider cannot be made, for reasons outside of general login failure.  </td></tr><tr><td><code>payscore/incomeVerification/documentUploaded</code></td><td>Triggers when an applicant uploads a document.</td></tr><tr><td><code>payscore/incomeVerification/completed</code></td><td>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.</td></tr></tbody></table>

## 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:**

<table data-header-hidden><thead><tr><th>Event Type</th><th>Payload</th></tr></thead><tbody><tr><td><code>payscore/incomeVerification/institutionConnected</code></td><td><pre class="language-ts"><code class="lang-ts">{ 
  institution: string;
  method: IncomeVerificationMethod
}
</code></pre></td></tr><tr><td><code>payscore/incomeVerification/institutionSelected</code></td><td><pre><code>{ 
  institution: string;
  method: IncomeVerificationMethod
}
</code></pre></td></tr><tr><td><code>payscore/incomeVerification/loginAttempt</code></td><td><pre><code>{
  institution: string;
  method: IncomeVerificationMethod;
}
</code></pre></td></tr><tr><td><code>payscore/incomeVerification/loginAttemptFailed</code></td><td><pre><code>{
  institution: string;
  method: IncomeVerificationMethod;
}
</code></pre></td></tr><tr><td><code>payscore/incomeVerification/providerError</code></td><td><pre><code>{
  institution: string;
  method: IncomeVerificationMethod;
  errorMessage: string;
}
</code></pre></td></tr></tbody></table>

**Example:**

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