Learn about Payroll Income features and implementation
View Income requests, responses, and example code
View the starter Income sample app and code
Payroll Income allows you to instantly verify employment details and gross income information, including the information available on a pay stub, from a user-connected payroll account. Payroll Income supports approximately 80% of the US workforce, including gig income workers.
/user/createto create a
user_tokenthat will represent the end user interacting with your application. This step will only need to be done once per end user. If you are using multiple Income types, do not repeat this step when switching to a different Income type.
/link/token/create. In addition to the required parameters, you will need to provide the following:
user_token, provide the
["income_verification"]. Document Income cannot be used in the same Link session as any other Plaid products, except for Payroll Income.
- (Optional) If you are only using Payroll Income and do not want customers to use Document Income,
- Provide a
webhookURI with the endpoint where you will receive Plaid webhooks.
- On the client side, create an instance of Link using the
/link/token/create; for more details, see Link.
- Open Link in your web or mobile client and listen to the
onExitcallbacks, which will fire once the user has finished or exited the Link session.
- Listen for the
INCOME: INCOME_VERIFICATIONwebhook, which will fire within a few seconds, indicating that the Income data is ready.
/credit/payroll_income/getfor income data, and/or
/credit/employment/getfor employment details.
Payroll Income Refresh (beta)
Payroll Income Refresh is currently in closed beta. To request access, contact your account manager.
On-demand Payroll Income Refresh allows you to request updated information from a previously connected payroll account.
To trigger a refresh, call
/credit/payroll_income/refresh and specify the
user_token to refresh.
If the refresh was not successful, you will receive a
INCOME_VERIFICATION_REFRESH_RECONNECT_NEEDED webhook. To resolve this failure state, send the user through update mode. The refresh attempt will automatically be retried once the user has completed update mode, and an
INCOME_VERIFICATION webhook will be sent if the retry is successful.
Download original documents
To download PDF versions of the original payroll documents that were parsed to obtain payroll data, use the
document_metadata.download_url returned by
/credit/payroll_income/get. Not all integrations will return a
In cases where an original source cannot be obtained, Plaid can optionally generate a PDF pay stub based on the data obtained. To enable Plaid-generated PDF pay stubs, contact your account manager.
Plaid provides employment data via the
/credit/employment/get endpoint. If you are on a Pay-as-you-go or Growth plan and want to use this endpoint, contact support to request access.
Testing Payroll Income
Income can be tested in Sandbox against test data without contacting Plaid. In order to test Income against live Items in either Development or Production, you will need to first request access by submitting a product access request Support ticket explaining your use case.
/credit/payroll_income/get can optionally be tested in Sandbox without using Link. Call
/user/create, pass the returned
ins_90 is a good sample
institution_id for testing Income in Sandbox), and then call
/credit/payroll_income/get. The output of
/sandbox/public_token/create will not be used, but calling it initializes the user token for testing.
If you're ready to launch to Production, see the Launch checklist.