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 flowsAnchorIcon

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

Network checkAnchorIcon

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

You may also find it useful to:

Micro-transfersAnchorIcon

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

You may also find it useful to:

Independent checkAnchorIcon

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

You may also find it useful to set up webhooks.

Vaulting the payment methodAnchorIcon

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:

  1. Python
result = gateway.payment_method.create({
    "customer_id": "131866",
    "payment_method_nonce": nonce_from_the_client,
    "options": {
        "us_bank_account_verification_method": UsBankAccountVerification.VerificationMethod.NetworkCheck # or MicroTransfers or IndependentCheck
    }
})

Verification Add OnsAnchorIcon

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.

  1. Python
result = gateway.payment_method.create({
    "customer_id": "131866",
    "payment_method_nonce": nonce_from_the_client,
    "options": {
        "us_bank_account_verification_method": UsBankAccountVerification.VerificationMethod.NetworkCheck,
        "verification_add_ons": UsBankAccountVerification.VerificationAddOn.CustomerVerification
    }
})

Checking for successful verificationAnchorIcon

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:
  1. Python
if result.is_success:
    us_bank_account = result.payment_method
    verified = us_bank_account.verified
    response_code = us_bank_account.verifications[0].processor_response_code
    # ...
If the payment method has been marked on any attempt, it will be transactable – even if subsequent verification attempts fail.

Confirming micro-deposit amountsAnchorIcon

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:
  1. Python
result = gateway.us_bank_account_verification.confirm_micro_transfer_amounts(
    verification_id_from_payment_method,
    [17, 29]
)
if (result.is_success):
    # confirmation successful
else:
    # confirmation failed
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 statusAnchorIcon

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:
  1. Python
status = gateway.us_bank_account_verification.find(verification_id_from_payment_method);

if status == UsBankAccountVerification.Status.Verified:
    # ready for transacting
elif status == UsBankAccountVerification.Status.Pending:
    # continue waiting
else:
    # verification failed
See retrying verifications for details on how to proceed if micro-transfers verification fails.

Creating transactionsAnchorIcon

From payment method tokensAnchorIcon

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.
  1. Python
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.is_success:
    # See result.transaction for details
else:
    # Handle errors

Retrying verificationsAnchorIcon

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:
  1. Python
result = gateway.payment_method.update("the_token", {
    "options": {
        "us_bank_account_verification_method": UsBankAccountVerification.VerificationMethod.MicroTransfers # or NetworkCheck or IndependentCheck
    }
})
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 webhooksAnchorIcon

Note
This step is applicable to all verification methods.
You can set up webhooks to notify you of changes in status to ACH transactions.

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more