Link events are sent to your client (via the initializing callbacks) and will give you visibility into what is happening in the modal as the user moves through Pinwheel Link. It is up to you to determine how to use these events.

The onEvent callback is called with parameters (eventName: string, eventPayload: T) where T is the payload format corresponding to the event name found in this document below.

📘
Alternatively, you may use one of the specialized initialization callback parameters. These are convenient methods offering the same payloads as onEvent, but tailored for specific events.

Core Events

Link events inform you about user actions within the Pinwheel Link modal. It is up to you to determine how to use these events for tracking.

open

Modal was opened.

Payload

Empty object, {}.

exit

Modal was exited.

Payload (with error)

Key	Type	Description
`type`	string	Error type is the broad category of error. Read more here.
`code`	string	Error code is the specific error code. Read more here.
`message`	string	The error message shown to the end user.
`pendingRetry`	boolean	Sometimes jobs fail on the initial attempt. This field indicates if the job that has errored will be retried or not. Retries occur asynchronously and within 24 hours. The result of this retried job will be sent via a webhook.

Payload (without error)

Empty object, {}.

success

User reached the success screen. For direct deposit and card switch jobs, this will occur once for each job that completes successfully. For all other jobs this event will fire when the user logs in successfully, as these jobs are completed in the background.

Payload (SDK v3)

Key	Type	Description
`accountId`	string	The newly created uuid that signifies the relation between the user and the platform.
`platformId`	string	The uuid of the platform that the user uses.
`job`	string	Can be `'login'` or `direct_deposit_switch`. If you created a link token with only read jobs you will receive `'login'` here. This event means that the user has successfully logged in to their system and thus all read jobs will run subsequently asynchronously.* If your link token contains the job `direct_deposit_switch`, you will receive `'direct_deposit_switch'` here. This event means that the user has successfully switched their direct deposit to the specified account. Any read jobs contained in your link token will run subsequently asynchronously.* * Read job results may be retrieved via webhooks.
`params.action`	string	Optional. Only present if the link token has `direct_deposit_switch` and the user succeeds. Can be `full_switch` or `partial_switch`.
`params.allocation.type`	string	Optional. This key is only present when the `params.action` is `partial_switch`. Can be `remainder`, `amount`, or `percentage`.
`params.allocation.value`	integer	Optional. This key is only present when the `params.allocation.type` is `amount` or `percentage`.

Payload (SDK v2)

Key	Type	Description
`accountId`	string	The newly created uuid that signifies the relation between the user and the platform.
`platformId`	string	The uuid of the platform that the user uses.
`job`	string	Can be `'login'` or `direct_deposit_switch`. If the job is `login`, the user has successfully logged in to their system and thus all read jobs will run subsequently asynchronously. If the job is `direct_deposit_switch`, the user has successfully switched their direct deposit to the specified account.
`params.amount.value`	integer	Optional. Only present if the link token has `direct_deposit_switch` and the user succeeds. This is the value of the switch.
`params.amount.unit`	string	Optional. Only present if the link token has `direct_deposit_switch` and the user succeeds. The unit may be `"%"` or `"$"`.

error

User was shown an error. You can find more detail on Link errors and error handling here.

NOTE: Not all errors are terminal errors; e.g. a user may input incorrect credentials and still proceed.

Payload

Key	Type	Description
`type`	string	Error type is the broad category of error. Read more here.
`code`	string	Error code is the specific error code. Read more here.
`message`	string	The error message shown to the end user.
`pendingRetry`	boolean	Sometimes jobs fail on the initial attempt. This field indicates if the job that has errored will be retried or not. Retries occur asynchronously and within 24 hours. The result of this retried job will be sent via a webhook.

input_required

Indicates that user interaction is needed to continue the Link flow. This may include actions such as clicking a button, entering credentials, or providing additional input.

This event is primarily intended for analytics or custom implementations. In most cases, handling this event is not required for standard integration.

Payload

Empty object, {}.

Employer/Platform Events

These events give insight into the employer or platform selected by the user or customer.

For On Demand Updates these events are not sent since the account_id is already associated with a platform.

select_employer

User selected an employer.

For On Demand Updates this event is not sent since the account_id is already associated with a platform.

Payload

Key	Type	Description
`selectedEmployerId`	string	The uuid of the employer selected by the user in the search page.
`selectedEmployerName`	string	The name of the employer selected by the user in the search page.

