Plaid logo
Docs
ALL DOCS

Income

  • Introduction to Income
  • Bank Income
  • Document Income
  • Payroll Income
  • Add Income to your app
Plaid logo
Docs
Close search modal
Ask Bill!
Ask Bill!
Hi! I'm Bill! You can ask me all about the Plaid API. Try asking questions like:
  • How do I set up a webhook for IDV?
  • What's the difference between an Item and an access token?
  • Do access tokens expire?
Note: Bill isn't perfect. He's just a robot platypus that reads our docs for fun. You should treat his answers with the same healthy skepticism you might treat any other answer on the internet. This chat may be logged for quality and training purposes. Please don't send Bill any PII -- he's scared of intimacy. All chats with Bill are subject to Plaid's Privacy Policy.
Plaid.com
Log in
Get API Keys
Open nav

Bank Income

Learn about Bank Income features and implementation

Get started with Bank Income
API ReferenceQuickstartIncome Verification Demo

Overview

Bank Income allows you to instantly retrieve net income information from a user-connected bank account, supporting both irregular or gig income and W-2 income. Data available includes a breakdown of income streams to the account, as well as recent and historical income.

Prefer to learn by watching? Get an overview of how Income works in just 3 minutes!

No-code Income integration with the Credit Dashboard

Bank Income can be used as part of a no-code integration flow. This integration mode is available only when using Income alongside Assets. For more details, see the Assets no-code integration guide.

Integration process

  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"]. You can also specify additional products. For more details, see Using Bank Income with other products.
    • For income_verification.income_source_types, use bank.
    • Set income_verification.bank_income.days_requested to the desired number of days.
    • 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 the Link documentation.
  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. If you are using other Plaid products such as Auth or Balance alongside Bank Income, call /link/token/get and make sure to capture each public_token from the results.item_add_results array. Exchange each public_token for an access_token using /item/public_token/exchange. For more details on token exchange, see the Token exchange flow.
  6. To retrieve data, call /credit/bank_income/get with the user_token.

Multi-Item sessions

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.

Bank Income Multi Item flow
Bank Income Multi Item Link flow

To enable this flow, see Multi-Item Link. The previous Income-specific flow, which used the income_verification.bank_income.enable_multiple_items setting in /link/token/create and obtained public tokens from the /credit/sessions/get endpoint, has been deprecated and replaced with a generic Multi-Item Link flow that supports all Plaid and Plaid Check products.

Using Bank Income with other products

Bank Income Items are fully compatible with other Plaid Item-based products, including Auth, Transactions, Balance, and Assets.

When initializing Link, if you plan to use Bank Income and Assets in the same session, it is recommended to put both income_verification and assets in the /link/token/create products array. If you plan to use Bank Income with Transactions, you should not put transactions in the products array, as this may increase latency. For more details, see Choosing how to initialize Link.

To capture an access_token for use with other products, call /credit/sessions/get after receiving the onExit or onSuccess callback from Link. This endpoint will return all public_tokens for every Item linked to a given user_token. For details on the API schema, see the /credit/sessions/get documentation. You can then exchange these public_tokens for access_tokens using /item/public_token/exchange.

Verifying Bank Income for existing Items

If your user has already connected their depository bank account to your application for a different product, you can add Bank Income to the existing Item via update mode.

To do so, in the /link/token/create request described above, populate the access_token field with the access token for the Item. If the user connected their account less than two years ago, they can bypass the Link credentials pane and complete just the Income Verification step. Otherwise, they will be prompted to complete the full Plaid Bank Income Link flow.

Bank Income Refresh

Bank Income Refresh is available as an optional add-on to Bank Income. With Bank Income Refresh, you will be able to get updated income data for a user. Existing income sources will be updated with new transactions, and new income sources will be added if detected.

To implement Bank Income Refresh:

  1. On the webhooks page in the Dashboard, enable Bank Income Refresh webhooks and (optionally) Bank Income Refresh Update webhooks.

  2. Call /credit/bank_income/refresh with the user_token for which you want an updated report.

  3. A BANK_INCOME_REFRESH_COMPLETE webhook will notify you when the process has finished. If the value of the result field in the webhook body is SUCCESS, the report was updated. If it was FAILURE, send the user through update mode and then try calling /credit/bank_income/refresh again.

  4. If the report was updated, when you next call /credit/bank_income/get or /credit/bank_income/pdf/get, the refreshed version of the report will be returned. To see old versions of the report, call /credit/bank_income/get with the options.count parameter set to a number greater than 1.

Institution coverage

To determine whether an institution supports Bank Income, you can use the Dashboard status page (look for "Bank Income") or the /institutions/get endpoint (look for or filter by the income_verification product). The income product returned by these surfaces represents a legacy product and does not indicate coverage for Bank Income.

Testing Bank Income

In Sandbox, you can use the user user_bank_income with the password {}. The basic Sandbox credentials (user_good/pass_good) will not return data when used to test Bank Income.

Plaid also has additional test users for scenarios such as joint accounts, bonus income, and different levels of creditworthiness: for details, see Credit and Income testing credentials.

When using special Sandbox test credentials (such as user_bank_income / {}), use the /sandbox/public_token/create flow or a non-OAuth test institution, such as First Platypus Bank (ins_109508). Special test credentials may be ignored when using the Sandbox Link OAuth flow.

If you’d like to test Bank Income with custom data, Plaid provides several test JSON configuration objects. To load this data into Sandbox, copy and paste the JSON into a new custom user via the Sandbox Users pane in the Dashboard.

/credit/bank_income/get can optionally be tested in Sandbox without using Link. Call /user/create and pass the returned user_token to /sandbox/public_token/create. /sandbox/public_token/create must be called with the following request body:

1{
2 "client_id": "${PLAID_CLIENT_ID}",
3 "secret": "${PLAID_SECRET}",
4 "institution_id": "ins_20", //any valid institution id is fine
5 "initial_products": ["income_verification"],
6 "user_token": "user-token-goes-here", //use the user_token from the `/user/create` call made earlier
7 "options": {
8 "override_username": "user_bank_income", //or other test user from Credit and Income testing credentials
9 "override_password": "{}",
10 "income_verification": {
11 "income_source_types": ["bank"],
12 "bank_income": {
13 "days_requested": 120 //any number of days under 730 is valid
14 }
15 },
16 }
17}

After calling /sandbox/public_token/create, call /credit/bank_income/get using the same user_token. The output of /sandbox/public_token/create will not be used, but calling it initializes the user token for testing.

Bank Income pricing

Bank Income is billed on a one-time fee model. Bank 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.

Next steps

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

Launch Center

See next steps to launch in Production

Launch

Launch Center

See next steps to launch in Production

Launch
Was this helpful?
Developer community
GitHub
GitHub
Stack Overflow
Stack Overflow
YouTube
YouTube
Discord
Discord