Docs
Get API Keys

Add a Bank Funding Source with Plaid #

Dwolla partners with Plaid to provide customers with bank account verification through a tokenized solution. Bank accounts are linked with purpose-built tokens between the Dwolla and Plaid platforms.

While bank account verification is required before initiating an ACH transaction from a funding source, Dwolla clients are able to choose between Dwolla's micro-deposit solution or a third-party data aggregator, such as Mastercard, MX, or, as we will discuss in further detail in this guide, Plaid.

For more information on Dwolla's tokenized solutions with other third-party data aggregators, check out our Secure Exchange solution!

Prerequisites #

Let's first go over a few items you need to check off before you begin your integration.

  • Set up a Dwolla Production account, or a Dwolla Sandbox account if you're still developing or testing your application.
  • Set up a Plaid Production account, or a Plaid Sandbox account if you're still developing or testing your application.
  • Enable Dwolla's Plaid integration in your Plaid account settings. If you need assistance with this step, reach out to your Account Manager with Plaid.
  • Customize Plaid Link's account selection to only be "enabled for one account."

Adding a bank is a one-time process that verifies the account ownership of the underlying bank account being added by an end user. At the end of this guide, you'll obtain a Funding Source URL, which is a unique identifier that represents a bank account being used for ACH debits and/or credits.

Integrate with Plaid #

Once you have your Dwolla and Plaid accounts set up, you can begin the integration process. For the following steps, we will make use of two Plaid libraries: Plaid Link (more specifically, react-plaid-link), Plaid Link's React bindings, and plaid-node, Plaid's server-side Node SDK.

In order to instantiate a Plaid Link instance—in our case, by using usePlaidLink—you first need to have your server generate a Link token. To learn more about what properties are available, check out Plaid's Create Link Token documentation.

Though you are welcome to use additional Plaid products and customize the LinkTokenCreateRequest object to your liking, a couple properties are required in order to be compatible with Dwolla:

  • country_codes must include "US" (or an enumerative equivalent), as Dwolla is currently only able to transact with U.S.-based bank accounts.
  • products must include "auth" (or an enumerative equivalent), as Dwolla will fetch the associated account and routing number using Plaid Auth.
typescript
import type { LinkTokenCreateRequest, LinkTokenCreateResponse } from "plaid";
import { CountryCode, Products } from "plaid";
import { v4 as uuidv4 } from "uuid";

const createLinkToken = async (): Promise<LinkTokenCreateResponse> => {
  const request: LinkTokenCreateRequest = {
    client_name: "Dwolla-Plaid Integration Example",
    country_codes: [CountryCode.Us],
    language: "en",
    products: [Products.Auth],
    user: { client_user_id: uuidv4() },
    redirect_uri: "http://localhost:3000",
  };
  return (await plaidClient.linkTokenCreate(request)).data;
};

Once your client environment has made the necessary requests to your server to fetch the Link token, you can now give that token to usePlaidLink with an additional onSuccess handler.

The onSuccess handler will be responsible for proxying client requests to your server to, at a minimum,

  1. Exchange the public token for an access token.
  2. Exchange the access token and account ID for a processor token.
  3. Create a funding source using the processor token.
typescript
import type { PlaidLinkOnSuccess } from "react-plaid-link";
import { usePlaidLink } from "react-plaid-link";

const handlePlaidLinkSuccess: PlaidLinkOnSuccess = async (
  publicToken,
  metadata
) => {
  // When handling the Plaid Link token, you'll want to call the following functions
  // in order to create a Dwolla funding source. Function implementations can be found below.
  //
  // [1] Exchange public token for an access token
  // [2] Exchange access token & accountID for a processor token
  // [3] Create a funding source using the processor token
};

const { open, ready } = usePlaidLink({
  onSuccess: handlePlaidLinkSuccess,
  token: linkToken, // linkToken is the Link token that your server sent
});

Exchange Public Token for Access Token #

Now that you have your public token, you will need to exchange it for an access token back in your server environment. An access token is an intermediate step between a public token and a processor token, and can be generated in a one-line JavaScript function using Plaid's Node SDK.

