Drop-in Components - Dwolla Developer Portal

Overview

Dwolla’s drop-in components library allows developers to leverage isolated functions or build connected flows in their web applications, which expedites the integration process with the Dwolla Platform. Each component within Dwolla’s drop-in components library includes HTML, CSS and JavaScript that developers can drop-in and customize to fit the look and feel of their application. The library comes with a collection of low-code components that solve for a variety of functions and flows including: create a customer, document upload, balance display, as well as a connected flow for accepting incoming payments from a user. Each drop-in component contains built-in features such as responsive design, custom styling, error handling, and more. These components allow developers to ship more with fewer lines of code— while improving readability and maintainability of their application’s code. This is a language-agnostic library, meaning that any webpage that supports client-side JavaScript will support drop-in components! For ease of use, however, we also offer JSX/TSX bindings if you are developing using React or a React-based environment (such as Next). As the library continues to grow, Dwolla will evaluate adding support for other frameworks based on community feedback.

Workflow

Use of Dwolla’s drop-in components requires client-side and server-side interaction between your application and Dwolla. A unique “client token” is generated with limited permissions to be used in the components library to authenticate requests to Dwolla.

Initialize Components
On your application’s front-end, the Dwolla components library is instantiated and configured. One or many components are dropped into the web page where they will be rendered.
Request Client Token
A request is sent from your front-end to your back-end server to generate a client-token. Using a server-side SDK, you’ll specify the “action” needed for the component and the unique Customer ID that represents the end user performing the action.
Authenticate with Client Token
Your server sends the generated client token back to your front-end, which is used by the components library to authenticate the client-side request to Dwolla.
User Interaction
Your end user interacts with the Dwolla Component, either directly via submission of information in a form (e.g. upgrade customer), or indirectly by viewing data (e.g. balance display).

Drop-in Component Example

Dwolla’s drop-in components are customizable to match the look and feel of your application down to the individual HTML element by applying styles via custom CSS classes. Preview the Unverified Customer component below, or refer to the drop-ins examples repo to view a list of all drop-in component examples.

Setup

Every component shares the same one-time setup: load dwolla-web.js, then call dwolla.configure({ ... }). The tokenUrl you provide points at your own back-end proxy, which mints the scoped client token each component needs. Because the proxy handles token generation, you don’t need to specify individual client-token actions per component.

<head>
  <script src="//cdn.dwolla.com/v3.1.0/dwolla-web.js"></script>
  <link rel="stylesheet" href="/styles/custom.css" />
  <script>
    dwolla.configure({
      environment: "sandbox",
      styles: "/styles/custom.css",
      success: (res) => Promise.resolve(),
      error: (err) => Promise.resolve(),
      tokenUrl: "/tokenUrl",
    });
  </script>
</head>

For a full walkthrough, reference the Drop-in Components Guide.

Supported Components

Dwolla’s UI components library contains a variety of supported components that represent isolated functions or connected flows. This section outlines the complete list of supported components. For each component you’ll find a description of when to use it, its HTML tag, configurable attributes, CSS classes for customization, and a preview.

Create a Receive Only User

dwolla-customer-create Renders a form that collects the information needed to create a Receive Only user (type="receive-only"). Receive Only users are restricted to a payouts-only funds flow. Use this when you need to pay out to a recipient who won’t send funds on your platform. To learn more about this customer type, visit our docs on concepts.

Usage

This assumes you’ve already called dwolla.configure({ ... }) once during setup.

<dwolla-customer-create
  type="receive-only"
  terms="www.yourterms.com"
  privacy="www.yourprivacy.com"
>
</dwolla-customer-create>

Full HTML page example

<head>
  <script src="//cdn.dwolla.com/v3.1.0/dwolla-web.js"></script>
  <link rel="stylesheet" href="/styles/create-custom.css" />
  <script>
    dwolla.configure({
      environment: "sandbox",
      styles: "/styles/create-custom.css",
      success: (res) => Promise.resolve(),
      error: (err) => Promise.resolve(),
      tokenUrl: "/tokenUrl",
    });
  </script>
</head>
<body>
  <div class="container">
    <dwolla-customer-create
      type="receive-only"
      terms="www.yourterms.com"
      privacy="www.yourprivacy.com"
    >
    </dwolla-customer-create>
  </div>
</body>

Attributes

Attribute	Description	Required
`type`	Set to `receive-only` to create a Receive Only user.	Yes
`terms`	URL to your Terms of Service, shown in the acceptance checkbox.	Yes
`privacy`	URL to your Privacy Policy, shown in the acceptance checkbox.	Yes
`firstName`	Pre-fills the customer’s first name.	No
`lastName`	Pre-fills the customer’s last name.	No
`email`	Pre-fills the customer’s email.	No
`businessName`	Pre-fills the business name.	No
`ipAddress`	Pre-fills the end user’s IP address.	No
`correlationId`	Your identifier to correlate the customer to your system.	No

View all required vs. optional parameters in our API Reference.

CSS classes for customization

dwolla-customer-create,
dwolla-input-container,
dwolla-customer-input,
dwolla-customer-firstName,
dwolla-customer-lastName,
dwolla-customer-email,
dwolla-customer-tos,
dwolla-customer-checkbox,
dwolla-customer-text,
dwolla-submit,
dwolla-customer-submit,
dwolla-success,
dwolla-success-message,
dwolla-error,
dwolla-error-message

Preview

Create an Unverified Customer

dwolla-customer-create Renders a form that collects the minimal information needed to create an Unverified Customer: first name, last name, email, and optionally a business name. Add the isBusiness attribute to prompt for a business name. Use this for the lightest-weight customer record; you can upgrade them to a Verified Customer later. To find out more about the abilities and limitations of this customer type, visit our docs on concepts.