Client-side implementation

JavaScript v4

• Current Braintree SDKs
• Android v5
• iOS v7
• JavaScript v3
• Pre-release versions
• JavaScript v4
• Previous Versions
• Android v4
• iOS v6
• JavaScript v2

Implement ACH Direct Debit on your client to collect a customer's bank account information, verify it using one of three verification methods, and exchange it for a payment method nonce you can use to create transactions.

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 ACH overview, you must verify a customer's bank account information before you can transact on it. However, your verification workflow changes depending on which verification method you use. Learn more about the 3 available verification methods in our support articles.

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

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. By default, only account/routing number information is verified. If you want to also verify personal/business information, specify customer_verification under verification_add_ons.
5. Check the verification status on the payment method response object to determine whether the bank account was verified successfully
6. 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 using the API
   • Customers should see PAYPAL on their statement
   • You have up to 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 moves 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

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

Use 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/4.0.0-alpha.0/js/client.min.js"></script>
  <script src="https://js.braintreegateway.com/web/4.0.0-alpha.0/js/us-bank-account.min.js"></script>

Use CommonJS (Browserify or Webpack)

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

const client = require('braintree-web/client');
   const 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:

async function initializeUsBankAccount() {
     try {
       const clientInstance = await braintree.client.create({
         authorization: 'CLIENT-TOKEN-FROM-SERVER'
       });
       const usBankAccountInstance = await braintree.usBankAccount.create({
         client: clientInstance
       });
       // Use the usBankAccountInstance here.
       // ...
     } catch (err) {
       // Handle the component creation error.
     }
   }

If the promise resolves without an error, usBankAccountInstance is ready to use in the following steps.

Collect bank account information

After your component is ready, collect the required bank account information from the customer according to the verification method(s) you intend to use. For Network Check, Micro-Transfers, or Independent Check, the following bank account information is required:

• routingNumber
• accountNumber
• accountType (checking or savings)
• ownershipType (personal or business)
• firstName (if personal)
• lastName (if personal)
• businessName (if business)
• billingAddress

Use 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 to get fields from a form:

// ...

   async function collectBankDetails() {
     try {
       const usBankAccountInstance = await braintree.usBankAccount.create({
         client: clientInstance
       });
       // ...
       const bankDetails = {
         accountNumber: document.getElementById('account-number').value,
         routingNumber: document.getElementById('routing-number').value,
         accountType: document.querySelector('input[name="account-type"]:checked').value,
         ownershipType: document.querySelector('input[name="ownership-type"]:checked').value,
         billingAddress: {
           streetAddress: document.getElementById('billing-street-address').value,
           extendedAddress: document.getElementById('billing-extended-address').value,
           locality: document.getElementById('billing-locality').value,
           region: document.getElementById('billing-region').value,
           postalCode: document.getElementById('billing-postal-code').value
         }
       };

       if (bankDetails.ownershipType === 'personal') {
         bankDetails.firstName = document.getElementById('first-name').value;
         bankDetails.lastName = document.getElementById('last-name').value;
       } else {
         bankDetails.businessName = document.getElementById('business-name').value;
       }
       // ...
     } catch (err) {
       // Handle the error.
     }
   }

After this runs, bankDetails contains the values you need for tokenization.

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 button (for example, a Purchase or Complete button)
2. Pass the text back to us as mandateText when you tokenize the bank account information

Tokenize bank account information

Regardless of which verification method you use, after 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.

// ...

   async function tokenizeBankAccount() {
     try {
       const usBankAccountInstance = await braintree.usBankAccount.create({
         client: clientInstance
       });
       // Collect bankDetails.

       const tokenizedPayload = await usBankAccountInstance.tokenize({
         bankDetails: bankDetails,
         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.'
       });
       // Submit tokenizedPayload.nonce to your server as you would
       // other payment method nonces.
     } catch (err) {
       // Handle the error.
     }
   }

A successful call returns a tokenizedPayload object containing a nonce you can submit to your server.

Tokenize only exchanges the bank account information for a payment method nonce through Braintree. You'll need to trigger verification separately on your server.

Collect device data

We recommend including device data with all customer-initiated transactions to decrease the risk of fraud. For more information, see our guide on Device Data Collection.