Manual ACH Instrument Verification

This quickstart guides you through the process of manually verifying a customer's ACH instrument. If you have Plaid enabled, most popular banks will be verified automatically when an ACH instrument is first created. However, if the customer's bank is not supported, or instant verification fails, the instrument must be verified manually.

Manual ACH instrument verification is a delayed-verification process that involves sending microdeposits to the customer's account. These deposits typically take 1-2 business days to appear and your customer will need to forward the values of the microdeposits back to your service.

Your customer will need to search their deposit statements for items with a description that includes AMTS. For security reasons, there is a limit of 10 failed verification attempts and, once this threshold is exceeded, the bank will no longer accept verification requests. Clear communication to customers around microdeposits is essential to avoiding any problems.

In five minutes, learn how to:

  1. Create an ACH instrument
  2. Verify an ACH instrument using the Instrument Verification API

Presumptions:

  1. You have reviewed the RevOps Accounts and Instruments APIs
  2. You have developer credentials in RevOps and access to your API key. If not, talk to your admin.

Step 1: Create a new ACH instrument for an existing customer

Creating an ACH instrument

The following example illustrates how to create a new ACH instrument for an existing account using the Instruments API. After the ACH instrument is created, you can ask your customer to check their bank deposit statements after 1-2 business days.

$> curl  https://vault.revops.io/v1/accounts/acct_<id>/instruments \
        -X POST \
        -H 'Authorization: Bearer <public_key>' \
        -H 'Content-type: application/json' \
        -d '{"method": "ach", "account_id" : "acct_<id>", "holder_name" : "Account Holder", "is_individual" : true, "bank_name": "Bank Name", "account_number" : "000123456789", "routing_number" : "110000000", "country" : "USA", "currency" : "USD", "email" : "customer@email.com" }'

Here is the same example in python.

from uuid import uuid4
import urllib.request
import json

api_key = "sk_sandbox_<yourkey>"
api_url = "https://vault.revops.io/v1/accounts/acct_<id>/instruments"

instrument = {
   'method': 'ach',
   'account_id' : 'acct_<id>',
   'bank_name' : 'Bank Name',
   'holder_name' : 'Account Holder',
   'is_individual' : True,
   'account_number' : '000123456789',
   'routing_number' : '110000000',
   'country' : 'USA',
   'currency' : 'USD',
   'email' : 'customer@email.com',
}

data = json.dumps(instrument).encode('utf8')

request = urllib.request.Request(
  api_url,
  method='POST',
  data=data,
  headers={
    'Content-type': 'application/json',
    'Authorization': "Bearer {}".format(api_key),
  },
)
try:
    with urllib.request.urlopen(request) as response:
        json_response = response.read().decode('utf-8')
        print(json.loads(json_response))
except urllib.error.HTTPError as httperror:
    print(httperror.read().decode('utf-8'))

Step 2: Collect microdeposit information

After an ACH instrument has been created, the delayed-verification process will automatically be kicked off. Communicate to your customer that they will need to check their bank deposit statements for items with a description that includes AMTS. The following as an example of microdeposits showing up in an example bank account:

Microdeposits

Step 3: Send microdeposit information to RevOps

After the microdeposits have shown up in the bank statement and have been provided to your service, you can forward the amount information to RevOps. Using the unique instrument identifier created in the previous step, send the microdeposit information to the instrument verification endpoint.

You have now successfully performed manual ACH verification!

$> curl  https://vault.revops.io/v1/accounts/<acct_id>/instruments/<inst_id>/verify \
        -X POST \
        -H 'Authorization: Bearer <secret_key>' \
        -H 'Content-type: application/json' \
        -d '{"method": "ach", "amounts": [32, 45]}'
from uuid import uuid4
import urllib.request
import json

api_key = "sk_sandbox_<yourkey>"
api_url = "https://vault.revops.io/v1/accounts/acct_<id>/instruments/inst_id/verify"

verification = {
   'method': 'ach',
   'amounts': [32, 45],
}

data = json.dumps(verification).encode('utf8')

request = urllib.request.Request(
  api_url,
  method='POST',
  data=data,
  headers={
    'Content-type': 'application/json',
    'Authorization': "Bearer {}".format(api_key),
  },
)
try:
    with urllib.request.urlopen(request) as response:
        json_response = response.read().decode('utf-8')
        print(json.loads(json_response))
except urllib.error.HTTPError as httperror:
    print(httperror.read().decode('utf-8'))

Next Steps

Now that we have an understanding of how manual ACH verification works. You can now review the Instruments ACH Testing guide for instructions on testing specific failure cases.

Next: Testing Instruments Guide