ACH Direct Debit

Server-side Implementationanchor

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 flowsanchor

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

Network checkanchor

  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-transfersanchor

  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 checkanchor

  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 methodanchor

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. 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 Onsanchor

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. 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 verificationanchor

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. 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 VERIFIED on any attempt, it will be transactable – even if subsequent verification attempts fail.

Confirming micro-deposit amountsanchor

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. 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 statusanchor

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. Ruby
status = gateway.us_bank_account_verification.find(verification_id_from_payment_method).status
if (status == UsBankAccountVerification.Status.Verified)
  # ready for transacting
elsif (status == UsBankAccountVerification.Status.Pending)
  # continue waiting
else
  # verification failed
end

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

Creating transactionsanchor

From payment method tokensanchor

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. 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 verificationsanchor

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. 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 webhooksanchor

This step is applicable to all verification methods.

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


Next Page: Testing and Go Live →