Select Language

Getting Started
Testing in the Sandbox
Generate an OAuth Access Token
Send Money to Users
Receive Money from Users
Transfer Money Between Users
Transfer Money Me-to-Me
Building With Drop-in Components
Customers
Create a Business Verified Customer
Create a Personal Verified Customer
Funding Sources
Add a Debit Card Using Dwolla-cards.js
Overview Step 1: Create a card funding sources token Step 2: Configure and call function Step 3: Handle JavaScript callback
Add a Bank Using Dwolla.js
Add a Bank Using Dwolla.js + IAV
Verify Bank with Micro-deposits
Add Bank via Dwolla + Plaid Integration
Webhooks
Working with Webhooks

Step 2: Configure and call function #

Once you've obtained a card funding source token, the next step is to complete the client-side implementation which starts with including dwolla-cards.js on the page you want the container to load and configuring the dwolla-cards.js library.

Including dwolla-cards.js

Begin the client-side implementation by including dwolla-cards.js in the HEAD of your HTML page.

html

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

Configure dwolla-cards.js

Configuration options are available for utilizing dwolla-cards.js in both our sandbox and production environments. Configuration of an environment should take place after you have included the dwolla-cards.js library.

javascript

// Sandbox
dwolla.configure("sandbox");

// Production
dwolla.configure("prod");

Options and customization #

There are a subset of options available for customizing the add a debit card form. The function dwolla.cards.start() takes in three arguments which includes the name of the id attribute which specifies a unique id for the HTML element, the cards funding sources token and options available for styling and customization of the form.

dwolla.cards.start()

ParamTypeValuecontainer ID namestringRepresents a string value container element ID where the add a debit card flow will render.tokenstringValue of single-use debit card funding sources token.optionsobjectAn object containing configurable options for style customization. Contains keys: stylesheets and styles.
stylesheets: represents an array list of stylesheets to load custom styles.
styles: Contains keys: default, success, failure, and buttonText. Includes customization of CSS properties such as text, color, padding, border, and more.

Dwolla-cards.js Example #

For this example, you'll pass the token you received from the previous step into 'token goes here' below. This input box can be a 'hidden' input. The only requirement is that there is an input with id="authTokenInput" that has the generated token assigned to its value. It will be used in the JavaScript function dwolla.cards.start. This token will be used to authenticate the request asking Dwolla to render the add a debit card flow.

Once your customer clicks "Add Card", your application will call dwolla.cards.start() passing in the following arguments:

The cardContainer element where the add a debit card flow will render
A string value of your single-use card funding source token
Any specified styling options

html

<html>
  <head>
    <script
      type="text/javascript"
      src="https://cdn-b.dwolla.com/1/dwolla-cards.js"
    ></script>
  </head>
  <body>
    <div>
      <span
        >Add a payment card so that you can start doing something today!</span
      >
      <div style="padding-bottom: 25px">
        <input
          type="text"
          placeholder="funding source token"
          id="authTokenInput"
          value="token goes here"
        />
        <input type="button" id="startButton" value="Add Card" />
        <div id="cardContainer"></div>
      </div>

      <div id="result"><span>Card has been added!</span></div>
      <script type="text/javascript">
        dwolla.configure("sandbox");
        document
          .getElementById("startButton")
          .addEventListener("click", (e) => {
            e.preventDefault();
            const token = document.getElementById("authTokenInput").value;
            dwolla.cards.start(
              "cardContainer",
              token,
              options
            )((err, res) => {
              console.log(err);
              console.log(res);
              document.getElementById("cardContainer").style.display = "none";
              document.getElementById("result").style.display = "block";
            });
          });
      </script>
    </div>
    <pre id="preview"></pre>
    <pre id="bin"></pre>
  </body>
</html>

Example styled form

Check out our blog post for an interactive code example on styling the debit card form.

Dwolla-cards.js Styling #

When you invoke the function to create the tokenized fields via dwolla-cards.js, you can pass in style options for placeholder, valid and invalid text. From here, you can style text-specific properties such as color, font-family, font-style and font-weight. These styles are applied to all fields.

Failure text is used for the format validation errors for the following:

Card number
Expiration date
Security code

Success text applies to format validation for the following:

Name and address fields
Card number
Expiration date
Security code

Note: Color cannot be specified for the placeholder text.

Using an External Style Sheet

You can also link an external style sheet to the form. While you can't adjust the font-specific properties of the placeholder, success or failure text via an external stylesheet, you can style container-specific properties.

Basic container-specific properties include the following:

Margin
Padding
Width
Height
Border

Example options object

javascript

const options = {
  stylesheets: ["styles.css"],
  styles: {
    // most CSS properties can be supplied to these objects
    default: {
      // placeholder text
      fontFamily: fontFamily,
      fontSize: fontSize,
      fontWeight: "normal",
    },
    success: {
      // valid input text
      color: "#1176BC",
      fontFamily: fontFamily,
      fontSize: fontSize,
      fontWeight: "bold",
    },
    error: {
      // invalid input text
      color: "#d9534f",
      fontFamily: fontFamily,
      fontSize: fontSize,
      fontWeight: "bold",
    },
    buttonText: "Go!",
  },
};

Styling the Card Name Input

The card name input isn't a tokenized field, so it doesn't apply font styles from the options. You will need to style this field manually to match the properties applied from the options and external CSS. You'll also need to supply the submit button and you're responsible for wiring it up to the dwolla-cards.js call.

To the left of the card number is an input. Once the card number is entered, it will change to the card brand name.

You can style this in your stylesheet via #brand. Key properties that can be adjusted include the following:

Color
Text color
Padding
Size
Border radius

Note: All of the inputs share a class name and each field has its own id.

Styling the Form Validation Errors

The form provides client-side form validation to ensure that users do not enter invalid data in the form-fields. The validation error messages are displayed in a <span> with class="cards-error-message". By default, the error message has a red text color. You can customize it in your stylesheet to match the look and feel of your application.

Here is the list of all possible form validation error messages:

Cardholder Name is required
Card Nickname is required
City is required
Invalid card number
Invalid expiration date
Invalid CVV
Street Address is required
State is required
Zip code is required

Step 1: Create a card funding sources token

Step 3: Handle JavaScript callback

Test in the Sandbox for free today.

Use sandbox environment to test API requests.

Get API Keys

Dwolla

Product

Developers

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.