Introduction to Auth

Instantly retrieve account information to set up pay-by-bank payments via ACH and more

Link an account

Fetch account info

Initiate a payment

Auth allows you to request a user's checking, savings, or cash management account and routing number, making it easy for you to initiate credits or debits via ACH, wire transfer, or equivalent international networks. For example, your app might allow users to accumulate a credit balance that they can cash out to a bank account, or it might allow users to pay you using their bank account information (pay by bank). With Auth, a user can provide this information in a frictionless way, simply by authenticating into their bank account.

For an all-in-one solution that includes payment processor functionality, see Transfer (US-only). If you are not using Transfer, Auth must be used with a third-party payment processor to move money: either a Plaid Partner or another third party. For more information, see Using a Payments Service.

Auth can only be used with debitable checking, savings, or cash management accounts. Credit-type accounts, including credit cards, cannot receive payments directly via electronic interbank transfers, and Auth data cannot be used to set up credit card payments. Auth can not be used to connect debit cards; instead, you can make a transfer directly from the user's bank account, saving you money over using the debit card network.

Below is a high level overview of the Auth integration process. For a more detailed walkthrough, see Add auth to your app or (if applicable) the docs for the specific partner you are using.

1. Create a Link token by calling /link/token/create with auth in the products parameter.
   • In the US, you may optionally configure this call to extend coverage to more banks or allow customers to verify their account without entering bank credentials. For details, see Additional auth coverage.
2. Initialize Link with the Link token from the previous step. For more details, see Link.
   • For Link configuration recommendations, see Optimizing the Link UI for Auth.
3. Once the user has successfully completed the Link flow, exchange the public_token for an access_token.
4. If using a Plaid partner for payment processing, ensure the partner is enabled on your Plaid Dashboard, then call /processor/token/create or /processor/stripe/bank_account_token/create to obtain a token that you will provide to the partner to enable funds transfers. For more detailed instructions, including a full walkthrough, see Auth payment partners.
5. If not using a Plaid partner, call /auth/get to obtain the account and routing number, then provide these fields to your payment processing system.
6. Listen for the AUTH: DEFAULT_UPDATE, ITEM: USER_PERMISSION_REVOKED, and ITEM: USER_ACCOUNT_REVOKED webhooks to be informed when account and routing number data become invalid.
7. (Optional) To reduce fraud and complement know-your-customer processes, call /identity/get to verify that the identity information held by the bank matches the information that the user has provided to you. For more details, see Identity.
8. (Optional) If you plan to transfer funds from the linked bank account, check the account's balance beforehand by calling /accounts/balance/get to avoid risk of an overdraft. For more details, see Balance.

When using Auth, you will send Auth data to a payments service to initiate an interbank transfer; Plaid does not function as the payment processor. While Plaid is processor-agnostic and allows you to work with any partner you want, one easy way to make transfers is to work with a payments platform that partners with Plaid, such as Dwolla or Stripe. Working with these partners, you will not call the /auth/get endpoint, so you will not obtain a user's bank account information. Instead, you will call /processor/token/create or /processor/stripe/bank_account_token/create to obtain a Plaid token that you will provide to the partner and that allows them to make these Plaid API calls as needed. For detailed instructions on how to set up Auth with a Plaid partner, as well as a list of supported funds transfer partners, see Auth Partnerships.

If you choose to use a payments provider who is not a Plaid partner, you will need to obtain bank account numbers and codes using /auth/get. Given the sensitive nature of this information, we recommend that you consult the Open Finance Data Security Standard for security best practices. We also recommend that you do not store account numbers. You can integrate with one of Plaid's Data Security partners to process and share tokenized bank account numbers instead of raw bank account numbers. Contact your Account Manager to learn more about these partnerships.

When used in its default configuration, Auth provides access to approximately 95% of eligible financial institution accounts in supported countries. In the US, Plaid also offers additional flows you can implement to cover more institutions with Auth, including manual micro-deposit based flows. These flows can also be used to support customers who cannot or do not want to log in to a bank account. For more information, see Add institution coverage.

By default, only checking, savings, and cash management accounts will appear when using Auth, and institutions that do not support these accounts will not appear in the Institution Select pane.

The following Link configuration options are commonly used with Auth:

• Account select: The "Account Select: Enabled for one account" setting configures the Link UI so that the end user may only select a single account. If you are not using this setting, you will need to build your own UI to let your end user select which linked account they want to use to send or receive funds.
• Embedded Institution Search: This presentation mode shows the Link institution search screen embedded directly into your UI, before the end user has interacted with Link. Embedded Institution Search increases end user uptake of pay-by-bank payment methods and is strongly recommended when implementing Auth as part of a pay-by-bank use case where multiple different payment methods are supported.

When using Chase or PNC, Auth will provide a tokenized account number (TAN), which is unique to your app, rather than the user's exact account number. Institutions that use TANs do not always expose them to end users; to avoid confusion, in user-facing UIs, always display the account mask rather than the account number, as end users will not recognize their TAN.

TANs are valid for ACH and RTP, but may not be used for wire transfers or physical checks. TANs may not be supported by your third-party fraud and account verification databases and vendors.