typescript
// 1. Exchange public token for an access token
export const exchangeForAccessToken = async (
  publicToken: string
): Promise<string> =>
  (await plaidClient.itemPublicTokenExchange({ public_token: publicToken }))
    .data.access_token;

Exchange Access Token and Account ID for Processor Token #

Continuing in your server environment, once you have an access token and an account ID (account ID is returned by Plaid Link in your client environment), you can now create a processor token!

Similar to how you created a Link token, when creating a processor token, you must specify Dwolla ("dwolla") as the processor. If you are using Plaid's SDK, you can use an enumerative equivalent, such as ProcessorTokenCreateRequestProcessorEnum.Dwolla.

typescript
// 2. Exchange access token & accountID for a processor token
import { ProcessorTokenCreateRequestProcessorEnum } from "plaid";

export const exchangeForProcessorToken = async (
  accessToken: string,
  accountId: string
): Promise<string> =>
  (
    await plaidClient.processorTokenCreate({
      access_token: accessToken,
      account_id: accountId,
      processor: ProcessorTokenCreateRequestProcessorEnum.Dwolla,
    })
  ).data.processor_token;

Once your application has generated the processor token, you are now ready to integrate with Dwolla!

Integrate with Dwolla #

Before creating a funding source, your application will need to create a Customer. If you have not created a customer yet, check out our Create a Customer API reference, or our Create a Business Verified Customer or Create a Personal Verified Customer guides.

Once you have a customer set up, we will use Dwolla's server-side Node SDK to create the funding source.

Create a Funding Source #

To create a verified funding source for a customer, you will supply two required properties: name and plaidToken. In the API request, name defines an arbitrary name that you or your user will assign to the funding source, and plaidToken defines the Plaid processor token that was generated in the previous step.

In the following function, once a response is received, it will extract the Location header value, which is the fully-qualified URL specifying the resource location of your funding source.

typescript
// 3. Create a funding source using the processor token
interface CreateFundingSourceOptions {
  customerId: string;
  fundingSourceName: string;
  plaidToken: string;
}

const createFundingSource = async (
  options: CreateFundingSourceOptions
): Promise<string> =>
  (
    await dwollaClient.post(`customers/${options.customerId}/funding-sources`, {
      name: options.fundingSourceName,
      plaidToken: options.plaidToken,
    })
  ).headers.get("Location");

Frequently Asked Questions #

When creating a funding source, a Plaid processor_token value is passed in using the plaidToken key. With this information, Dwolla executes a call to Plaid's API to securely retrieve the account and routing number and creates a funding source on your behalf. Upon success, Dwolla returns a URL that represents the new funding source via the Location response header.

Yes, if the end user has 2FA enabled with their bank, Plaid will attempt to mimic their bank's login flow, meaning that the user should receive a 2FA code, and is subsequently prompted to enter it in on the next screen.

If the processor_token has already been used to create a funding source, then the token changing or expiring will not affect it; Dwolla only uses the processor_token to fetch the account and routing number from Plaid and then immediately discards it.


However, if you have not yet used the processor_token to create a funding source, then you will need to follow Plaid's process for creating a new token before sending it over to Dwolla.

Yes, it is possible to use Plaid Link to both automatically verify bank accounts and manually verify via micro-deposits if the bank is not supported or an error occurs during automatic verification.

No. Since Dwolla only uses Plaid to securely retrieve the account and routing number, any changes to the underlying Plaid account will not affect the funding source(s) that have already been created in Dwolla.

This issue can occur when the user's bank utilizes Tokenized Account Numbers (TANs) for bank verification, and Plaid provides Dwolla with the TAN instead of the actual Account Number. Dwolla processes the ACH payment using the TAN. If the user has disabled TAN transactions on their bank's website, the ACH payment made by Dwolla will fail with an ACH return (e.g., R04 - Invalid Account Number).


To resolve this issue, please advise the user to contact their bank or visit their bank's website and enable TANs for future transfers. In some cases, it might be necessary to re-add the Plaid verified bank using a new processor token.

Still haven’t found what you are looking for?
Ask the community.
Test in the Sandbox for free today.
Use sandbox environment to test API requests.
Get API Keys
2024 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.