ACH Direct Debit

Client-side Implementationanchor

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 methodanchor

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

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 checkanchor

  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 will be verified. If you want to additionally 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
important

If the verification status is PROCESSOR_DECLINED with Processor Response Codes 2046 or 2092, you must deliver the following message to consumers:

Sorry, the bank account was not charged but you may still complete this transaction with an alternative account or payment method. This transaction was declined based, at least in part, on consumer reporting data obtained from Giact Systems, LLC. Giact did not make the decision to decline this transaction and is unable to provide the specific reasons why the transaction was declined. You have the right to obtain a free copy of your consumer report from Giact if you make a request within 60 days and you have the right to dispute the accuracy or completeness of the information with Giact by contacting them:

Giact Systems, LLC

700 Central Expy. S, Suite 300

Allen, TX 75013

1-866-918-2409

Micro-transfersanchor

  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

Independent checkanchor

  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 componentanchor

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

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

Using CommonJS (Browserify or Webpack)anchor

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

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

Initialize the componentanchor

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

  1. Callback
  2. Promise
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 informationanchor

Once 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

Using network check, micro-transfers, or independent checkanchor

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:

  1. Callback
  2. Promise
// ...

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();
  }
  // ...
});

Show required authorization languageanchor

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 for different use-cases is provided below:

To support a recurring payment with different amounts:

By clicking [“Checkout/Submit”], I authorize Braintree, a service of PayPal, on behalf of [your business name here] to verify my bank account information using bank information and consumer reports and I authorize [your business name here] to initiate an ACH/electronic debit to my checking/savings account, Depository Name: <>, Routing Number:<> and Account Number:<>, that will be stored on file, and debited on or after the due date. I agree the ACH transactions I authorize comply with all applicable laws.

I understand that this authorization will remain in full force and effect until I notify [your business name here] that I wish to revoke this authorization.

To support a One-time payment:

By clicking [“Checkout/Submit”], I authorize Braintree, a service of PayPal, on behalf of [your business name here] to verify my bank account information using bank information and consumer reports and I authorize [your business name here] to initiate an ACH/electronic debit to my checking/savings account, Depository Name: <>, Routing Number:<> and Account Number:<> , in the amount of <$XXX> on <date>. I agree the ACH transactions I authorize comply with all applicable laws.

Tokenize bank account informationanchor

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.

  1. Callback
  2. Promise
// ...

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

  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.'
  }, 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.

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.

Device data collectionanchor

It is recommended that all customer-initiated transactions include device data to decrease the risk of fraud. For more information, see our guide on Device Data Collection.


Next Page: Server-side →