Introduction to Income
Verify income and paystubs with Income.
View Income requests, responses, and example code
View Income error codes and troubleshooting guides
Plaid Income (currently US only) helps you verify anyone's income and employment in seconds, facilitating an improved decisioning and underwriting process. You can verify a user's income via three products:
Payroll Income: Retrieve income information from a user-connected payroll account.
Document Income: Retrieve income information via a user-uploaded documents such as a pay stub or W-2 form.
Bank Income: Retrieve income information from a user-connected bank account.
Income is configurable, allowing you to choose at the time of connection which income verification method best suits your user’s needs. The Document Income solution is a natural fallback to the Payroll Income solution, but you are also able to mix and match income verification methods.
Depending on your use case, you may want to enable different income verification methods. For instance, if your use case relies on net income or income deposited in a user’s bank account, you can leverage Bank Income. Additionally, if you plan to use other Plaid products, such as Auth and Balance for payments, you can use Bank Income to verify income in a single Link experience, without requiring your user to go through multiple flows. For use cases that require gross income verification, you may want to use both Payroll and Document Income.
|Method||Data source||Processing time||Income supported||Integrates w/other Plaid APIs|
|Bank Income||User logs in to bank account||Instant||Net / gross (W2, self-employment, gig, multi-stream)||Yes|
|Payroll Income||User logs in to payroll provider||Instant||~80% of US workforce (both W2 and gig)||No|
|Document Income||User uploads W2 or pay stubs||~15 min||Any W2 or pay stub income||No|
Income integration process
/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.
- (Optional) Call
user_token. This endpoint will indicate Plaid's confidence that a user will be able to complete the Payroll Income flow and can increase conversion by customizing the Payroll flow in Link for the specific user. For users where the endpoint returns a low confidence in their ability to connect via Payroll Income, we recommend you launch Link with either Document Income or Bank Income instead.
/link/token/create. In addition to the required parameters, you will need to provide the following:
user_token, provide the
["income_verification"]. If using Bank Income, you can also specify additional products.
income_verification.income_source_types, use either
payroll(for Payroll and Document Income) or
bank(for Bank Income). You can further customize the flows enabled and the amount of data collected via optional parameters; see the API Reference for more details.
- Provide a
webhookURI with the endpoint where you will receive Plaid webhooks.
- If you collect income information directly from your users, provide it in the
income_verification.stated_income_sourcesparameter. This data is used to improve the accuracy of data sent back to you, such as income stream categories.
- On the client side, create an instance of Link using the
/link/token/create; for more details, see the Link documentation.
- When the user has successfully completed the client-side Link flow, you will be alerted in one of two ways:
- If using Bank Income, listen for the client-side
BANK_INCOME_INSIGHTS_COMPLETEDLink event that occurs after
onSuccess. This event indicates that a user has completed the full Bank Income flow. If you are using other Plaid products such as Auth or Balance alongside Bank Income, make sure to capture the
onSuccesscallback and exchange it for an
access_token. For more details on token exchange flows, see the Token exchange flow.
- If using Payroll or Document Income, listen for the
INCOME: INCOME_VERIFICATIONwebhook. For more details, see Income webhooks.
- If using Bank Income, listen for the client-side
- To retrieve data, call the credit endpoints using the
When using Payroll or Document Income, Plaid will asynchronously process the income data and send an
INCOME: INCOME_VERIFICATION webhook once processing is complete. If processing was successful, the webhook's
verification_status value will be
VERIFICATION_STATUS_PROCESSING_COMPLETE. If you attempt to retrieve the income data before it has been processed, you may receive a 400 response with the error code
PRODUCT_NOT_READY. Awaiting the webhook before calling
/credit/payroll_income/get is strongly recommended.
Processing will usually complete within a few seconds if the user's income was verified via Payroll Income. If the user verified their income via Document Income, processing may take up to 45 minutes.
When using Bank Income, no webhooks are sent; data will be available as soon as the
BANK_INCOME_INSIGHTS_COMPLETED event has been emitted by Link.
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.
In the Sandbox environment, when testing Document Income, the contents of the actual document will not be processed and Sandbox will instead use pre-populated test data. This data will be available immediately. To test that your application properly handles the real-world delayed processing behavior of Document Income, test in the Development environment.
/credit/payroll_income/get can optionally be tested in Sandbox without using Link. Call
/user/create, pass the returned
/sandbox/public_token/create, and then call
/credit/payroll_income/get. The output of
/sandbox/public_token/create will not be used, but calling it intializes the user token for testing.
To test the
/credit/payroll_income/precheck endpoint in Sandbox, use test employer objects with the employer names
employer_bad, to generate
LOW confidence scores.
employer_multi can be used to generate a
HIGH confidence score with multiple payroll options. Any other employer will result in an
UNKNOWN confidence score. Likewise, use the test access tokens
access_bad to generate
LOW confidence scores. Any other access token will result in an
UNKNOWN confidence score.
Testing Bank Income
Bank Income cannot be tested via
/sandbox/public_token/create; you must use the Link flow instead.
To help you test Bank Income, Plaid provides a test JSON configuration object. To load this data into Sandbox, update the JSON object so that all transaction dates are within the past 90 days (Bank Income only reviews transactions from the past 90 days) and then copy and paste the JSON into the Sandbox Users pane in the Dashboard. For more information on configuring custom Sandbox data, see Configuring the custom user account.
Enabling multi-Item sessions for Bank Income
Many users get income deposited into multiple institutions. To help capture a user’s full income profile, you can allow your users to link multiple accounts within the same link session on web integrations.
To enable this flow:
- When calling
- Pass in the
onResultcallback to the Link Web SDK
Every time the user successfully links an Item by authenticating their account, you will receive an
item_add_result through the
onResult callback. The
onResult callback will be fired once for every added Item, while the
onSuccess callback will fire for the final added Item, indicating that the user has exited Link.
While you can access Bank Income data with the
user_token, if you are planning to leverage these account connections for other Plaid products (such as Auth, Balance, etc) you should make sure to process the output of the
onResult callback, by exchanging the provided
public_token for an
Sample app code
For an example of an app that incorporates Income, see the React and NodeJS-based Income Sample app. This application uses Income and Liability data to help determine whether the user can qualify for financing on a pre-owned hoverboard. It supports the use of Payroll, Document, and Bank Income data.
If you're ready to launch to Production, see the Launch checklist.