Step 3: Configure and call function #

Configuration options are available for utilizing dwolla.js in both our Sandbox and production environments. Configuration of an environment should take place after you have included the dwolla.js library.

// Sandbox

// Production

Now that you have dwolla.js initialized on the page and the container created where you’ll render the IAV flow, you’ll create a JavaScript function that responds when clicking the “Add bank” button on your page. Once your Customer clicks “Add Bank”, your application will call dwolla.iav.start() passing in the following arguments: the iavContainer element where IAV will render, a string value of your single-use IAV token, and a callback function that will handle any error or response.

<script type="text/javascript">
$('#start').click(function() {
  var iavToken = '4adF858jPeQ9RnojMHdqSD2KwsvmhO7Ti7cI5woOiBGCpH5krY';
  dwolla.iav.start(iavToken, {
          container: 'iavContainer',
          stylesheets: [
          microDeposits: 'true',
          fallbackToMicroDeposits: 'true'
        }, function(err, res) {
    console.log('Error: ' + JSON.stringify(err) + ' -- Response: ' + JSON.stringify(res));

Options and customization #


Your application can present the micro-deposit method of bank verification throughout the IAV flow by setting the microDeposits option to true. This option gives the user the ability to initially select either the micro-deposit method of bank verification or IAV, as well as fallback to selecting the micro-deposit method of bank verification if un-successful connecting a bank through the IAV flow.

Micro-deposit fallback


If your application sets the fallbackToMicroDeposits option to true, a fallback selection screen will appear after two failed attempts if there was an issue with connecting a bank using IAV. This selection screen asks the user to choose from either the traditional micro-deposit method of bank verification or re-attempt the IAV flow choosing a different financial institution.


By default, a back button will not be displayed throughout the IAV flow. If your application sets the backButton option to true, a back button will appear in the lower left corner of the container throughout the IAV flow.


An optional subscriber function can be used if your application is wanting to receive additional information on where the user is within the IAV flow, as well as if a user-facing message was presented to the user. subscriber is a function that will be called with an object containing a currentPage and an optional error attribute. currentPage will be a string value that identifies what page the user is on in the IAV flow. If an error occurs, the error attribute will be returned along with currentPage. error will be a JSON object, which includes a top-level error code and a message (similar to common errors in the API). Reference the following table for possible values:

SuccessMicroDepositserrorcode and message:
InvalidLogin - "Please make sure your login or security information is correct."
AccountNotFound - "Sorry, we’re unable to find your {BANK NAME} account. Please try again or use a different account."
UnsupportedSite - "Sorry, that financial institution is not supported. If possible, please choose a different one or an alternative method for connecting your financial institution."
AlreadyLoggedIn - "If you're currently logged in to your {BANK NAME} account, please log out and try again."
VisitSite - "We’re unable to process your information because the {BANK NAME} site is currently requiring additional action from you. Please resolve this, then try again."
UnavailableSite - "Sorry, there seem to be some technical difficulties while attempting to process your information. Please try again later."
Example subscriber callback
  "currentPage": "BankLogin",
  "error": {
    "code": "InvalidLogin",
    "message": "Please make sure your login or security information is correct."


Dwolla provides a list of CSS classes available for styling certain elements of the IAV flow. These elements can be easily customized to match the look and feel of your application, and are included within the options JavaScript object of the function dwolla.iav.start(). You can specify one or many stylesheets as a list within the stylesheets attribute. By default, the elements within your specified container are responsive to any change in screen size.

List of CSS classes

/* Available css classes for customization*/

IAV user experience #

Financial institutions have different procedures when it comes to online logins. There are two flows to be aware of in terms of user experience: Preferred and Non-preferred. Your Customers may fall into either one of these two flows when verifying their bank account within the IAV experience.

Preferred Flow #

There are a subset of banks that are found in the initial bank search page that will immediately prompt the user to login with the associated bank account. These are some of the larger financial institutions in the United States, and are all supported by our IAV flow. If your Customer is not banking with one of these institutions, they can search for their bank in the search bar.

Non-preferred Flow #

Non-preferred flow #1

There are a number of banks that aren’t found in the bank search with IAV. These banks are generally smaller financial institutions. When a bank isn’t returned in the bank search, the IAV flow will prompt the end user to input the account and routing number of their bank. Once they click agree and continue, an attempt will be made to look up a bank with the provided information. If a bank is found, it is added as an unverified funding-source to the Customer and the user is returned to a screen to authenticate using their online banking credentials. Once the online banking credentials are submitted, Dwolla receives back information that enables the bank account to be verified.

Alternatively, if the user fails to correctly enter their online credentials, the IAV flow will fallback to micro-deposit verification after two failed attempts. However, you must make sure that your application has set the fallbackToMicroDeposits option to true within the dwolla.js library in order for a fallback selection screen to appear after two failed connection attempts. In addition, a selection screen will be shown to the user which prompts them to choose from either the traditional micro-deposit method of bank verification or to re-attempt the IAV flow choosing a different financial institution.

Non-preferred flow #2

In some cases, we don’t receive enough information back to verify the bank account. In such cases, we will fall back to name matching in order to determine if the bank should be verified.

Note: In a non-preferred flow, if the user enters their account and routing numbers to look up a bank and exits the flow without entering their online banking credentials for authentication, then we fail to make a connection to the bank account and the user is left with an unverified funding-source.

If you run into such cases, we have a few recommendations in order to handle the failure attempt and continue the bank verification process. Immediately after the IAV flow, check for the Customer’s list of funding-sources. The list is sorted by the created timestamp of the funding-sources, so the latest funding-source should be at the top of the list. If you find that there exists a newly added funding-source with an unverified status, you can do one of the following,

  • Remove the unverified funding-source and prompt the user to attempt the IAV flow again
  • Verify the funding-source using Microdeposits

Test in the Sandbox for free today.

Use sandbox environment to test API requests.

Get API Keys
2022 All Rights Reserved
Financial institutions play an important role in our network.

All funds transfers made using the Dwolla Platform are performed by a financial institution partner, and any funds held in a Dwolla Balance are held by a financial institution partner. Learn more about our financial institution partners.