Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.tesouro.com/llms.txt

Use this file to discover all available pages before exploring further.

The failure modes below are all on the external-bank-account side — internal bank accounts don’t have a verification step that can fail. Each scenario assumes the user has hit a wall in the linking flow and your support path needs to recover them.

​
Micro-deposits never arrived

Standard ACH timing is one to two business days. If three business days have passed and the user hasn’t seen them in their outside bank’s transactions, check in this order:
  1. Routing number is real and still active. The connect call rejects obviously malformed numbers but doesn’t catch stale or merged routing numbers. The ABA registry is the source of truth.
  2. The receiving account hasn’t closed at the outside bank. Users sometimes link an account they’ve already shut down.
  3. The receiving bank doesn’t filter low-value inbound ACH. A handful of regional banks and credit unions hold or reject sub-dollar credits. Confirm with the user’s bank if the first two look fine.
If verificationStatus is VERIFICATION_SENT and nothing arrived, the deposits aren’t reissued on the same external bank account record. Connect a new one and start over.

​
Validation amounts don’t match

Submitting wrong amounts to /validate returns a 400 and the external bank account stays in VERIFICATION_SENT for the user to retry. After the service-side cap on failed attempts, it moves to FAILED and a new external bank account is required. If the same numbers fail a second time on a fresh connection, two likely causes:
  • The receiving bank doesn’t accept ACH at all on that account type (some money-market and savings products are deposit-only or block ACH entirely).
  • The user is misreading the deposit amounts. Different banks group pending and posted activity differently, and small credits sometimes get bundled into a single line item. Have them log into the outside bank from a desktop browser, where activity is easier to read line by line.

​
The receiving bank returned the micro-deposits

When Tesouro receives an ACH return on the credit it sent, the external bank account moves to FAILED regardless of whether the user has submitted amounts yet. The return reason code is what’s actionable:
Return codeMeaningWhat the user should do
R02Account closedUse a different account.
R03No account / unable to locate at this numberReverify the account number with their bank.
R04Invalid account number structureReverify both the account and routing numbers.
R20Non-transaction account (savings without ACH access)Use a checking account or call the bank to enable ACH.

​
VERIFIED, but ACH still fails

Verification only proves the account existed and could receive a deposit at link time. A push or pull months later can still bounce — the account may have been closed since, the user may have set up authorization restrictions on their outside bank’s side, or the bank may have flagged the activity. Surface the return reason from the transfer’s ACH lifecycle. If the return code indicates the account is no longer valid (R02, R03, R04), have the user connect a fresh external bank account with current details. Don’t auto-retry against a FAILED external bank account — the next attempt will return the same way.