Bridge Events

Truv Bridge emits client-side events during the user’s connection flow. These are JavaScript callbacks configured when you initialize TruvBridge.init(). They are distinct from server-side webhook events.

Callbacks: Responses for specific Truv Bridge actions
Event data: onEvent types and their payload shapes
Errors: Bridge error objects, types, and codes

Callbacks

const bridge = TruvBridge.init({
  bridgeToken: bridgeToken,
  onSuccess(publicToken, metadata) {},  // required
  onLoad() {},                          // optional
  onEvent(type, payload) {},            // optional
  onClose() {},                         // optional
})

Callback	Required	Description
`onSuccess`	Required	User successfully connected to a payroll provider and closed Bridge. Receives `publicToken` and a `metadata` object.
`onLoad`	Optional	Truv Bridge finished loading.
`onEvent`	Optional	A specific event occurred within Bridge. See Event data for all types.
`onClose`	Optional	Truv Bridge was closed by the user.

The Embedded Orders flow uses a different callback signature. See Embedded Orders for the correct initialization pattern when using isOrder: true.

Event data

onEvent Types

Event Type	Payload	Description
`LOAD`	None	Bridge module finished loading
`OPEN`	`CommonEventData`	Bridge is ready and visible
`SCREEN_VIEW`	`ScreenViewData`	A Bridge screen was viewed
`EMPLOYER_SELECTED`	`EmployerSelectedData`	Employer or provider selected
`DOC_UPLOAD_OPENED`	`CommonEventData`	Document upload screen opened
`DOCUMENTS_UPLOADED`	`DocumentsUploadedData`	Specific document types uploaded
`LINK_CREATED`	`TaskData`	User logging in as a new Link
`LOGIN_COMPLETE`	`TaskData`	User successfully logged in
`SUCCESS`	`TaskData`	Data successfully retrieved
`ERROR`	`ErrorData`	Error during connection process
`UNSUPPORTED_BROWSER`	None	Browser is not supported
`CLOSE`	`CloseData`	Bridge was closed
`MANUAL_DDS`	`ManualDDSData`	Manual Direct Deposit Switch (DDS) operation submitted
`OAUTH_OPENED`	`OAuthEventData`	User redirected to OAuth login (assets/transactions only)

CommonEventData

Present on OPEN and DOC_UPLOAD_OPENED events.

Field	Type	Description
`bridge_token`	string	The `bridge_token` passed to `TruvBridge.init`
`product_type`	string	Product type (`income`, `employment`, `assets`, etc.). May be `undefined` if token is expired.
`data_source`	string	Underlying data source: `payroll`, `docs`, `financial_accounts`, `tax`, or `insurance`

{
  "bridge_token": "b5cb1933e43043a792a9b337af5824e2",
  "product_type": "income",
  "data_source": "payroll"
}

ScreenViewData

Field	Type	Description
`view_name`	string	Screen viewed: `SELECT_EMPLOYER`, `PROVIDER_LIST`, `PROVIDER_LOGIN`, `PROVIDER_ORG_ID`, `ERROR`, `SUCCESS`, `DOC_UPLOAD`, `DOC_UPLOAD_TYPES`
`bridge_token`	string	The `bridge_token` passed to `TruvBridge.init`
`product_type`	string	Product type
`doc_type`	string	Applicable only for `DOC_UPLOAD`: `paystub`, `w2`, or `f1099`
`data_source`	string	Underlying data source: `payroll`, `docs`, `financial_accounts`, `tax`, `scoring_attributes`, or `insurance`

{
  "view_name": "PROVIDER_LOGIN",
  "bridge_token": "b5cb1933e43043a792a9b337af5824e2",
  "product_type": "income",
  "data_source": "payroll"
}

EmployerSelectedData

Field	Type	Description
`bridge_token`	string	The `bridge_token` passed to `TruvBridge.init`
`product_type`	string	Product type
`employer`	object	Employer object with `name` property. `null` if none selected.
`provider`	string	ID of the selected provider. `null` if none selected.
`data_source`	string	Underlying data source

{
  "bridge_token": "b5cb1933e43043a792a9b337af5824e2",
  "product_type": "income",
  "employer": { "name": "Acme Corp" },
  "provider": "workday",
  "data_source": "payroll"
}

DocumentsUploadedData

Field	Type	Description
`bridge_token`	string	The `bridge_token` passed to `TruvBridge.init`
`product_type`	string	Product type
`doc_type`	string	Type of document uploaded: `paystub`, `w2`, or `f1099`
`data_source`	string	Always `docs` for document upload events

{
  "bridge_token": "b5cb1933e43043a792a9b337af5824e2",
  "product_type": "income",
  "doc_type": "paystub",
  "data_source": "docs"
}

TaskData

Present on LINK_CREATED, LOGIN_COMPLETE, and SUCCESS events.

Field	Type	Description
`public_token`	string	Exchange for `access_token` on your server
`task_id`	string	Unique task identifier. Include in support tickets.
`bridge_token`	string	The `bridge_token` passed to `TruvBridge.init`
`product_type`	string	Product type
`employer`	object	Employer data object. May be `undefined` for `admin` product type.
`provider_id`	string	Unique identifier for the selected provider
`data_source`	string	Underlying data source

{
  "public_token": "d80ec8255dc54c5eb7cc03ac05d18ebd",
  "task_id": "2b0e7a7dec1d47678fec4e02af621cc0",
  "bridge_token": "b5cb1933e43043a792a9b337af5824e2",
  "product_type": "income",
  "provider_id": "adp",
  "employer": { "name": "Acme Corp" },
  "data_source": "payroll"
}

