Payroll Income Verification
Note
For implementations using Truv Order functionality, refer to the Verification using Truv Orders documentation.
Overview
Payroll Income allows you to instantly verify employment details and income information, including the information available on a paystub, from a user-connected payroll account. Payroll Income supports approximately 90% of the US workforce, including gig income workers.
Integration Process
-
Create User Token
Call/user/
to create auser_id
that will represent the end user interacting with your application. This step only needs to be done once per end user. If you are using multiple Income data sources, do not repeat this step when switching to a different Income data source. -
Generate a Bridge Token
Call/users/{user_id}/tokens/
with the following parameters:user_id
: Provide the user_id from /user/ .product_type
: Use"income"
.data_sources
: Specify["payroll"]
to connect exclusively to payroll. To enable fallback options, include additionaldata_sources
such as"docs"
and/or"financial_accounts"
in the list.Note
When including
"docs"
in thedata_sources
, the first and last name must be completed when creating theuser_id
in step 1.- (Optional)
tracking_info
: To add a unique identifier from an internal system to identify a Truv transaction, enter it in the provided field.
-
Client-Side Setup
On the client side, create an instance of the Truv Bridge using thebridge_token
. For more details, see Implementing Truv Bridge. -
Callbacks
Listen to theonSuccess
andonEvent
callbacks, which will trigger once the user completes the Truv Bridge session. More info here. -
Listen for Webhooks
Listen for thetask-status-updated
webhook, which provides the status of the login attempt and indicates when the data is ready to be retrieved once thestatus
is set todone
. Thedata_source
will specify the income source of the task. Use theuser_id
andlink_id
to trigger the corresponding income information retrieval. More info here. -
Retrieve Income and/or Employment Data
Call/users/{user_id}/reports/
for user-specific report,/links/{link_id}/income/report/
for link specific income details or/links/{link_id}/employment/report/
for employment-only details.
Note
To obtain a user-specific report in PDF format, append the
?fmt=pdf
suffix when accessing the report using theuser_id
and thereport_id
. Thereport_id
is provided when the user-specific report is created.
Payroll Income Refresh
On-demand Payroll Income Refresh enables the request for updated information from a previously connected payroll account.
To trigger a refresh, call /refresh/tasks/
and specify the access_token
of the original successful connection to refresh.
- If the refresh is successful, a
task-status-updated
webhook with"status": "done"
will be received. The next time/links/{link_id}/income/report/
or/users/{user_id}/reports/
is called, updated data will be provided. - If the refresh is unsuccessful, a
task-status-updated
webhook with a status indicating a Task error will be received.- To resolve this failure state, send the user through a Refresh Truv Bridge via
/users/{user_id}/tokens/
by including theaccess_token
. Once the user completes the Refresh process, and atask-status-updated
webhook with a"status": "done"
will be sent if the retry is successful.
- To resolve this failure state, send the user through a Refresh Truv Bridge via
Download Original Documents
To download PDF versions of the original payroll documents that were parsed when obtaining payroll data, use the "file"
attribute returned by /links/{link_id}/income/report/
or /users/{user_id}/reports/
. The "file"
attribute can be found inside the statements
and w2s
objects. Truv returns all PDFs provided by the payroll system.
Testing Payroll Income
Income can be tested in Sandbox using Truv's Testing credentials. Here are some login examples:
- Happy path: username:
goodlogin
, password:goodpassword
, SSN:991-91-9991
- Login Error: username:
error.user
, password:login_error
- Multiple employers: username:
multiple.employments
, password:goodpassword
Next Steps
If you're ready to launch to Production, see the Launch checklist.
Updated 5 months ago