Migration guide: dwolla.js to dwolla-web.js

Announcements
1

Switching Javascript libraries can be a daunting task, but it’s often necessary to keep up with changes in technology or to take advantage of new features or functionality. This guide will help you understand the key differences between dwolla.js and dwolla-web.js (our Drop-in Components library) and provide step-by-step instructions for migrating to dwolla-web.js. Additionally, if migrating to drop-in components is not suitable for your needs, we will also cover an alternative approach for a custom implementation.

Note: If you are currently using the IP Allowlist functionality, please be aware that it is recommended to opt for the custom implementation option. The concurrent use of both IP allowlist and dwolla-web.js is presently not supported due to some limitations.

This guide takes you through:

  • Differences between dwolla.js and dwolla-web.js
  • Step-by-step instructions for migrating from dwolla.js to dwolla-web.js
  • Testing your migration in our Sandbox environment
  • Best practices
  • Alternative Approach: Custom Implementation

Let’s get started!

Differences between dwolla.js and dwolla-web.js

Functionality

dwolla.js:

This library supports:

  • Creating a verified funding source for a Customer using Dwolla’s IAV feature (deprecated 12/31/2022).
  • Creating an unverified funding source for a Customer by collecting banking information with a form and sending that information to Dwolla via the library.
  • Creating an unverified funding source for a Customer and initiating micro-deposits for verification. Note: Verifying the micro deposits after they post to the funding source is not supported by the library.

If you’ve been using dwolla.js for any of these functionalities, then you’re probably using one or both of these methods in your application:

dwolla.iav.start()

Related API endpoint: /customers/{id}/iav-token

dwolla.fundingSources.create()

Related API endpoint: /customers/{id}/funding-sources-token

dwolla-web.js:

What this library supports:

  • Creating an unverified funding source for a Customer.
  • Creating an unverified funding source for a customer and initiating micro deposits.
  • Verifying micro deposits.

Note: These three drop-in components are relevant to your migration from dwolla.js to dwolla-web.js, but others are available in the library. Check out the docs for a full list of all supported components, or view the storybook to see what each component looks like!

Implementation

dwolla.js: This library enables secure transmission of sensitive data, such as bank account and routing numbers, directly to Dwolla without the data passing through your server. It requires generating a single-use token via the Dwolla API, collecting the user’s banking information via a form, and passing it along to Dwolla by calling a JavaScript function.

dwolla-web.js: This library offers low-code UI Components that simplify the front-end work required to interact with end users for Dwolla-related functions. In order to use the dwolla-web.js JavaScript library, you must provide a unique “client-token” or server-side route that generates a client-token for configuration. By establishing an endpoint, the component can fetch client-tokens on-demand to display the appropriate UI. To implement the drop-in component, you must create a custom HTML container for it to render in upon page load. Initializing the dwolla-web.js library with dwolla.configure() will render the drop-in component.

User Experience

dwolla.js: The User experience is entirely handled by your application. You design a form to obtain the user’s account and routing numbers, and if necessary, you initiate micro-deposits through an API call. After the micro-deposits post to the account, you need to create a new form to gather the micro-deposit amounts and submit it to the Dwolla API for verification.

dwolla-web.js: Using dwolla-web.js eliminates the need to design forms for gathering banking details and conducting micro-deposit verification via API. The drop-in components are integrated within the library and are pre-built with input validation and success/error message handling. You can customize them to match your application’s interface design.

Migration Process

Now, let’s dive into the steps needed to successfully migrate from using dwolla.js to dwolla-web.js. Note: If you already use drop-in components in your application to leverage other supported functionalities, you can skip to Step 3.

Step 1: Begin the client-side implementation by replacing the dwolla.js script with dwolla-web.js in the ‘head’ of your HTML page.

Before:

<head>
    <script src="https://cdn.dwolla.com/1/dwolla.js"></script>
</head>

After:

<head>
    <script
        type="text/javascript"
        src="//cdn.dwolla.com/v2.2.0/dwolla-web.js"
    ></script>
</head>

Step 2: Set up a server side route for generating client-tokens.

Client-tokens contain granularly scoped permissions for a specific Customer associated with your Dwolla account and are valid for up to one hour. The library makes multiple HTTP calls to the endpoint you set up to fetch client-tokens as needed during the component’s lifecycle.

The server-side endpoint should act as a pass-through, receiving the request body and making the appropriate call to the '/client-tokens' endpoint in the Dwolla API. The '/client-tokens' endpoint will then return a response body with a “token” string value, which the HTTP response expects to be formatted like this: {token: ‘Token string value’}.

Here we have an example using Express.js to create a token URL that is invoked by dwolla-web.js whenever a client-token needs to be generated during the flow of a component.

/**
 * Using Dwolla Node.js SDK - https://github.com/Dwolla/dwolla-v2-node
 * Assuming the SDK has been installed and an instance of 'Client' initialised as 'dwolla' using the Dwolla API credentials
*/

app.post("/tokenUrl", function (req, res) {
  generateClientTokenWithBody(req.body).then((clientTokenRes) => {
    console.log(clientTokenRes);
    res.send({ token: clientTokenRes.token });
  });
});

