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 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.
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
- 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
- Customers should see
- 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
toverified
when all micro-transfer credits and debits have successfully settled and the customer has confirmed the amounts
- Verification status will move from
- If the verification status is
verified
, create transactions as needed using the payment method token
Tokenized 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 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
- 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
- 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
- This automatically sets the payment method’s verification status to
- 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.73.1/js/client.min.js"></script>
<script src="https://js.braintreegateway.com/web/3.73.1/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.
Required bank account information | |
---|---|
Network Check Micro-Transfers Independent Check |
Tokenized Check |
|
|
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:
- 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.
// ...
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.
});
});
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.
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.