Payroll Income 
===============

#### Learn about Payroll Income features and implementation 

Get started with Payroll Income

[API Reference](https://plaid.com/docs/api/products/income/index.html.md) [Quickstart](https://github.com/plaid/income-sample)

#### Overview 

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.

[Prefer to learn by watching? Get an overview of how Income works in just 3 minutes!](https://www.youtube.com/watch?v=Hc-MpibSxJE)

#### Integration process 

1.  Call [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) 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](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . In addition to the required parameters, you will need to provide the following:
    *   For `user_token`, provide the `user_token` from [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) .
    *   For `products`, use `["income_verification"]`. Payroll Income cannot be used in the same Link session as any other Plaid products, except for Document Income (which may be offered as a fallback when a payroll provider is not supported).
    *   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](https://plaid.com/docs/api/link/index.html.md#linktokencreate) ; for more details, see [Link](https://plaid.com/docs/link/index.html.md) .
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](https://plaid.com/docs/api/products/income/index.html.md#income_verification) webhook, which will fire within a few seconds, indicating that the Income data is ready.
6.  Call [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) for income data, and/or [/credit/employment/get](https://plaid.com/docs/api/products/income/index.html.md#creditemploymentget) for employment details.

#### Payroll Income Refresh 

To request access to Payroll Income Refresh, 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](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerefresh) and specify the `user_token` to refresh.

If the refresh is successful, you will receive an [INCOME\_VERIFICATION](https://plaid.com/docs/api/products/income/index.html.md#income_verification) webhook. The next time you call [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) , you will receive updated data.

If the refresh was not successful, you will receive an [INCOME\_VERIFICATION\_REFRESH\_RECONNECT\_NEEDED](https://plaid.com/docs/api/products/income/index.html.md#income_verification_refresh_reconnect_needed) webhook. To resolve this failure state, send the user through [update mode](https://plaid.com/docs/link/update-mode/index.html.md) . The refresh attempt will automatically be retried once the user has completed update mode, and an [INCOME\_VERIFICATION](https://plaid.com/docs/api/products/income/index.html.md#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](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) . 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](https://plaid.com/documents/plaid-generated-mock-paystub.pdf) .

#### Employment data 

Plaid provides employment data via the [/credit/employment/get](https://plaid.com/docs/api/products/income/index.html.md#creditemploymentget) 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 

You can test Payroll Income in Sandbox using Link. For best results, select a payment provider that only requests a username, password, and/or SSN. (Good examples are Paycom, Paychex, or Workday.) Use `test-good` as the username, `test` as the password, and `1234` as the last 4 digits of your SSN.

You can also see an example Link flow for Payroll Income using the [Plaid Link demo site](https://plaid.com/link-demo/) : select "Payroll and Document Income" from the drop-down and use the credentials above.

[/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) can optionally be tested in Sandbox without using Link. Call [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) , pass the returned `user_token` to [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) (use `ins_135842` when creating a public token for Payroll Income in Sandbox), and then call [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) . The output of [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) 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 pricing 

Payroll Income is billed on a [one-time fee model](https://plaid.com/docs/account/billing/index.html.md#one-time-fee) . Payroll Income Refresh is billed on a [per-request fee model](https://plaid.com/docs/account/billing/index.html.md#per-request-flat-fee) . To view the exact pricing you may be eligible for, [apply for Production access](https://dashboard.plaid.com/overview/production) or [contact sales](https://plaid.com/contact/) . For more details about pricing and billing models, see [Plaid billing](https://plaid.com/docs/account/billing/index.html.md) .

#### Next steps 

If you're ready to launch to Production, see the [Launch checklist](https://plaid.com/docs/launch-checklist/index.html.md) .

#### Launch Center 

See next steps to launch in Production

[Launch](https://dashboard.plaid.com/developers/launch-center)