ACH Direct Debit
Client-side Implementation
On this page, we cover:
- The basic workflow for each verification method
- How to load and initialize the usBankAccount component on your client
- How to collect customers' bank account information based on the verification method(s) you intend to use
- How to prove you have authorization to charge customers' accounts
- 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 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.
Network check
- On your client side, prompt the customer to enter the required bank account information and consent to ACH Direct Debit transactions
- Tokenize the bank account information to get a payment method nonce
- 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
- 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.
- Check the verification status on the payment method response object to determine whether the bank account was verified successfully
- If the verification status is verified, create transactions as needed using the payment method token
Micro-transfers
- On your client side, prompt the customer to enter the required bank account information and consent to ACH Direct Debit transactions
- Tokenize the bank account information to get a payment method nonce
- 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
- 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
- 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
- If the verification status is verified, create transactions as needed using the payment method token
Independent check
- On your client side, prompt the customer to enter the required bank account information and consent to ACH Direct Debit transactions
- Tokenize the bank account information to get a payment method nonce
- 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
- 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:
- HTML
<script src="https://js.braintreegateway.com/web/3.109.0/js/client.min.js"></script>
<script src="https://js.braintreegateway.com/web/3.109.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:
- JavaScript
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:
- Callback
- 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 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. 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 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:
- Callback
- 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 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:
- Include the exact text shown below as part of your checkout flow, at or near the final “buy” (purchase, complete, etc.) button.
- 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, 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.
- Callback
- 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.
});
});
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 collection
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 →