ACH Direct Debit

Server-side Implementation

Important

Your integration may be impacted by upcoming certificate changes. Visit our best practices guide to learn more..

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:

Ruby

result = gateway.payment_method.create(
    :customer_id => "131866",
    :payment_method_nonce => nonce_from_the_client,
    :options => {
        :us_bank_account_verification_method => "network_check" # or "micro_transfers" or "independent_check"
    }
)

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.

Ruby

result = gateway.payment_method.create(
    :customer_id => "131866",
    :payment_method_nonce => nonce_from_the_client,
    :options => {
        :us_bank_account_verification_method => "network_check",
        :verification_add_ons => "customer_verification"
    }
)

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:

Ruby

if result.success?
    us_bank_account = result.payment_method
    verified = result.verified
    response_code = us_bank_account.verifications.first.processor_response_code
    # ...
end

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:

Ruby

result = gateway.us_bank_account_verification.confirm_micro_transfer_amounts(
    verification_id_from_payment_method,
    [17, 29]
)
if result.success?
    # confirmation successful
else
    # confirmation failed
end

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:

Ruby

status = gateway.us_bank_account_verification.find(verification_id_from_payment_method).status
if (status == UsBankAccountVerification.Status.Verified) {
    # ready for transacting
} elseif (status == UsBankAccountVerification.Status.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 device_data_from_the_client in the transaction.

Ruby

result = gateway.transaction.sale(
    :amount => "10.00",
    :payment_method_token => token_from_vault,
    :device_data => device_data_from_the_client,
    :options => {
        :submit_for_settlement => true
    }
)
if result.success?
    # See result.transaction for details
else
    # Handle errors
end

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:

Ruby

result = gateway.payment_method.update(
    "the_token", 
    :options => {
        :us_bank_account_verification_method => UsBankAccountVerification.VerificationMethod.MicroTransfers
        # or "network_check" or "independent_check"
    }
)

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