function generateClientTokenWithBody(body) {
  const url = `/client-tokens`;

  return dwolla
    .post(url, body)
    .then((response) => {
      return response.body;
    })
    .catch((error) => {
      return error;
    });
}

Step 3: Remove all code related to the implementation of dwolla.js, which may include some or all of the following.

Step 4: Configure dwolla-web.js.

<script>
  dwolla.configure({
    environment: "sandbox",
    styles: "/styles/your-custom-styles.css",
    tokenUrl: "/tokenUrl",
    success: (res) => Promise.resolve(res),
    error: (err) => Promise.resolve(err),
  });
</script>

Step 5: Include the relevant drop-in components in your front-end code.

Create an unverified funding source.

<div class="container">
  <dwolla-funding-source-create customerId="{{ customerId }}">
  </dwolla-funding-source-create>
</div>

Create an unverified funding source and initiate micro-deposits for verification.

<div class="container">
  <dwolla-funding-source-create 
customerId="{{ customerId }}"
initiateMicroDeposits
  >
  </dwolla-funding-source-create>
</div>

Verify micro-deposits.

<div class="container">
  <dwolla-micro-deposits-verify
      customerId="{{ customerId }}"
      fundingSourceId="{{fundingSourceId}}"
  >
  </dwolla-micro-deposits-verify>
</div>

Important considerations during the migration process

Custom styling

dwolla-web.js offers CSS classes for styling specific components so you can customize them to match your application’s look and feel using a custom stylesheet. The elements are responsive by default within the specified container. Check out the Developer Documentation for lists of classes available for customizing each component.

Handling success and error callbacks

If the component encounters any exceptions, the error callback function will return a string indicating the issue. For instance, it may return a message such as "We encountered an issue fetching a token."

The success callback function is triggered when the component is implemented correctly and no exceptions are encountered, regardless of whether the API request itself was successful. It returns a JSON object containing a resource and a response, and the response includes relevant information from the API response. If a new resource is created, the response includes a location key:value pair with a link to the new resource. Otherwise, it contains the corresponding JSON response body from the API.

Example:

{
   "resource": "funding-sources",
   "response": {
      "location": "https://api.dwolla.com/funding-sources/e169aa24-92ad-4dd2-acdf-6803bb09c63e"
   }
}

For more detailed information and examples of callbacks, please refer to our guide in the Developer Documentation.

Testing

Testing in Dwolla’s Sandbox environment is crucial when migrating from one library to another. It enables you to verify that the new library is functioning correctly, is compatible with existing systems and meets your requirements. You can check that all required functionality is working as expected and identify and address any issues or bugs that may arise before going live in the production environment. This helps minimize potential downtime and ensure a smooth and seamless transition for you and your end users.

Tips for testing <dwolla-funding-source-create>

  • Use 222222226 or any valid US routing number to pass the API validation check on the Routing Number field.
  • Pass any numeric string of 4-17 digits for the Account Number field. Do not use a real bank account number.

Tips for testing <dwolla-micro-deposits-verify>

  • Test successful verification by supplying any two amounts less than 10 cents. This will trigger a customer_funding_source_verified webhook.
  • Test failed verification attempt by supplying the amounts 0.09 and 0.09. Three failed attempts will result in the customer_microdeposits_maxattempts webhook.

Best Practices

Use the success callback function provided by the component to extract and store the funding-source ID in relation to the Customer account in your database. By properly storing this information, you can improve the user experience and simplify future actions related to that funding source.

After you have created a funding source and initiated micro-deposits, we recommend waiting for the “microdeposits_completed” webhook event to occur before triggering the <dwolla-micro-deposits-verify> component. Keep in mind that in the Sandbox environment, you can verify the micro-deposits at any time, even if they have not been completed. To trigger the “microdeposits_completed” event, you will need to simulate bank transfer processing.

Alternative Approach: Custom Implementation

An alternative approach to switching to the drop-in components library (dwolla-web.js) is to build out your own custom form for collecting bank account information and passing it to the Dwolla API in order to create an unverified funding source.

To implement this custom solution, you would need to:

  1. Design and integrate a UI form in your application to collect the required bank account information from the user. Note: If you are currently using the 'dwolla.fundingSources.create()' function for creating unverified funding sources, you likely have a custom UI for collecting banking information already.

  2. Capture the information entered by the user and securely transmit it to your server.

  3. Utilize the Dwolla API to create an unverified funding source by making a request to the funding source creation endpoint with the collected bank account information.

  4. Handle the API response and provide appropriate feedback to the user based on the success or failure of the funding source creation.

As for verifying the funding source using micro-deposits, this can also be implemented by interacting with the API directly. We have a dedicated guide for verifying funding sources via micro-deposits in our official docs which can be found here - Micro Deposit Verification | Dwolla API Documentation

One thing to consider with the custom implementation approach is that sensitive banking information collected from your UI must be handled by your server, requiring additional security measures to protect the data.

Additional resources

Here are some additional resources that might be helpful to reference in relation to Drop-in Components.

You should now be equipped with the necessary information to make a successful migration to dwolla-web.js or explore the alternative approach of building out a custom implementation! Whether you choose to migrate to dwolla-web.js or pursue a custom implementation, we hope this guide has provided valuable insights. If you run into any issues or questions, feel free to ask below or create a new post!

2
3
4
5