> ## Documentation Index
> Fetch the complete documentation index at: https://developers.dwolla.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Drop-in Components

> Dwolla's Drop-in components are low-code solutions to alleviate the technical overhead of a payments integration to rapidly implement key functionality into an application.

## 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](https://github.com/Dwolla/react-drop-ins) 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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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).
  </Step>
</Steps>

## 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](https://github.com/Dwolla/drop-ins-examples) to view a list of all drop-in component examples.

<img src="https://mintcdn.com/dwolla/C9LuhBlLWlq2MFvM/assets/images/content-images/drop-in-upgrade-unverified-customer.png?fit=max&auto=format&n=C9LuhBlLWlq2MFvM&q=85&s=34f68724777dd45b4c3bc2ba4fb5fcda" alt="Upgrade a Customer Drop-in Component" width="1620" height="1183" data-path="assets/images/content-images/drop-in-upgrade-unverified-customer.png" />

## 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.

```html theme={"dark"}
<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](/docs/drop-in-components/building-with-drop-ins#step-1-setup-and-configuration).

## 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.

<Card title="Drop-in Components Guide" icon="book" href="/docs/drop-in-components/building-with-drop-ins">
  For more information on integrating drop-in components, reference our Guide which walks through how to use drop-in components in full detail.
</Card>

### Create a Receive Only User

<code>dwolla-customer-create</code>

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](/docs/customer-types) on concepts.

#### Usage

This assumes you've already called `dwolla.configure({ ... })` once during [setup](#setup).

```html theme={"dark"}
<dwolla-customer-create
  type="receive-only"
  terms="www.yourterms.com"
  privacy="www.yourprivacy.com"
>
</dwolla-customer-create>
```

<Accordion title="Full HTML page example">
  ```html theme={"dark"}
  <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>
  ```
</Accordion>

#### 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](/docs/api-reference/customers/create-a-customer).

<Accordion title="CSS classes for customization">
  ```css theme={"dark"}
  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
  ```
</Accordion>

<Accordion title="Preview">
  <img src="https://mintcdn.com/dwolla/rBVzublRFRC2NIA9/assets/images/content-images/drop-in-create-a-ro-user.png?fit=max&auto=format&n=rBVzublRFRC2NIA9&q=85&s=2c636728b76485b67e75d249b2dd5bcf" alt="Create a Receive Only User Drop-in Component" width="1290" height="986" data-path="assets/images/content-images/drop-in-create-a-ro-user.png" />
</Accordion>

### Create an Unverified Customer

<code>dwolla-customer-create</code>

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](#upgrade-an-unverified-customer) them to a Verified Customer later. To find out more about the abilities and limitations of this customer type, [visit our docs](/docs/customer-types#unverified-customer) on concepts.

#### Usage

This assumes you've already called `dwolla.configure({ ... })` once during [setup](#setup).

```html theme={"dark"}
<!-- Individual -->
<dwolla-customer-create
  terms="www.yourterms.com"
  privacy="www.yourprivacy.com"
>
</dwolla-customer-create>

<!-- Business (prompts for a business name) -->
<dwolla-customer-create
  terms="www.yourterms.com"
  privacy="www.yourprivacy.com"
  isBusiness
>
</dwolla-customer-create>
```

<Accordion title="Full HTML page example">
  ```html theme={"dark"}
  <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
        terms="www.yourterms.com"
        privacy="www.yourprivacy.com"
      >
      </dwolla-customer-create>
    </div>
  </body>
  ```
</Accordion>

#### Attributes

| Attribute       | Description                                                     | Required |
| --------------- | --------------------------------------------------------------- | -------- |
| `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      |
| `isBusiness`    | Prompts the user to enter a business name.                      | No       |
| `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](/docs/api-reference/customers/create-a-customer).

<Accordion title="CSS classes for customization">
  ```css theme={"dark"}
  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
  ```
</Accordion>

<Accordion title="Preview">
  <img src="https://mintcdn.com/dwolla/C9LuhBlLWlq2MFvM/assets/images/content-images/drop-in-create-a-customer.png?fit=max&auto=format&n=C9LuhBlLWlq2MFvM&q=85&s=dfe45b13cf095a8641e148948f9fc24d" alt="Create a Customer Drop-in Component" width="3013" height="1921" data-path="assets/images/content-images/drop-in-create-a-customer.png" />

  Unverified Customer with a business name:

  <img src="https://mintcdn.com/dwolla/C9LuhBlLWlq2MFvM/assets/images/content-images/drop-in-create-a-ucr-business.png?fit=max&auto=format&n=C9LuhBlLWlq2MFvM&q=85&s=bcf6ca3513f9fc58e8121c53fbcb5b35" alt="Create an Unverified Business Customer Drop-in Component" width="1478" height="1034" data-path="assets/images/content-images/drop-in-create-a-ucr-business.png" />
</Accordion>

### Upgrade an Unverified Customer

<code>dwolla-customer-update</code>

Renders a form that upgrades an existing **Unverified Customer** into a **Personal Verified Customer**, giving them higher transaction limits and the ability to hold a balance. Use this when a customer who started out unverified is ready to be fully verified. For more information on the difference between an Unverified and Verified Customer, [visit our docs](/docs/customer-types) on concepts.

#### Usage

This assumes you've already called `dwolla.configure({ ... })` once during [setup](#setup).

```html theme={"dark"}
<dwolla-customer-update
  customerId="{{ customerId }}"
  terms="www.yourterms.com"
  privacy="www.yourprivacy.com"
