Introduction to Auth
Instantly retrieve account information to set up pay-by-bank payments via ACH and more
API Reference
View Auth requests, responses, and example code
View Auth APIQuickstart
Learn about Plaid's key concepts and run starter code
Get startedAuth allows you to request a user's checking or savings 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 checking or savings accounts. Auth cannot be used with other depository accounts, such as money market 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.
Enhancing Auth with related products
Auth is commonly used in combination with other Plaid APIs that reduce risk and support compliance, such as Balance (to verify accounts have sufficient funds), Signal (to calculate the risk of ACH returns with ML-powered analysis), and Identity (to verify ownership information on the account).
For account funding use cases, see Identity Verification for an end-to-end KYC compliance solution with optional AML capabilities.
Auth integration process
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.
- Create a Link token by calling
/link/token/create
withauth
in theproducts
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.
- 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.
- Once the user has successfully completed the Link flow, exchange the
public_token
for anaccess_token
. - 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. - 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. - Listen for the
AUTH: DEFAULT_UPDATE
,ITEM: USER_PERMISSION_REVOKED
, andITEM: USER_ACCOUNT_REVOKED
webhooks to be informed when account and routing number data become invalid. - (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. - (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.
Using a payments service
Looking for bank-to-bank transfer capabilities and don't have a payment processor yet? Check out Transfer (US only) for a money movement solution with built-in payment processing capabilities.
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.
Covering more institutions and flows
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.
Optimizing the Link UI for Auth
By default, only checking and savings 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.
Tokenized account numbers
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 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, in the case of a USER_PERMISSION_REVOKED
webhook, delete the existing Item and create a new Item. In the case of a USER_ACCOUNT_REVOKED
, send the end user through update mode and then call the Auth endpoint again.
Currently, only Chase supports the USER_ACCOUNT_REVOKED
webhook. Support for additional institutions that use TANs is expected to 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.
Some institutions listed in this section as having tokenized account numbers may be in the process of converting to TANs or may be performing a gradual rollout of this functionality.
Updates to Auth data
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.
United States (ACH) Auth data
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}
Auth data for other countries
Canada (EFT)
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}
Europe (SEPA transfers)
For funds transfers in Europe, also consider the Payment Initiation API, which allows end-to-end payments directly, without having to integrate an additional payment processor.
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}
United Kingdom (BACS)
For funds transfers in the UK, also consider the Payment Initiation API, which allows end-to-end payments directly, without having to integrate an additional payment processor.
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}
Sample app code
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.
Testing Auth
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 pricing
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.
Next steps
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 are using Auth as part of an account funding use case, see the Plaid Account Funding Guide for an overview of all required steps.
If you're ready to launch to Production, see the Launch checklist.