ACH Direct Debit/Client-side Implementation

availability

ACH Direct Debit is available to eligible merchants. It's currently not available in our Drop-in UI.

On this page, we cover:

1. The basic workflow for each verification method
2. How to load and initialize the usBankAccount component on your client
3. How to collect customers’ bank account information based on the verification method(s) you intend to use
4. How to prove you have authorization to charge customers’ accounts
5. How to exchange the bank account information for a payment method nonce

In addition to completing your client implementation, be sure to follow the Server-side Implementation and Testing and Go Live portions of the guide, as well.

Workflows by verification method

As mentioned in the Overview, you must verify a customer's bank account information before you can transact on it. However, your verification workflow will change depending on which verification method is being used. Learn more about the 4 available verification methods in our support articles.

Most verification methods are triggered server-side and require you to store the bank account as a payment method in your Vault before a transaction can be created. If you attempt to create a one-time transaction with a payment method nonce representing an unverified bank account, the request will fail.

Unlike the verification methods triggered on the server side, tokenized checks are triggered client-side. Because tokenized checks require a bank login, the bank account is instantly verified by Plaid before a nonce is created, meaning the nonce itself represents a verified bank account. As such, you can use it immediately to create a one-time transaction. However, we still recommend creating a stored payment method so you can create future transactions on that bank account.

note

If you’d like to allow your customers to choose their preferred method, or if you’d like to present a backup verification method if the first attempt fails, you can implement multiple verification methods.

Network check

1. On your client side, prompt the customer to enter the required bank account information and consent to ACH Direct Debit transactions
2. Tokenize the bank account information to get a payment method nonce
3. On your server side, use the payment method nonce to save the bank account information as a payment method in your Vault and specify the verification method as network_check
4. Check the verification status on the payment method response object to determine whether the bank account was verified successfully
5. If the verification status is verified, create transactions as needed using the payment method token

Micro-transfers

1. On your client side, prompt the customer to enter the required bank account information and consent to ACH Direct Debit transactions
2. Tokenize the bank account information to get a payment method nonce
3. On your server side, use the payment method nonce to save the bank account information as a payment method in your Vault and specify the verification method as micro_transfers
   • This triggers the deposit of two sub-$1 amounts into the customer’s bank account, followed immediately by a single debit to reverse the deposits
4. In your UI, prompt the customer to enter the micro-deposit amounts they see in their bank account and then attempt confirmation via the API
   • Customers should see PAYPAL on their statement
   • We allow a maximum of 5 attempts to provide the correct amounts
5. On your server side, check the verification status on the payment method response object to determine whether the bank account was verified successfully
   • Verification status will move from pending to verified when all micro-transfer credits and debits have successfully settled and the customer has confirmed the amounts
6. If the verification status is verified, create transactions as needed using the payment method token

Tokenized check

1. On your client side, prompt the customer to enter the required bank account information and consent to ACH Direct Debit transactions
2. Tokenize the bank account information to trigger a bank login prompt for the customer and get a payment method nonce
   • This nonce will be transactable, unlike nonces created using other verification methods
3. On your server side, use the payment method nonce to create a one-time transaction or save the banking information as a payment method in your Vault

Independent check

1. On your client side, prompt the customer to enter the required bank account information and consent to ACH Direct Debit transactions
2. Tokenize the bank account information to get a payment method nonce
3. On your server side, save the banking information as a payment method in your Vault using the payment method nonce and specify the verification method as independent_check
   • This automatically sets the payment method’s verification status to verified
4. Create transactions as needed using the payment method token

Load the component

Using direct links

If you're integrating with <script> tags, you can load the usBankAccount component just like the required client component:

<script src="https://js.braintreegateway.com/web/3.57.0/js/client.min.js"></script>
<script src="https://js.braintreegateway.com/web/3.57.0/js/us-bank-account.min.js"></script>

Using CommonJS (Browserify or Webpack)

You can require the us-bank-account module just like the client module:

var client = require('braintree-web/client');
var usBankAccount = require('braintree-web/us-bank-account');

// ...

Initialize the component

Every Braintree.js component requires a Client, and the usBankAccount component is no exception. Create a usBankAccountInstance like this:

braintree.client.create({
  authorization: 'CLIENT_TOKEN_FROM_SERVER'
}, function (clientErr, clientInstance) {
  if (clientErr) {
    console.error('There was an error creating the Client.');
    throw clientErr;
  }

  braintree.usBankAccount.create({
    client: clientInstance
  }, function (usBankAccountErr, usBankAccountInstance) {
    if (usBankAccountErr) {
      console.error('There was an error creating the USBankAccount instance.');
      throw usBankAccountErr;
    }

    // Use the usBankAccountInstance here.
    // ...
  });
});

