Payroll Income

Payroll Income (US only) 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.

1. Call /user/create to create a user_token that 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.
2. Call /link/token/create. In addition to the required parameters, you will need to provide the following:
   • For user_token, provide the user_token from /user/create.
   • For products, use ["income_verification"]. Document Income cannot be used in the same Link session as any other Plaid products, except for Payroll Income.
   • For income_verification.income_source_types, use payroll.
   • (Optional) If you are only using Payroll Income and do not want customers to use Document Income, for income_verification.payroll_income.flow_types, use ["payroll_digital_income"].
   • Provide a webhook URI with the endpoint where you will receive Plaid webhooks.
3. On the client side, create an instance of Link using the link_token returned by /link/token/create; for more details, see Link.
4. Open Link in your web or mobile client and listen to the onSuccess and onExit callbacks, which will fire once the user has finished or exited the Link session.
5. Listen for the INCOME: INCOME_VERIFICATION webhook, which will fire within a few seconds, indicating that the Income data is ready.
6. Call /credit/payroll_income/get for income data, and/or /credit/employment/get for employment details.

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 is successful, you will receive an INCOME_VERIFICATION webhook. The next time you call /credit/payroll_income/get, you will receive updated data.

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.

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 download_url.

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. View an example generated pay stub.

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.

/credit/payroll_income/get can optionally be tested in Sandbox without using Link. Call /user/create, pass the returned user_token to /sandbox/public_token/create (use ins_135842 when creating a public token for Payroll 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.

Payroll Income does not currently support the use of custom Sandbox data; only the default user_good user is compatible with Sandbox Payroll Income.

Payroll Income is billed on a one-time fee model. Payroll Income Refresh is billed on a per-request fee model. To view the exact pricing you may be eligible for, apply for Production access or contact Sales. For more details about pricing and billing models, see Plaid billing.

If you're ready to launch to Production, see the Launch checklist.