select_platform

User selected a platform

Payload

Key	Type	Description
`selectedPlatformId`	string	The uuid of the platform selected by the user in the search page.
`selectedPlatformName`	string	The name of the platform selected by the user in the search page.

Login Events

These events give insight into user login actions.

login_attempt

User has submitted login attempt for the first time.

Payload

Key	Type	Description
`platformId`	string	The uuid of the platform that the user has attempted to log in to.

login

User logged in successfully.

Payload

Key	Type	Description
`platformId`	string	The uuid of the platform that the user has logged in to.
`accountId`	string	The newly created uuid that signifies the relation between the user and the platform.

merchant_login_success

For the Bill Switch and Switch Kit products only.

Payload

Key	Type	Description
`platformId`	string	The uuid of the platform that the user has logged in to.
`accountId`	string	The newly created uuid that signifies the relation between the user and the platform.

Direct Deposit Switch Events

These events give insight into the employer or platform selected by the user or customer.

input_allocation

User has submitted an allocation. Depending on the user's actions or your token creation parameters, you may receive a form of the payload described below.

Payload (SDK v3)

Key	Type	Description
`action`	string	Optional. Can be `full_switch` or `partial_switch`. May not be present for all platforms.
`allocation.type`	string	Optional. This key is only present when the `action` is `partial_switch`. Can be `remainder`, `amount`, or `percentage`.
`allocation.value`	integer	Optional. This key is only present when the `allocation.type` is `amount` or `percentage`.

Payload (SDK v2)

Key	Type	Description
`action`	string	Can be `full_switch` or `partial_switch`.
`allocation.type`	string	Optional. This key is only present when the `action` is `partial_switch`. Can be `remainder`, `amount`, or `percentage`.
`allocation.value`	integer	Optional. This key is only present when the `allocation.type` is `amount` or `percentage`.

input_amount (deprecated)

Not available in SDK version 3.

User inputted an amount. Note that this event is deprecated in favor of input_allocation, which provides more detail on what was input by the user.

Payload

Key	Type	Description
`value`	integer	The value of the switch.
`unit`	string	Either `'$'` or `'%'` if the switch was an amount switch or a percentage switch, respectively.

Document Uploads Events

These events give insight into manual document uploads.

doc_uploads_begin

User has started the doc uploads flow.

Payload

Empty object, {}.

doc_uploads_submitted

User has submitted documents for upload.

Payload

Key	Type	Description
`uploadedDocumentSubmittedCount`	integer	The number of documents submitted by the user.

Direct Deposit Form Events

dd_form_begin

User has begun the process to create a direct deposit form.

Payload

Empty object, {}.

dd_form_create

User has successfully created a direct deposit form, which is available at the returned URL.

Payload

Key	Type	Description
`url`	string	The URL of the generated direct deposit form.

dd_form_download

User has downloaded or shared the direct deposit form PDF.

Payload

Empty object, {}.

Bill Switch Events

The following events will only be emitted when using one of the Bill Switch products: Switch Kit or Bill Switch.

external_account_connected

User has connected one of their external bank accounts in order to find bills currently being charged to that account.

Key	Type	Description
`institutionName`	string	The name of the institution (eg bank, fintech, credit union, etc.) that the user connected to.
`accountName`	string	The name of the account they connected.

bill_switch_success

User has successfully switched a bill with a merchant.

Payload

Key	Type	Description
`platformId`	string	The uuid of the platform that the user has switched a bill with.
`platformName`	string	The name of the merchant that the user switched a bill with.
`isGuidedSwitch`	boolean	Whether the merchant integration was a one-click integration (false) or a guided integration (true).
`frequency`	string	One of: `weekly`, `bi-weekly`, `monthly`, `bi-monthly`, `quarterly`, `semi-yearly`, `yearly`, or `other`
`nextPaymentDate`	string	An ISO-formatted date string that indicates the next expected bill date. If the frequency is `other`, this will be an empty string.
`amountCents`	integer	The amount of the bill that got switched, denoted in cents. So a `$19.99` bill would be `1999`.

bill_removed

User has opted to remove a bill from their bill list.

Payload