If the underlying Item is deleted (using /item/remove) or a user revokes access to their account (such as via the Chase Security center or my.plaid.com), the TAN will become invalid and any attempt to make a transfer using that TAN will fail with an R04 return code. To avoid returns, listen for the USER_PERMISSION_REVOKED and USER_ACCOUNT_REVOKED webhooks and do not use an account number, processor token, or Stripe bank account token associated with an Item or account where access has been revoked. Instead, send the end user through update mode to restore the Item and then call the Auth endpoint again.

Currently, only Chase supports the USER_ACCOUNT_REVOKED webhook. The USER_PERMISSION_REVOKED webhook will fire for Chase Items, but will not always fire for PNC Items, depending on how the user revoked access. Wider and more consistent support for these webhooks among institutions that use TANs will be added later in 2024 and in early 2025.

Because account numbers cannot reliably be used to persistently identify TAN-enabled accounts across different Item instances, Plaid provides a persistent_account_id field for this purpose. This field is only available at institutions that use TANs.

If a Chase duplicate Item is created, the old Item will be invalidated, but the TAN on the new Item will remain the same. The TAN will only change if the user revokes access.

If multiple Items in your app correspond to the same account (for example, in the case of a joint bank account with multiple owners), each Item will typically have a different TAN.

Chase and PNC also provide a tokenized routing number; this may be the same routing number for all accounts at that bank and is not necessarily unique to each account.

Because routing and account numbers are inherently persistent, Plaid does not check for updates to Auth data for existing Items except in special circumstances, such as a bank changing its routing numbers due to a system change or merger. Plaid will also check for updated Auth data if a new user account is added to an Item via update mode.

The United States uses the Automated Clearing House (ACH) system for funds transfers, which uses account and routing numbers. Banks also have a second routing number, known as the wire transfer routing number. Wire transfers can be used to receive international payments and can be faster than ACH transfers, but often involve a fee. Plaid Auth can only provide wire transfer routing numbers for institutions in the US.

For a detailed, comprehensive guide to ACH transfers and payments, see Plaid's Modern Guide to ACH.

1"numbers": {
2  "ach": [
3    {
4      "account": "1111222233330000",
5      "account_id": "bWG9l1DNpdc8zDk3wBm9iMkW3p1mVWCVKVmJ6",
6      "routing": "011401533",
7      "wire_routing": "021000021"
8    }
9  ],
10  "bacs": [],
11  "eft": [],
12  "international": []
13}

In Canada, the routing number is in a different format than US routing numbers and broken into two pieces: the transit number (also known as the branch number), followed by the institution number. Canada uses Electronic Funds Transfer (EFT); VoPay is a Plaid partner that can be used to process EFT transfers.

1"numbers": {
2  "eft": [
3    {
4      "account": "111122220000",
5      "account_id": "qVZ3Bwbo5wFmoVneZxMksBvN6vDad6idkndAB",
6      "branch": "01533",
7      "institution": "114"
8    }
9  ],
10  ...
11}

In the European Economic Area member states (which includes Euro zone nations, as well as the United Kingdom), institutions use a Bank Identifier Code (BIC), also known as a SWIFT code. Each bank account has an International Bank Account Number (IBAN), which is used along with the BIC for funds transfers. Many bank accounts also have internal, non-IBAN account numbers that cannot be used for funds transfers. The funds transfer system is known as the Shared European Payment Area (SEPA), and it supports SEPA credit transfer, SEPA instant credit transfer, and SEPA direct debit.

1"numbers": {
2  "international": [
3    {
4      "account_id": "blgvvBlXw3cq5GMPwqB6s6q4dLKB9WcVqGDGo",
5      "bic": "IE64BOFI90583812345678",
6      "iban": "IE64BOFI90583812345678"
7    }
8    ...
9  ]
10}

The UK uses the SEPA system as well as the Bankers Automated Clearing System (BACS). Payments within the BACS system cannot be made outside the UK and take several days to process. BACS payments are typically used for recurring direct debit payments, such as payroll. UK bank accounts will typically have both a BACS sort code and an IBAN and support both BACS transfers and SEPA transfers.

1"numbers": {
2  "bacs": [
3    {
4      "account": "80000000",
5      "account_id": "blgvvBlXw3cq5GMPwqB6s6q4dLKB9WcVqGDGo",
6      "sort_code": "040004"
7    }
8  ],
9  "international": [
10    {
11      "account_id": "blgvvBlXw3cq5GMPwqB6s6q4dLKB9WcVqGDGo",
12      "bic": "MONZGB21XXX",
13      "iban": "GB23MONZ04000480000000"
14    }
15  ]
16  ...
17}

For a real-life example of an app that incorporates Auth, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that fetches Auth data in order to set up funds transfers. The Auth code can be found in items.js.

Plaid provides a GitHub repo with test data for testing Auth in Sandbox, helping you test configuration options beyond those offered by the default Sandbox user. For more information on configuring custom Sandbox data, see Configuring the custom user account.

For details on testing Auth with more complex Auth flows such as micro-deposit-based Auth, first familiarize yourself with Adding Institution Coverage, then see Test in Sandbox.

Auth is billed on a one-time 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.

Now that you understand Auth, add Auth to your app, or see Move Money with Auth partners to see specific instructions for configuring Auth with Plaid partners.

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