Language
Tools
The API Basics
- Customer types
- Balance Funding Source
- Bank transfer workflow
- Business verified customer
- Funding source verification
- Personal verified customer
- Test in the Sandbox
- Webhook Events
Features
Integrations
Integrations
Dwolla.js
Using Dwolla.js for Instant Account Verification (IAV)
For Dwolla API customers, dwolla.js
has the added function of facilitating Instant Account Verification (IAV) on their customer’s bank or credit union account. By calling a separate function dwolla.iav.start()
, your application can render the IAV flow within a specified container. dwolla.iav.start()
allows for customization through configurable options such as:
stylesheets
- a list of CSS stylesheets for styling the IAV flowmicroDeposits
- presents a selection screen for the user to choose the micro-deposit method of bank verification throughout the IAV flowfallbackToMicroDeposits
- presents a selection screen for the user to fallback to selecting the micro-deposit method of bank verification within the IAV flowbackButton
- displays a back button throughout the IAV flowsubscriber
- a function that can be used by an application to subscribe to state changes throughout the IAV flow
dwolla.iav.start()
Parameter | Type | Value |
---|---|---|
iav-token | string | A single use IAV token generated on your server. |
options | object | An object containing configurable options. Contains keys: container , stylesheets , microDeposits , fallbackToMicroDeposits , backButton , and subscriber . See example below.container represents a string value container element where IAV will render.stylesheets represents an array list of stylesheets to load IAV styles.microDeposits represents a boolean true or false value which determines if the micro-deposit method of bank verification is presented as an option throughout the IAV flow.fallbackToMicroDeposits represents a boolean true or false value which determines if a fallback selection screen appears for choosing an alternative bank verification method.backButton represents a boolean true or false value which determines if a back button is displayed throughout the IAV flow.subscriber is a function that can be used to subscribe to state changes throughout the IAV flow. This function will be called with an object containing a currentPage and an optional error attribute. |
callback | function | A callback function that handles the response from Dwolla. |
Example
dwolla.iav.start('8zN400zyPUobbdmeNfhTGH2Jh5JkFREJa9YBI8SLXp0ERXNTMT', {
container: 'iavContainer',
stylesheets: [
'https://fonts.googleapis.com/css?family=Lato&subset=latin,latin-ext'
],
microDeposits: false,
fallbackToMicroDeposits: true,
backButton: true,
subscriber: ({ currentPage, error }) => {
console.log('currentPage:', currentPage, 'error:', JSON.stringify(error))
}
}, function(err, res) {
console.log('Error: ' + JSON.stringify(err) + ' -- Response: ' + JSON.stringify(res));
});
Handling IAV errors
IAV related errors are returned either as user-facing messages within the IAV flow, or triggered through the dwolla.js callback. User-facing messages are displayed in red text at the top of the bank login screen informing the user there was an issue with connecting the associated bank account. Error callbacks will trigger letting your app know of errors that can’t be fixed by the user within the flow.
Error callbacks will contain a similar JSON error response body as common errors in the API, which includes a top-level error code
and a message
. Reference the following list of error callbacks:
Code | Message | Description |
---|---|---|
UnexpectedPage | IAV navigated to an unexpected page and was cancelled. | A Dwolla related error occurred. |
InvalidIavToken | Invalid IAV token. | An IAV token has already been used or has exceeded its expiration time of 1 hour. |
UnsupportedBank | Sorry, that financial institution is not supported. If possible, please choose a different one or an alternative method for connecting your financial institution. | The customer’s bank is not supported by the IAV flow. |
RateLimitReached | Sorry, we’re having trouble logging into your account. Please try a different account. | The customer exceeded the max number of two IAV attempts with the same bank. The customer must wait 30 minutes in order to re-authenticate. |
Example error callback
{
"code": "RateLimitReached",
"message": "Sorry, we’re having trouble logging into your account. Please try a different account."
}
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
There is a list of banks that aren’t found in the bank search, generally these are smaller financial institutions. As a result we’ll prompt the user to input the account and routing number of their bank. Once they click agree and continue, we’ll attempt to lookup a bank with the provided information. If a bank is found, we’ll return a screen for the user to authenticate using their online banking credentials.
Options and customization
microDeposits
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.
fallbackToMicroDeposits
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.
backButton
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.
subscriber
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:
Attribute | Value |
---|---|
currentPage | BankSearch BankLogin MFA SelectAccount SuccessIAV SelectVerificationMethod SubmitBankAccountDetails SuccessMicroDeposits |
error | code 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."
}
}
stylesheets
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*/
.dwolla-iav-text-box,
.dwolla-iav-button,
.dwolla-iav-header,
.dwolla-iav-text,
.dwolla-iav-link,
.dwolla-iav-error,
.dwolla-iav-label,
.dwolla-iav-header,
.dwolla-iav-text-box,
.dwolla-iav-text-box:focus,
.dwolla-iav-link,
.dwolla-iav-link:hover,
.dwolla-iav-button,
.dwolla-iav-button:hover,
.dwolla-iav-button:active,
.dwolla-iav-check-image,
.dwolla-iav-radio-hover,
.dwolla-iav-radio-selected
Testing IAV in the Sandbox
For more information on how to test various IAV scenarios in the Sandbox, check out our developer resource article. This article goes through different ways to simulate success and error scenarios including:
- Customer provides invalid login credentials
- Unsupported banks
- Prompts for your Customer to visit the bank website to complete verification
- …and more!
View:
- Funding source verification - IAV
- Dwolla.js - Overview
- Add a bank account
- On-demand bank transfers
- Sandbox testing
Status
Production: OperationalFinancial institutions play an important role in the Dwolla network.
Dwolla, Inc. is an agent of Veridian Credit Union and all funds associated with your account in our network are held in one or more pooled accounts at Veridian Credit Union. These funds may not be eligible for share insurance by the National Credit Union Share Insurance Fund. Dwolla, Inc. is the operator of a software platform that communicates user instructions for funds transfers to Veridian Credit Union.