Collect bank account information

Once your component is ready, collect the required bank account information from the customer according to the verification method(s) you intend to use.

Using network check, micro-transfers, or independent check

To create a transaction with this information, you'll need to exchange the bank details for a payment method nonce using the tokenize method. Here's an example that uses jQuery to get fields from a form:

// ...

braintree.usBankAccount.create({
  client: clientInstance
}, function (usBankAccountErr, usBankAccountInstance) {
  // ...
  var bankDetails = {
    accountNumber: $('#account-number').val(),
    routingNumber: $('#routing-number').val(),
    accountType: $('input[name="account-type"]:checked').val(),
    ownershipType: $('input[name="ownership-type"]:checked').val(),
    billingAddress: {
      streetAddress: $('#billing-street-address').val(),
      extendedAddress: $('#billing-extended-address').val(),
      locality: $('#billing-locality').val(),
      region: $('#billing-region').val(),
      postalCode: $('#billing-postal-code').val()
    }
  };

  if (bankDetails.ownershipType === 'personal') {
    bankDetails.firstName = $('#first-name').val();
    bankDetails.lastName = $('#last-name').val();
  } else {
    bankDetails.businessName = $('#business-name').val();
  }
  // ...
});

Using tokenized check

This UI is also triggered with the tokenize method. Here's an example that uses jQuery to trigger the flow:

// ...

braintree.usBankAccount.create({
  client: clientInstance
}, function (usBankAccountErr, usBankAccountInstance) {
  // ...

  $('#bank-login-button').on('click', function (event) {
    event.preventDefault();

    var bankLogin = {
      displayName: 'My Merchant',
      ownershipType: $('input[name="ownership-type"]:checked').val(),
      billingAddress: {
        streetAddress: $('#billing-street-address').val(),
        extendedAddress: $('#billing-extended-address').val(),
        locality: $('#billing-locality').val(),
        region: $('#billing-region').val(),
        postalCode: $('#billing-postal-code').val()
      }
    };

    if (bankLogin.ownershipType === 'personal') {
      bankLogin.firstName = $('#first-name').val();
      bankLogin.lastName = $('#last-name').val();
    } else {
      bankLogin.businessName = $('#business-name').val();
    }
    // ...
  });
});

Show required authorization language

For all ACH transactions, you are required to collect a mandate or “proof of authorization” from the customer to prove that you have their explicit permission to debit their bank account. We facilitate this requirement by storing the mandate text for you and providing it directly to banks if required, as long as you do both of the following:

1. Include the exact text shown below as part of your checkout flow, at or near the final “buy” (purchase, complete, etc.) button.
2. Pass the text back to us as mandateText when you tokenize the bank account information

important

The explicit language you must include is:

By clicking ["Checkout"], I authorize Braintree, a service of PayPal, on behalf of [your business name here] (i) to verify my bank account information using bank information and consumer reports and (ii) to debit my bank account.

Tokenize bank account information

Regardless of which verification method you use, once you’ve collected the required bank account information, the next step is to tokenize it in exchange for a payment method nonce.

The tokenize call is also where you should pass the required mandateText that you displayed to the customer in your UI.

// ...

braintree.usBankAccount.create({
  client: clientInstance
}, function (usBankAccountErr, usBankAccountInstance) {
  // Collect bankDetails or bankLogin.

  usBankAccountInstance.tokenize({
    bankDetails: bankDetails, // or bankLogin: bankLogin
    mandateText: 'By clicking ["Checkout"], I authorize Braintree, a service of PayPal, on behalf of [your business name here] (i) to verify my bank account information using bank information and consumer reports and (ii) to debit my bank account.'
  }, function (tokenizeErr, tokenizedPayload) {
    if (tokenizeErr) {
      console.error('There was an error tokenizing the bank details.');
      throw tokenizeErr;
    }

    // Submit tokenizedPayload.nonce to your server as you would
    // other payment method nonces.
  });
});

note

• Tokenizing bank account information means exchanging any bank account information for a payment method nonce.
• Tokenized check means verifying the bank account information using the bankLogin method.

If you’re using the tokenized check verification method, tokenize will both trigger the verification through Plaid and exchange the bank account information for a payment method nonce through Braintree.

If you’re using any other verification method, tokenize will only exchange the bank account information for a payment method nonce through Braintree. You’ll need to trigger verification separately on your server.

Next Page: Server-side →