ACH Direct Debit

Server-side Implementation

GraphQL

Click here to view the server-side implementation using GraphQL.

Availability

ACH Direct Debit is available to eligible merchants who can implement a custom client-side integration using our JavaScript v3 SDK. It's currently not available in our Drop-in UI.

Server-side flows

Your server-side implementation depends on the verification method(s) you intend to use:

Network check

Vault the payment method using the payment method nonce from your client
Check for successful verification
Create transactions using the vaulted payment method token

You may also find it useful to:

Micro-transfers

Vault the payment method using the payment method nonce from your client
Confirm micro-deposit amounts
Periodically look up the verification's status
Create transactions using the vaulted payment method token

You may also find it useful to:

Independent check

Vault the payment method using the payment method nonce from your client
Create transactions using the vaulted payment method token

You may also find it useful to set up webhooks.

Vaulting the payment method

Note

This step is required in order to verify the payment method and begin transacting on it.

Call Payment Method: Create to specify the verification method (network check, micro-transfers, or independent check) and store the bank account information as a payment method in your Vault:

Callback

Promise

gateway.paymentMethod.create({
    customerId: "131866",
    paymentMethodNonce: nonceFromTheClient,
    options: {
        usBankAccountVerificationMethod: braintree.UsBankAccountVerification.VerificationMethod.NetworkCheck // or MicroTransfers or IndependentCheck
    }
}, (err, result) => { });

Verification Add Ons

Note

This step is optional and only applies to network check verifications.

For additional personal/business information verification, specify customer_verification under verification_add_ons.

Callback

Promise

gateway.paymentMethod.create({
    customerId: "131866",
    paymentMethodNonce: nonceFromTheClient,
    options: {
        usBankAccountVerificationMethod: braintree.UsBankAccountVerification.VerificationMethod.NetworkCheck,
        verificationAddOns: braintree.UsBankAccountVerification.VerificationAddOns.CustomerVerification
    }
}, (err, result) => { });

Checking for successful verification

Note

This step is required when using the network check method.

Upon vaulting a bank account, the result object will indicate whether the payment method was vaulted or not. However, the successful vaulting call does not mean that the bank account has been verified. The result must be further examined to determine the verification status of the bank account. This will typically involve looking at the overall verification status, but you may also want to inspect the most recent verification's processor response code:

Node

if (result.success) {
    const usBankAccount = result.paymentMethod;
    const verified = usBankAccount.verified;
    const responseCode = usBankAccount.verifications[0].processorResponseCode;
    // ...
}

If the payment method has been marked on any attempt, it will be transactable – even if subsequent verification attempts fail.

Confirming micro-deposit amounts

Note

This step is required when using the micro-transfers method. Until micro-deposit amounts are confirmed, the vaulted bank account will not be verified or transactable.

If using micro-transfers, you’ll need to collect the micro-deposit amounts entered by the customer in your own UI and pass them to Braintree in a separate call.

This example shows how to specify micro-deposit amounts of $0.17 and $0.29:

Callback

Promise

gateway.usBankAccountVerification.confirmMicroTransferAmounts(
    verificationIdFromPaymentMethod,
    [17, 29],
    (err, response) => { }
);

Micro-transfers will not be verified immediately upon creation. They must go through the above confirmation and wait for the transfers to settle before they get marked as verified.

Looking up individual verification status

Note

This step is required when using the micro-transfers method.

After successfully confirming micro-deposit amounts, the verification may be ready for transacting, still waiting for transfers to settle, or may eventually report that settlement failed. You can periodically check the state of the verification as follows:

Callback

Promise

gateway.usBankAccountVerification.find(verificationId, (err, verification) => {
    const status = verification.status;
    if (status == UsBankAccountVerification.StatusType.Verified) {
        // ready for transacting
    } else if (status == UsBankAccountVerification.StatusType.Pending) {
        // continue waiting
    } else {
        // verification failed
    }
});

See retrying verifications for details on how to proceed if micro-transfers verification fails.

Creating transactions

From payment method tokens

Note

This step is applicable to all verification methods.

Like all Braintree SDK integrations, you will receive a payment method token when you successfully execute Payment Method: Create on a nonce created from your customer's payment information. Pass the token to your server, and create a transaction.

Collect device data from the client and include the deviceDataFromTheClient in the transaction.

Callback

Promise

gateway.transaction.sale({
    amount: "10.00",
    paymentMethodToken: tokenFromVault,
    deviceData: deviceDataFromTheClient,
    options: {
        submitForSettlement: true
    }
}, (err, result) => {
    if (result.success) {
        // See result.transaction for details
    } else {
        // Handle errors
    }
});

Retrying verifications

Note

This step is applicable to the network check and micro-transfer methods.

In case one verification method fails (e.g. due to false negatives or missing data), you may want to employ a backup verification method. For instance, if you use network check and receive a response of 1003 - Approved with Risk or 2092 - No Data Found - Try Another Verification Method, you can try another verification method like micro-transfers or independent check.

Although micro-transfers take the longest to complete, they have the highest chance of success and work well as a backup method. If the customer is able to provide a voided check or other manual form of verification, independent check can be a quick and easy alternative, too.

You can retry verification on a previously-stored payment method any number of times, using either the same verification method or a different verification method. This example shows how to attempt a micro-transfers verification on a payment method you've already vaulted and attempted to verify before:

Callback

Promise

gateway.paymentMethod.update("theToken", {
    options: {
        usBankAccountVerificationMethod: UsBankAccountVerification.VerificationMethod.MicroTransfers // or NetworkCheck or IndependentCheck
    }
}, (err, result) => {
    // handle result
});

Note

You can't change the details of a vaulted US Bank Account payment method using Payment Method: Update. If you need to retry verification with new bank account information, create a new payment method.

Setting up webhooks

Note

This step is applicable to all verification methods.

You can set up webhooks to notify you of changes in status to ACH transactions.

See the webhooks guide for details on how to configure webhooks in general
See the Transaction webhooks reference for details on the specific notifications available for sales and refunds