Key	Type	Description
`platformId`	string	The uuid of the platform that the user has removed from their bill list.
`platformName`	string	The name of the merchant that the user has removed from their bill list.
`isGuidedSwitch`	boolean	Always `false`.
`frequency`	string	One of: `weekly`, `bi-weekly`, `monthly`, `bi-monthly`, `quarterly`, `semi-yearly`, `yearly`, or `other`
`nextPaymentDate`	string	An ISO-formatted date string that indicates the next expected bill date. If the frequency is `other`, this will be an empty string.
`amountCents`	integer	The amount of the bill that got removed, denoted in cents. So a `$19.99` bill would be `1999`.

Navigation Events

screen_transition

User has transitioned to a new screen within the modal.

Payload

Key	Type	Description
`screen_name`	string	The name of the screen that was encountered. See options for this key below.
`selectedEmployerId`	string	Optional. Only available if the `screen_name` is `"LOGIN"` or `"MANUAL_INSTRUCTIONS"`. The uuid of the selected employer.
`selectedEmployerName`	string	Optional. Only available if the `screen_name` is `"LOGIN"` or `"MANUAL_INSTRUCTIONS"`. The name of the selected employer.
`selectedPlatformId`	string	Optional. Only available if the `screen_name` is `"LOGIN"` or `"MANUAL_INSTRUCTIONS"`. The uuid of the selected platform.
`selectedPlatformName`	string	Optional. Only available if the `screen_name` is `"LOGIN"` or `"MANUAL_INSTRUCTIONS"`. The name of the selected platform.

See options for screen_name below.

Screen Names

Note that all possible screens are not captured below. New screens may be added and your code should handle it.

`screen_name`	Description
`SEARCH_DEFAULT`	Default search screen after the initial intro page.
`SEARCH_RESULTS`	Results screen when the user starts a search from the `SEARCH_DEFAULT` screen.
`SEARCH_PLATFORM_ONLY`	From the `SEARCH_RESULTS` screen, the user is able to search through a list filtered for platforms only.
`PROVIDER_CONFIRMATION`	Provider confirmation screen. When some employers or platforms (e.g. Workday) are initially selected, the user is prompted to then confirm their specific employer/platform before logging in.
`LOGIN`	Login screen once the user has selected a platform or employer from search. [Bill Switch] also fires when a user selects a merchant to switch their bill and lands on the screen to login to that merchant.
`DD_AMOUNT_SELECTION`	Direct deposit amount selection screen after the user has successfully logged in.
`DD_CONFIRMATION`	Confirmation screen before a direct deposit switch is performed.
`JOB_SUCCESS`	Job success screen (e.g. direct deposit switch succeeded).
`JOB_ERROR`	Job error screen (e.g. direct deposit switch failed).
`MANUAL_INSTRUCTIONS`	Screen that provides users with manual instructions for updating their direct deposit.
`BILL_SWITCH_INTRO`	The intro/get started screen for the Bill Switch products.
`BILL_SWITCH_ACCOUNTS`	The Bill Switch screen that lists all the user's connected accounts.
`BILL_SWITCH_MERCHANT_LIST`	The Bill Switch screen that shows all the user's detected bills from their accounts.
`BILL_SWITCH_MERCHANT`	The Bill Switch screen that shows a particular merchant with options to initiate a switch.
`PLAID_MODAL`	[Bill Switch products only] User opened the Plaid modal to connect accounts.
`RECURRENCES_FOUND`	The Bill Switch screen that shows the user that Pinwheel has found recurring bills in their connected accounts that they can switch.
`BILL_SWITCH_MANUAL`	The Bill Switch screen that shows the user how to switch a bill manually, also known as a guided bill switch.
`BILL_SWITCH_PAYMENT_METHOD`	The Bill Switch screen that lets the user pick their payment method (if multiple options were provided via the Link Token).
`BILL_SWITCH_TRANSACTIONS`	The Bill Switch screen that shows the user all the transactions registered for a particular bill they've selected.
`BILL_SWITCH_SUCCESS`	The screen that shows after a successful bill switch.
`BILL_SWITCH_FAILURE`	The screen that shows after a bill switch was unsuccessful.
`EXIT_CONFIRMATION`	Exit confirmation screen when the user presses the modal close button.

Other Events

other_event

We periodically test new events that will appear as other_event. These are typically experimental in nature and may change in the future, so they're safe to ignore. If you have any feedback or requests for new Link events, please let us know!