ErrorData

Field	Type	Description
`error`	object	Error object. See Errors.
`public_token`	string	Associated `public_token`. Only present if error is tied to a specific connection attempt.
`task_id`	string	Task identifier. Include in support tickets.
`bridge_token`	string	The `bridge_token` passed to `TruvBridge.init`
`product_type`	string	Product type
`data_source`	string	Underlying data source

{
  "error": {
    "error_code": "LOGIN_ERROR",
    "error_message": "Username or password is incorrect",
    "error_type": "LINK_ERROR"
  },
  "task_id": "5ad1938450c54024bbc967a3a7dc9020",
  "bridge_token": "b5cb1933e43043a792a9b337af5824e2",
  "product_type": "income",
  "data_source": "payroll"
}

CloseData

Field	Type	Description
`employer`	object	Employer selected before closing. `undefined` if no employer was chosen.

{
  "employer": { "name": "Acme Corp" }
}

ManualDDSData

Field	Type	Description
`action`	string	Operation type: `EMAIL`, `DOWNLOAD`, `SHARE`, or `EXTERNAL_FLOW`
`depositType`	string	Deposit type selected: `entire`, `percent`, or `amount`. Not present for `EXTERNAL_FLOW`.

{
  "depositType": "entire",
  "action": "EMAIL"
}

OAuthEventData

Field	Type	Description
`bridge_token`	string	The `bridge_token` passed to `TruvBridge.init`
`product_type`	string	Product type
`task_id`	string	Task identifier
`provider_id`	string	Unique identifier for the selected provider
`url`	string	OAuth URL the user is redirected to

{
  "bridge_token": "b5cb1933e43043a792a9b337af5824e2",
  "product_type": "assets",
  "provider_id": "truv_bank_oauth",
  "task_id": "5ad1938450c54024bbc967a3a7dc9020",
  "url": "https://www.truv.com/oauth-login.html?..."
}

Errors

{
  "error": {
    "error_code": "LOGIN_ERROR",
    "error_message": "Username or password is incorrect",
    "error_type": "LINK_ERROR"
  }
}

Design your UX to surface login errors to borrowers in real time. When onEvent fires with type ERROR and error_code: LOGIN_ERROR, prompt the user to re-enter their credentials rather than silently failing.

Error Object

Field	Type	Description
`error_type`	string	Category of error
`error_code`	string	Specific error code
`error_message`	string	Human-readable description

Error Types

Type	Description
`LINK_ERROR`	Generic link-level error

Error Codes

Code	Description
`ERROR`	Generic error occurred
`LINK_EXISTS`	User’s account is already connected
`LOGIN_ERROR`	Incorrect username, password, or both
`MFA_ERROR`	Invalid MFA input
`NO_DATA`	User account has no data available
`UNAVAILABLE`	Payroll provider is unreachable

Route errors to manual fallback

When Bridge encounters an error, intercept it client-side and route the user to a manual verification workflow instead of dead-ending the experience.

Detect the error. Register an onEvent callback when initializing Truv Bridge. When onEvent fires with type ERROR, inspect the error_code in the payload.
Close Bridge. After capturing the error details, close the Bridge widget programmatically or wait for the user to close it via onClose.
Route to fallback. Based on the error type, redirect the user to your manual process — document upload, paper form submission, or a support contact flow.

`error_code`	Meaning	Recommended fallback
`LOGIN_ERROR`	Incorrect credentials	Prompt the user to retry. After repeated failures, offer document upload.
`MFA_ERROR`	Invalid MFA input	Prompt the user to retry. After repeated failures, offer document upload.
`UNAVAILABLE`	Payroll provider is unreachable	Route directly to document upload or manual process. The provider outage is not user-fixable.
`NO_DATA`	Account has no data	Route to document upload. The connected account lacks the required records.
`ERROR`	Generic error	Log the `task_id` for debugging. Offer document upload as a fallback.

Track which error_code values trigger manual fallbacks in your analytics. A high rate of UNAVAILABLE errors for a specific provider may indicate a temporary outage, while frequent LOGIN_ERROR events may point to a UX issue in your credential entry flow.

Bridge errors are client-side events, distinct from server-side webhook events and task status changes. Use both in combination: Bridge onEvent for real-time UX routing, and webhooks for backend workflow orchestration.

Next steps

SDKs & Libraries

Install Truv Bridge for web and mobile

Task Events

Server-side event reference for task and data-object events

Connection Lifecycle

Task status flow referenced by Bridge events

Deeplinking

Skip employer search to improve conversion

​Callbacks

​Event data

​onEvent Types

​CommonEventData

​ScreenViewData

​EmployerSelectedData

​DocumentsUploadedData

​TaskData

​ErrorData

​CloseData

​ManualDDSData

​OAuthEventData

​Errors

​Error Object

​Error Types

​Error Codes

​Route errors to manual fallback

​Next steps

SDKs & Libraries

Task Events

Connection Lifecycle

Deeplinking

Callbacks

Event data

onEvent Types

CommonEventData

ScreenViewData

EmployerSelectedData

DocumentsUploadedData

TaskData

ErrorData

CloseData

ManualDDSData

OAuthEventData

Errors

Error Object

Error Types

Error Codes

Route errors to manual fallback

Next steps