>
</dwolla-customer-update>
```

<Accordion title="Full HTML page example">
  ```html theme={"dark"}
  <head>
    <script src="//cdn.dwolla.com/v3.1.0/dwolla-web.js"></script>
    <link rel="stylesheet" href="/styles/upgrade-custom.css" />
    <script>
      dwolla.configure({
        environment: "sandbox",
        styles: "/styles/upgrade-custom.css",
        success: (res) => Promise.resolve(),
        error: (err) => Promise.resolve(),
        tokenUrl: "/tokenUrl",
      });
    </script>
  </head>

  <body>
    <div class="container">
      <dwolla-customer-update
        customerId="{{ customerId }}"
        terms="www.yourterms.com"
        privacy="www.yourprivacy.com"
      >
      </dwolla-customer-update>
    </div>
  </body>
  ```
</Accordion>

#### Attributes

| Attribute       | Description                                                     | Required |
| --------------- | --------------------------------------------------------------- | -------- |
| `customerId`    | ID of the Unverified Customer to upgrade.                       | 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       |
| `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](/docs/api-reference/customers/update-a-customer#update-unverified-and-receive-only).

<Accordion title="CSS classes for customization">
  ```css theme={"dark"}
  dwolla-customer-update,
  dwolla-input-container,
  dwolla-customer-input,
  dwolla-customer-firstName,
  dwolla-customer-lastName,
  dwolla-customer-email,
  dwolla-customer-address1,
  dwolla-customer-address2,
  dwolla-customer-city,
  dwolla-customer-state,
  dwolla-customer-postal,
  dwolla-customer-dob,
  dwolla-customer-ssn,
  dwolla-customer-tos,
  dwolla-customer-checkbox,
  dwolla-customer-text,
  dwolla-submit,
  dwolla-customer-submit,
  dwolla-success,
  dwolla-success-message,
  dwolla-error,
  dwolla-error-message
  ```
</Accordion>

<Accordion title="Preview">
  <img src="https://mintcdn.com/dwolla/C9LuhBlLWlq2MFvM/assets/images/content-images/drop-in-upgrade-unverified-customer.png?fit=max&auto=format&n=C9LuhBlLWlq2MFvM&q=85&s=34f68724777dd45b4c3bc2ba4fb5fcda" alt="Upgrade an Unverified Customer Drop-in Component" width="1620" height="1183" data-path="assets/images/content-images/drop-in-upgrade-unverified-customer.png" />
</Accordion>

### Create a Personal Verified Customer

<code>dwolla-personal-vcr</code>

Renders a form that collects the information needed to create a **Personal Verified Customer** — an individual who can send, receive, and hold a Dwolla balance. Use this to onboard a fully verified individual directly, without first creating an Unverified Customer and upgrading later. To learn more about the different customer types, [visit our docs](/docs/customer-types) on concepts.

<Tip>
  The same component also handles **updates, verification retries, and document uploads** for an existing customer — just pass a `customerId`. See [Update, retry, or upload documents](#update-retry-or-upload-documents) below.
</Tip>

#### Usage

This assumes you've already called `dwolla.configure({ ... })` once during [setup](#setup).

```html theme={"dark"}
<dwolla-personal-vcr
  terms="www.yourterms.com"
  privacy="www.yourprivacy.com"
>
</dwolla-personal-vcr>
```

<Accordion title="Full HTML page example">
  ```html theme={"dark"}
  <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-personal-vcr
        terms="www.yourterms.com"
        privacy="www.yourprivacy.com"
      >
      </dwolla-personal-vcr>
    </div>
  </body>
  ```
</Accordion>

#### Attributes

| Attribute       | Description                                                     | Required |
| --------------- | --------------------------------------------------------------- | -------- |
| `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      |
| `customerId`    | ID of an existing customer to update, retry, or document.       | No       |
| `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       |
| `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](/docs/api-reference/customers/create-a-customer).

#### Update, retry, or upload documents

The `dwolla-personal-vcr` component isn't limited to creating a new customer — pass an existing customer's `customerId` and the component checks their current [verification status](/docs/personal-verified-customer#handling-verification-statuses) and renders the right flow:

* **`retry`** — displays a form so the customer can correct and resubmit their identifying information.
* **`document`** — presents the document upload flow so the customer can upload an identifying document to complete verification.

```html theme={"dark"}
<dwolla-personal-vcr
  customerId="{{ customerId }}"
  terms="www.yourterms.com"
  privacy="www.yourprivacy.com"
>
</dwolla-personal-vcr>
```

<Accordion title="CSS classes for customization">
  ```css theme={"dark"}
  dwolla-input-container,
  dwolla-customer-input,
  dwolla-customer-firstName,
  dwolla-customer-lastName,
  dwolla-customer-email,
  dwolla-customer-address1,
  dwolla-customer-address2,
  dwolla-customer-city,
  dwolla-customer-state,
  dwolla-customer-postal,
  dwolla-customer-dob,
  dwolla-customer-ssn,
  dwolla-customer-tos,
  dwolla-customer-checkbox,
  dwolla-customer-text,
  dwolla-submit,
  dwolla-vcr-submit,
  dwolla-success,
  dwolla-success-message,
  dwolla-error,
  dwolla-error-message,
  dwolla-info,
  dwolla-info-message
  ```
</Accordion>

<Accordion title="Preview">
  <img src="https://mintcdn.com/dwolla/C9LuhBlLWlq2MFvM/assets/images/content-images/drop-in-create-a-pvc.png?fit=max&auto=format&n=C9LuhBlLWlq2MFvM&q=85&s=49c0dcff38717ab1d158abdd5a9a4012" alt="Create a Personal Verified Customer Drop-in Component" width="2008" height="1954" data-path="assets/images/content-images/drop-in-create-a-pvc.png" />
</Accordion>

### Create a Business Verified Customer

<code>dwolla-business-vcr</code>

Renders a form that collects the information needed to create a **Business Verified Customer**. Business Verified Customers can send and receive funds, hold a Dwolla balance, and have a transfer limit of `$10,000` per transfer. Use this to onboard a business entity. To learn more about the different customer types, [visit our docs](/docs/customer-types) on concepts.

<Tip>
  The same component also handles **updates, verification retries, and document uploads** for an existing customer — just pass a `customerId`. See [Update, retry, or upload documents](#update-retry-or-upload-documents-for-a-business-customer) below.
</Tip>

#### Usage

This assumes you've already called `dwolla.configure({ ... })` once during [setup](#setup).

```html theme={"dark"}
<dwolla-business-vcr
  terms="www.yourterms.com"
  privacy="www.yourprivacy.com"
>
</dwolla-business-vcr>
```

<Accordion title="Full HTML page example">
  ```html theme={"dark"}
  <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-business-vcr
        terms="www.yourterms.com"
        privacy="www.yourprivacy.com"
      >
      </dwolla-business-vcr>
    </div>
  </body>
  ```
</Accordion>

#### Attributes

| Attribute       | Description                                                     | Required |
| --------------- | --------------------------------------------------------------- | -------- |
| `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      |
| `customerId`    | ID of an existing customer to update, retry, or document.       | No       |
| `hideDBAField`  | Hides the "Doing Business As" field from the form.              | No       |
| `firstName`     | Pre-fills the controller's first name.                          | No       |
| `lastName`      | Pre-fills the controller's last name.                           | No       |
| `email`         | Pre-fills the customer's email.                                 | 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](/docs/api-reference/customers/create-a-customer).

#### Update, retry, or upload documents for a business customer

Like the Personal VCR component, the `dwolla-business-vcr` component can be reused for an existing customer — pass their `customerId` and the component checks the current [verification status](/docs/business-verified-customer#handling-retry-status) and renders the right flow:

* **`retry`** — displays a form so the customer can correct and resubmit the business and controller information.
* **`document`** — presents the document upload flow so the customer can upload the required identifying document(s) to complete verification.

```html theme={"dark"}
<dwolla-business-vcr
  customerId="{{ customerId }}"
  terms="www.yourterms.com"
  privacy="www.yourprivacy.com"
>
</dwolla-business-vcr>
```

<Accordion title="CSS classes for customization">
  ```css theme={"dark"}
  dwolla-input-container,
  dwolla-customer-input,
  dwolla-half-button,
  dwolla-half-button-secondary,
  dwolla-customer-firstName,
  dwolla-customer-lastName,
  dwolla-customer-email,
  dwolla-customer-address1,
  dwolla-customer-address2,
  dwolla-customer-city,
  dwolla-customer-state,
  dwolla-customer-country,
  dwolla-customer-postal,
  dwolla-customer-dob,
  dwolla-customer-ssn,
  dwolla-customer-tos,
  dwolla-customer-checkbox,
  dwolla-customer-text,
  dwolla-submit,
  dwolla-vcr-submit,
  dwolla-success,
  dwolla-success-message,
  dwolla-error,
  dwolla-error-message,
  dwolla-info,
  dwolla-info-message,
  dwolla-document-type,
  dwolla-document-type-select,
  dwolla-document-type-select-label,
  dwolla-document-choose,
  dwolla-document-chooser,
  dwolla-document-chooser-label,
  dwolla-file-name,
  dwolla-document-name-display,
  dwolla-document-name-span,
  dwolla-document-description,
  dwolla-document-label,
  dwolla-document-submit,
  dwolla-customer-businessIndustry,
  dwolla-customer-businessClassification,
  dwolla-customer-businessType,
  tooltip,
  tooltip.tooltiptext,
  tooltip-shift
  ```
</Accordion>

<Accordion title="Preview">
  <img src="https://mintcdn.com/dwolla/C9LuhBlLWlq2MFvM/assets/images/content-images/drop-in-business-verified-customer.png?fit=max&auto=format&n=C9LuhBlLWlq2MFvM&q=85&s=5473ead8a1e792d5c47522c9ab3487e6" alt="Create a Business Verified Customer Drop-in Component" width="530" height="401" data-path="assets/images/content-images/drop-in-business-verified-customer.png" />
</Accordion>

### Create Beneficial Owners

<code>dwolla-beneficial-owners</code>

Renders a form that collects the information needed to [add Beneficial Owners](/docs/business-verified-customer#step-3-adding-beneficial-owners) after a Business Verified Customer has been created. Use this to certify beneficial ownership; it can be paired with the [Business Verified Customer](#create-a-business-verified-customer) component or used on its own. To learn more about the different customer types, [visit our docs](/docs/customer-types) on concepts.

#### Usage

This assumes you've already called `dwolla.configure({ ... })` once during [setup](#setup).

```html theme={"dark"}
<dwolla-beneficial-owners customerId="{{ customerId }}">
</dwolla-beneficial-owners>
```

<Accordion title="Full HTML page example">
  ```html theme={"dark"}
  <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-beneficial-owners customerId="{{ customerId }}">
      </dwolla-beneficial-owners>
    </div>
  </body>
  ```
</Accordion>

#### Attributes

| Attribute    | Description                                                       | Required |
| ------------ | ----------------------------------------------------------------- | -------- |
| `customerId` | ID of the Business Verified Customer to add beneficial owners to. | Yes      |

View all required vs. optional parameters in our [API Reference](/docs/api-reference/beneficial-owners/create-beneficial-owner).

<Accordion title="CSS classes for customization">
  ```css theme={"dark"}
  dwolla-bo-submit,
  dwolla-document-submit,
  dwolla-customer-state,
  dwolla-customer-input,
  dwolla-customer-country,
  dwolla-width-1,
  dwolla-width-2,
  dwolla-width-3,
  dwolla-document-label,
  dwolla-document-type,
  dwolla-document-name,
  dwolla-document-name-display,
  dwolla-document-submit,
  dwolla-document-choose,
  dwolla-document-chooser,
  dwolla-document-description,
  dwolla-span-container,
  dwolla-file-name,
  dwolla-half-button,
  dwolla-half-button-secondary,
  dwolla-owner-name,
  dwolla-owner-delete,
  dwolla-owner-header,
  dwolla-owners-summary-container,
  dwolla-owners-empty,
  dwolla-add-owners-button,
  dwolla-owner,
  dwolla-owner-status,
  dwolla-owner-status-verified,
  dwolla-owner-status-incomplete,
  dwolla-owner-status-document,
  dwolla-button-label-container-nb,
  dwolla-button-label-container,
  dwolla-link,
  dwolla-customer-tos,
  dwolla-customer-checkbox,
  dwolla-customer-text,
  dwolla-text-container,
  dwolla-input-container,
  dwolla-loading
  ```
</Accordion>

<Accordion title="Preview">
  <img src="https://mintcdn.com/dwolla/C9LuhBlLWlq2MFvM/assets/images/content-images/drop-in-add-beneficial-owners.png?fit=max&auto=format&n=C9LuhBlLWlq2MFvM&q=85&s=bcb6c0c6195f88bbc0810f2e30f4c32d" alt="Add Beneficial Owners Drop-in Component" width="537" height="508" data-path="assets/images/content-images/drop-in-add-beneficial-owners.png" />
</Accordion>

### Document Upload

<code>dwolla-document-upload</code>

Renders a document upload form for a Verified Customer or Beneficial Owner who has a `document` status and needs to upload an identifying document to complete verification. Use this when a government-issued document is required to verify an individual or business's identity.

#### Usage

This assumes you've already called `dwolla.configure({ ... })` once during [setup](#setup).

```html theme={"dark"}
<dwolla-document-upload customerId="{{ customerId }}">
</dwolla-document-upload>
```

<Accordion title="Full HTML page example">
  ```html theme={"dark"}
  <head>
    <script src="//cdn.dwolla.com/v3.1.0/dwolla-web.js"></script>
    <link rel="stylesheet" href="/styles/document-custom.css" />
    <script>
      dwolla.configure({
        environment: "sandbox",
        styles: "/styles/document-custom.css",
        success: (res) => Promise.resolve(),
        error: (err) => Promise.resolve(),
        tokenUrl: "/tokenUrl",
      });
    </script>
  </head>

  <body>
    <div class="container">
      <dwolla-document-upload customerId="{{ customerId }}">
      </dwolla-document-upload>
    </div>
  </body>
  ```
</Accordion>

#### Attributes

| Attribute    | Description                                        | Required |
| ------------ | -------------------------------------------------- | -------- |
| `customerId` | ID of the customer who needs to upload a document. | Yes      |

View all required vs. optional parameters in our [API Reference](/docs/api-reference/documents/create-a-document-for-customer).

<Accordion title="CSS classes for customization">
  ```css theme={"dark"}
  dwolla-document-type,
  dwolla-document-type-select,
  dwolla-document-type-select-label,
  dwolla-document-chooser,
  dwolla-document-chooser-label,
  dwolla-document-name,
  dwolla-document-name-span,
  dwolla-document-submit
  ```
</Accordion>

<Accordion title="Preview">
  <img src="https://mintcdn.com/dwolla/C9LuhBlLWlq2MFvM/assets/images/content-images/drop-in-document-upload.png?fit=max&auto=format&n=C9LuhBlLWlq2MFvM&q=85&s=e8971c2104a9a718535876140d235a01" alt="Document Upload Drop-in Component" width="2960" height="1884" data-path="assets/images/content-images/drop-in-document-upload.png" />
</Accordion>

### Create a Funding Source

<code>dwolla-funding-source-create</code>

Renders a form that collects the information needed to create a [bank funding source](/docs/api-reference/funding-sources) attached to a [customer](/docs/api-reference/customers) record. Optionally, add the `initiateMicroDeposits` attribute to automatically [initiate micro-deposits](/docs/api-reference/funding-sources/initiate-or-verify-micro-deposits) when the funding source is created.

<Warning>
  This component currently does not support <a href="/docs/api-reference/transfers/create-an-on-demand-transfer-authorization"> on-demand authorization</a> when creating a funding source. Instead, if you wish to make use of this feature, the interaction between the API and the customer must happen outside of the drop-ins component library at this time.
</Warning>

#### Usage

This assumes you've already called `dwolla.configure({ ... })` once during [setup](#setup).

```html theme={"dark"}
<!-- Without automatic micro-deposit initiation -->
<dwolla-funding-source-create customerId="{{ customerId }}">
</dwolla-funding-source-create>

<!-- With automatic micro-deposit initiation -->
<dwolla-funding-source-create
  customerId="{{ customerId }}"
  initiateMicroDeposits
>
</dwolla-funding-source-create>
```

<Accordion title="Full HTML page example">
  ```html theme={"dark"}
  <head>
    <script src="//cdn.dwolla.com/v3.1.0/dwolla-web.js"></script>
    <link rel="stylesheet" href="/styles/create-funding-sources-custom.css" />
    <script>
      dwolla.configure({
        environment: "sandbox",
        styles: "/styles/create-funding-sources-custom.css",
        success: (res) => Promise.resolve(),
        error: (err) => Promise.resolve(),
        tokenUrl: "/tokenUrl",
      });
    </script>
  </head>

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

#### Attributes

| Attribute               | Description                                                                                             | Required |
| ----------------------- | ------------------------------------------------------------------------------------------------------- | -------- |
| `customerId`            | ID of the customer this funding source will attach to.                                                  | Yes      |
| `initiateMicroDeposits` | If present, micro-deposits are automatically initiated *if the funding source is created successfully*. | No       |

View all required vs. optional parameters in our [API Reference](/docs/api-reference/funding-sources/create-customer-funding-source).

<Accordion title="CSS classes for customization">
  ```css theme={"dark"}
  /* Input Form */
  .dwolla-input-container,
  .dwolla-funding-source-input,
  .dwolla-funding-source-name,
  .dwolla-funding-source-type,
  .dwolla-funding-source-routingNumber,
  .dwolla-funding-source-accountNumber,
  .dwolla-funding-source-submit

  /* Error Messaging */
  #dwolla-error,
  #dwolla-error-message

  /* Success Messaging */
  #dwolla-success,
  #dwolla-success-message
  ```
</Accordion>

<Accordion title="Preview">
  <img src="https://mintcdn.com/dwolla/C9LuhBlLWlq2MFvM/assets/images/content-images/drop-in-create-funding-source.png?fit=max&auto=format&n=C9LuhBlLWlq2MFvM&q=85&s=13a3679f8cb19634363b293b77157e98" alt="Create Funding Source Drop-In Component" width="1918" height="1428" data-path="assets/images/content-images/drop-in-create-funding-source.png" />
</Accordion>

### Verify Micro Deposits

<code>dwolla-micro-deposits-verify</code>

Renders a form that collects the micro-deposit amounts needed to verify a customer's [bank funding source](/docs/api-reference/funding-sources). Present this component once micro-deposits have successfully posted into the customer's bank funding source. Check out our guide on [verifying a bank with micro-deposits](/docs/micro-deposit-verification) for more information.

#### Usage

This assumes you've already called `dwolla.configure({ ... })` once during [setup](#setup).

```html theme={"dark"}
<dwolla-micro-deposits-verify
  customerId="{{ customerId }}"
  fundingSourceId="{{ fundingSourceId }}"
>
</dwolla-micro-deposits-verify>
```

<Accordion title="Full HTML page example">
  ```html theme={"dark"}
  <head>
    <script src="//cdn.dwolla.com/v3.1.0/dwolla-web.js"></script>
    <link rel="stylesheet" href="/styles/verify-micro-deposits.css" />
    <script>
      dwolla.configure({
        environment: "sandbox",
        styles: "/styles/verify-micro-deposits-custom.css",
        success: (res) => Promise.resolve(),
        error: (err) => Promise.resolve(),
        tokenUrl: "/tokenUrl",
      });
    </script>
  </head>

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

#### Attributes

| Attribute         | Description                                                      | Required |
| ----------------- | ---------------------------------------------------------------- | -------- |
| `customerId`      | ID of the customer the funding source belongs to.                | Yes      |
| `fundingSourceId` | ID of the funding source to which micro-deposits were initiated. | Yes      |

<Accordion title="CSS classes for customization">
  ```css theme={"dark"}
  /* Input Form */
  dwolla-input-container,
  dwolla-micro-deposits-input,
  dwolla-micro-deposits-amount-one,
  dwolla-micro-deposits-amount-two,
  dwolla-micro-deposits-submit,
  dwolla-loading,

  /* Success Messaging */
  dwolla-success,
  dwolla-success-message,

  /* Error Messaging */
  dwolla-error,
  dwolla-error-message,

  /* Info Messaging */
  dwolla-info,
  dwolla-info-message
  ```
</Accordion>

<Accordion title="Preview">
  <img src="https://mintcdn.com/dwolla/C9LuhBlLWlq2MFvM/assets/images/content-images/drop-in-verify-micro-deposits.png?fit=max&auto=format&n=C9LuhBlLWlq2MFvM&q=85&s=d107347ec9a1bccac48c1b3a8a39fe3f" alt="Verify Micro Deposits Drop-In Component" width="1076" height="731" data-path="assets/images/content-images/drop-in-verify-micro-deposits.png" />
</Accordion>

### Display a Verified Customer's Balance

<code>dwolla-balance-display</code>

Displays the Dwolla balance for a customer who already has one — a Personal Verified Customer or a Business Verified Customer. Add the `hideZeroBalance` attribute to suppress the display when the balance is `$0.00`.

#### Usage

This assumes you've already called `dwolla.configure({ ... })` once during [setup](#setup).

```html theme={"dark"}
<dwolla-balance-display customerId="{{ customerId }}">
</dwolla-balance-display>

<!-- Hide the balance when it is $0.00 -->
<dwolla-balance-display customerId="{{ customerId }}" hideZeroBalance>
</dwolla-balance-display>
```

<Accordion title="Full HTML page example">
  ```html theme={"dark"}
  <head>
    <script src="//cdn.dwolla.com/v3.1.0/dwolla-web.js"></script>
    <link rel="stylesheet" href="/styles/document-custom.css" />
    <script>
      dwolla.configure({
        environment: "sandbox",
        styles: "/styles/document-custom.css",
        success: (res) => Promise.resolve(),
        error: (err) => Promise.resolve(),
        tokenUrl: "/tokenUrl",
      });
    </script>
  </head>

  <body>
    <div class="container">
      <dwolla-balance-display customerId="{{ customerId }}">
      </dwolla-balance-display>
    </div>
  </body>
  ```
</Accordion>

#### Attributes

| Attribute         | Description                                                       | Required |
| ----------------- | ----------------------------------------------------------------- | -------- |
| `customerId`      | ID of the customer whose balance will be shown.                   | Yes      |
| `hideZeroBalance` | If present, the balance is not shown when it is equal to `$0.00`. | No       |

<Accordion title="CSS classes for customization">
  ```css theme={"dark"}
  dwolla-balance,
  dwolla-balance-display,
  dwolla-error
  ```
</Accordion>

<Accordion title="Preview">
  <img src="https://mintcdn.com/dwolla/C9LuhBlLWlq2MFvM/assets/images/content-images/drop-in-balance-display.png?fit=max&auto=format&n=C9LuhBlLWlq2MFvM&q=85&s=3d7a270c72d8e9ad6820e89514c3b84e" alt="Balance Display Drop-in Component" width="1603" height="1021" data-path="assets/images/content-images/drop-in-balance-display.png" />
</Accordion>

### Pay-In

<code>dwolla-payin</code>

Renders a connected flow for transferring funds from a customer's verified funding source into your own Dwolla Client funding source. The customer can be an Unverified, Personal Verified, or Business Verified Customer, and must already have a verified funding source.

To add and verify a funding source, you can:

* [Add a bank](#create-a-funding-source) with an account and routing number, then verify it with [micro-deposits](#verify-micro-deposits)
* Add and verify a bank with [Open Banking](/docs/open-banking)

#### Usage

This assumes you've already called `dwolla.configure({ ... })` once during [setup](#setup).

```html theme={"dark"}
<dwolla-payin
  customerId="{{ customerId }}"
  blob="{{ blob }}"
  token="{{ token }}"
></dwolla-payin>
```

<Accordion title="Full HTML page example">
  ```html theme={"dark"}
  <head>
    <script src="//cdn.dwolla.com/v3.1.0/dwolla-web.js"></script>
    <link rel="stylesheet" href="/styles/document-custom.css" />
    <script>
      dwolla.configure({
        environment: "sandbox",
        styles: "/styles/document-custom.css",
        success: (res) => Promise.resolve(),
        error: (err) => Promise.resolve(),
        tokenUrl: "/tokenUrl",
      });
    </script>
  </head>

  <body>
    <div class="container">
      <dwolla-payin
        customerId="{{ customerId }}"
        blob="{{ blob }}"
        token="{{ token }}"
      ></dwolla-payin>
    </div>
  </body>
  ```
</Accordion>

#### Attributes

| Attribute    | Description                                    | Required |
| ------------ | ---------------------------------------------- | -------- |
| `customerId` | ID of the customer sending funds.              | Yes      |
| `blob`       | Encrypted transfer payload provided by Dwolla. | Yes      |
| `token`      | Token used to authenticate the transfer.       | Yes      |
| `amount`     | Pre-fills the transfer amount.                 | No       |

<Accordion title="CSS classes for customization">
  ```css theme={"dark"}
  dwolla-payin,
  dwolla-payin-submit,
  dwolla-amount,
  dwolla-amount-label,
  dwolla-amount-display,
  dwolla-funding-sources-label,
  dwolla-funding-sources,
  dwolla-payin-title
  ```
</Accordion>

<Accordion title="Preview">
  <img src="https://mintcdn.com/dwolla/C9LuhBlLWlq2MFvM/assets/images/content-images/drop-in-pay-in.png?fit=max&auto=format&n=C9LuhBlLWlq2MFvM&q=85&s=3f6d38cfc11c35807172e649be06141e" alt="Pay In Drop-in Component" width="2435" height="1615" data-path="assets/images/content-images/drop-in-pay-in.png" />
</Accordion>

## Next steps

Leveraging Dwolla's UI Components library is a great way to expedite your integration with the Dwolla Platform by limiting the amount of custom code that you would be required to write.

Get started building with drop-in components by checking out the [getting started guide](/docs/drop-in-components) and the API Reference documentation.

## Changelog

### `v3.1.0` (Latest)

The latest version of **dwolla-web.js** is `3.1.0`. If you are currently using an earlier version, we recommend [upgrading](/docs/drop-in-components/building-with-drop-ins#step-1-setup-and-configuration) to `v3.1.0`.

* Enhanced multi-document verification for Business Verified Customers in the `<dwolla-business-vcr>` drop-in component.
  * Expanded support for "Doing Business As" (DBA) and combined controller and business document flows, so the upload UI presents all required document type options.
  * Improved verification tracking to evaluate each document by type against the customer's live status after every upload, so accepted documents no longer re-prompt and pending ones are not re-requested.
  * Added an uploaded-documents summary showing each document's type, verification status, and any failure reasons.
  * Added DBA-specific guidance when a "Doing Business As" document is requested.

### `v3.0.0`

* **BREAKING**: Added mandatory Terms of Service and Privacy Policy acceptance checkbox for Receive-Only customers in `<dwolla-customer-create>` drop-in component.
  * The `type="receive-only"` attribute now requires `terms` and `privacy` attributes to be provided.
  * Users must accept the Terms of Service and Privacy Policy before creating a Receive-Only customer (required for regulatory compliance).
  * Receive-Only customers display client's Terms of Service and Privacy Policy (not Dwolla's).
* Fixed duplicate `id` attributes in checkbox inputs across multiple drop-in components.

### `v2.2.2`

* Updated user hints and prompts for documentation upload screens to be correct and consistent throughout the following drop-in components:
  * `<dwolla-beneficial-owners>`
  * `<dwolla-business-vcr>`
  * `<dwolla-document-upload>`
  * `<dwolla-personal-vcr>`

### `v2.2.1`

* Renamed `Name` field to `Account Nickname` in `<dwolla-funding-source-create>` drop-in for clarity.

### `v2.2.0`

* Added `<dwolla-funding-source-create>` drop-in component.
* Added `<dwolla-micro-deposits-verify>` drop-in component.
* Updated `dwolla.configure` `token` callback function to receive `{ _links, action, links }`, rather than just `{ action, links }`. This will allow immediate pass-through without modification to the Dwolla API while maintaining backwards compatibility for existing implementations.
* Made `postalCode` optional in `<dwolla-business-vcr>` drop-in for Business Verified Customers with non-US controllers.

### `v2.1.9`

* Fixed `Submit` button double-click issue on customer creation drop-ins.
* Improve SSN field validation.
* Added optional `hideZeroBalance` attribute to `<dwolla-balance-display>` drop-in.
* Added new Account Opening drop-in `<dwolla-account-opening>`.

### `v2.1.8`

* Added optional `correlationId` field to `<dwolla-customer-create>`, `<dwolla-business-vcr>` and `<dwolla-personal-vcr>` drop-ins.
* Added optional `businessName` field to `<dwolla-customer-create>` drop-in.
* Added optional `hideDBAField` attribute to `<dwolla-business-vcr>` drop-in.
* Made `EIN` optional in the `<dwolla-business-vcr>` drop-in for Business Verified Customers of type Sole Proprietorship.
* All components are now flow-type components requiring multiple calls to the `client-tokens` endpoint for granularly scoped actions.
* Implemented hard-versioning of dwolla-web.js; to use the latest version, you will need to import the exact version rather than just the major version using the CDN script.

### `v2.1.6`

* Changed `success` callback response structure. In previous versions, upon successful creation of a resource, the `location` of the newly created resource is returned. In v2.1.6 and onwards, the success JSON response will contain a top-level `resource` and a `response` object with the location to the newly created resource.

```raw theme={"dark"}
# Used to be:
{
   "location":"https://api-sandbox.dwolla.com/customers/c81cf726-77ff-4a2a-bfde-1fb1fb90cefd"
}



# Changed to:
{
   "resource":"customers",
   "response":{
      "location":"https://api-sandbox.dwolla.com/customers/c81cf726-77ff-4a2a-bfde-1fb1fb90cefd"
   }
}
```