Merge pull request #91788 from Expensify/claude-bankAccountValidationEdgeCases

[No QA] Add bank account validation & wallet troubleshooting edge cases

Author: stephanieelliott

cspell.json

@@ -163,6 +163,7 @@
         "IHDR",
         "INTECOMS",
         "IPHONEOS",
+        "ITIN",
         "ITSM",
         "Idology",
         "Inactives",

docs/articles/expensify-classic/bank-accounts-and-payments/bank-accounts/Troubleshooting-business-bank-account-setups.md

@@ -1,7 +1,7 @@
 ---
 title: Troubleshooting business bank account setup
 description: Fix common errors when adding or verifying a verified business bank account in Expensify.
-keywords: [bank account troubleshooting, verified business account, Onfido error, missing test transactions, ACH whitelisting, ID upload issues, missing verification amounts, missing micro deposits]
+keywords: [bank account troubleshooting, verified business account, Onfido error, missing test transactions, ACH whitelisting, ID upload issues, missing verification amounts, missing micro deposits, validation failed, test deposits wrong, Fix button missing, Unlock button missing, bank account pending, verification stuck, documentation review]
 ---
 <div id="expensify-classic" markdown="1">
 
@@ -99,4 +99,46 @@ Yes. Expensify cannot process payments for:
 
 If your business operates in one of these industries, you may not be able to use Expensify for payments.
 
+---
+
+# Troubleshooting Test Transaction Validation
+
+## I entered the correct test transaction amounts but validation failed
+
+If you can see the test transactions in your bank account but the amounts are being rejected:
+
+- **Wait for transactions to fully post.** Pending transactions may display slightly different amounts than the final posted values. Only enter amounts after they have fully posted.
+- **Double-check for rounding.** Enter the exact amounts including cents. Even a one-cent difference will cause validation to fail.
+- **Verify you have the right transactions.** Look for transactions labeled "Expensify, Inc. Validation" or similar. If you have multiple bank accounts connected, make sure you are not mixing up transactions from different accounts.
+
+If you have confirmed all of the above and validation still fails, contact Concierge for assistance.
+
+## Validation is temporarily locked after multiple failed attempts
+
+Entering incorrect amounts multiple times will temporarily lock the validation process. The lock typically lasts a few hours. After the lock period, retry by navigating to your bank account in **Settings > Account > Payments** and clicking the pending bank account.
+
+If you are unable to validate after the lock period has passed, contact Concierge.
+
+## Test transactions expired or validation window closed
+
+Test transactions and the validation window are active for a limited time. If you did not complete validation before the window expired, contact Concierge to request a new set of test transactions.
+
+---
+
+# Troubleshooting Additional Documentation Review
+
+## Concierge says my account requires additional documentation
+
+If automatic verification cannot be completed, Expensify may request a manual review of your supporting documents. This can happen when:
+
+- Business information does not match public records
+- The business is newly formed or has limited public data
+- Additional verification is required for compliance reasons
+
+Concierge will send you a message with specific instructions on what to provide. Common documents include a bank statement, business license, articles of incorporation, or EIN confirmation letter.
+
+## How long does the documentation review take?
+
+Reviews are typically completed within **1-3 business days** after all requested documents are submitted. You will receive a message from Concierge when the review is complete. If your review is taking longer than expected, contact Concierge for a status update.
+
 </div>

docs/articles/new-expensify/wallet-and-payments/Resolve-Errors-Adding-a-Bank-Account.md

@@ -1,19 +1,87 @@
 ---
 title: Resolve Errors Adding a Bank Account
 description: Troubleshooting issues adding a business bank account in Expensify.
+keywords: [New Expensify, bank account error, Onfido, identity verification, ID upload, beneficial owner, industry restriction, documentation review, verification failed, bank account pending]
 ---
 
-Expensify is required to verify the identity of the individual who is connecting a business bank account.
+Expensify is required to verify the identity of the individual who is connecting a business bank account. Below are common errors and how to resolve them.
+
+---
+
+# Identity Verification (Onfido) Errors
+
+## Generic error while uploading your ID
+
+If you get a generic error message while uploading your ID, try the following steps:
 
-**If you get a generic error message while uploading your ID, please go through the following steps:**
 1. Ensure you are using either Safari (on iPhone) or Chrome (on Android) as your web browser.
-2. Check your browser's permissions to make sure that the camera and microphone settings are set to "Allow"
+2. Check your browser's permissions to make sure that the camera and microphone settings are set to "Allow".
 3. Clear your web cache for Safari (on iPhone) or Chrome (on Android).
 4. If using a corporate Wi-Fi network, confirm that your corporate firewall isn't blocking the website.
-5. Make sure no other apps are overlapping your screen, such as the Facebook Messenger bubble, while recording the video. 
+5. Make sure no other apps are overlapping your screen, such as the Facebook Messenger bubble, while recording the video.
 6. On iPhone, if using iOS version 15 or later, disable the Hide IP address feature in Safari.
-7. If possible, try these steps on another device
-8. If you have another phone available, try to follow these steps on that device
+7. If possible, try these steps on another device.
+8. If you have another phone available, try to follow these steps on that device.
 
 If the issue persists, please contact your Account Manager or Concierge for further troubleshooting assistance.
 
+## Identity verification failed or was not accepted
+
+If Onfido could not verify your identity:
+
+1. Make sure the photo of your ID is clear, well-lit, and shows all four corners of the document.
+2. Use a valid, non-expired government-issued photo ID (passport, driver's license, or national ID card).
+3. Ensure your selfie or video matches the photo on the ID.
+4. Try again in a well-lit area and hold the camera steady.
+5. If you continue to receive errors, try a different device or browser.
+
+If verification fails after multiple attempts, contact Concierge. An agent can review your case and advise on next steps, which may include submitting documentation manually.
+
+---
+
+# Beneficial Owner Documentation
+
+## Who qualifies as a beneficial owner?
+
+A beneficial owner is any **individual** who owns 25% or more of the business. Only individuals should be listed -- do not enter other companies or entities, even if they are partial owners.
+
+## What documentation is required?
+
+When adding beneficial owners, you may be asked to provide:
+
+- Full legal name, date of birth, and Social Security Number (SSN) or Individual Taxpayer Identification Number (ITIN) for each beneficial owner
+- Residential address (not a P.O. Box) for each beneficial owner
+
+If Expensify cannot verify a beneficial owner automatically, Concierge may request additional documentation, such as a copy of a government-issued ID.
+
+---
+
+# Industry Restriction Errors
+
+Expensify cannot process payments for certain industries due to regulatory requirements. If you receive an error indicating that your business type is not supported, it means your industry falls outside of what Expensify can service for payments.
+
+For a full list of restricted industries, see the [Expensify Classic troubleshooting guide](https://help.expensify.com/articles/expensify-classic/bank-accounts-and-payments/bank-accounts/Troubleshooting-business-bank-account-setups).
+
+If you believe the restriction was applied in error, contact Concierge with details about your business.
+
+---
+
+# Additional Documentation Review
+
+## What does "additional documentation review" mean?
+
+If automatic verification cannot be completed, Expensify may require a manual review of supporting documents. This typically happens when:
+
+- The information provided does not match public records
+- The business is newly formed and has limited public data
+- Additional verification is needed for compliance reasons
+
+## What to expect
+
+- Concierge will message you with specific instructions on which documents to provide.
+- Common documents include: a bank statement, a business license, articles of incorporation, or an EIN confirmation letter.
+- Reviews are typically completed within **1-3 business days** after all requested documents are submitted.
+- You will receive a message from Concierge when the review is complete.
+
+If your review is taking longer than expected, contact Concierge for a status update.
+

docs/articles/new-expensify/wallet-and-payments/Set-up-your-wallet.md

@@ -1,7 +1,7 @@
 ---
 title: Set Up Your Wallet
 description: Send and receive payments by adding your personal bank account in Expensify Wallet.
-keywords: [New Expensify, wallet, peer-to-peer payments, personal bank account, enable wallet, Plaid, Onfido]
+keywords: [New Expensify, wallet, peer-to-peer payments, personal bank account, enable wallet, Plaid, Onfido, wallet pending, verification stuck, wallet not working, can't send payments, can't receive payments, identity verification failed]
 ---
 
 The Expensify Wallet allows you to send and receive **peer-to-peer payments**, such as expense reimbursements or transfers between colleagues. To use it, you'll need to connect a **personal bank account** and verify your identity.
@@ -69,3 +69,42 @@ When verification is successful, your Expensify Wallet will be fully enabled. Yo
 - Get reimbursed for expenses
 - Transfer funds with no additional fees
 
+---
+
+# Troubleshooting
+
+## Wallet verification is stuck in a pending state
+
+If your wallet setup appears to be stuck and is not progressing:
+
+1. Close the Expensify app or browser tab completely and reopen it.
+2. Go to **Wallet** and check whether the setup flow resumes automatically.
+3. If a specific step (such as Onfido verification) shows as pending for more than a few minutes, try completing it again.
+4. Ensure your internet connection is stable, as the verification steps require network access.
+
+If the wallet remains stuck after retrying, contact Concierge for help.
+
+## Identity verification fails during wallet setup
+
+If Onfido cannot verify your identity during wallet setup:
+
+1. Make sure you are using a clear, valid, non-expired government-issued photo ID.
+2. Take the photo in a well-lit area and ensure all four corners of the ID are visible.
+3. For the selfie or video step, hold the camera steady and ensure your face is clearly visible.
+4. Try a different browser or device if errors persist.
+
+For detailed troubleshooting steps, see [Resolve Errors Adding a Bank Account](https://help.expensify.com/articles/new-expensify/wallet-and-payments/Resolve-Errors-Adding-a-Bank-Account).
+
+If verification fails after multiple attempts, contact Concierge. An agent can review your case and may offer an alternative verification path.
+
+## Wallet shows as enabled but I can’t send or receive payments
+
+If your wallet appears to be active but payments are not working:
+
+1. Confirm that a personal bank account is connected. Go to **Wallet** and check the **Bank accounts** section. If no bank account is listed, you will need to [connect a personal bank account](https://help.expensify.com/articles/new-expensify/expenses-and-payments/Connect-a-Personal-Bank-Account).
+2. Make sure the bank account is not in an error state. If you see an error badge, follow the instructions shown to resolve it.
+3. Check that you have completed all wallet setup steps, including identity verification. A partially completed setup may show the wallet as enabled but restrict functionality.
+4. Try logging out and logging back in to refresh your wallet status.
+
+If none of these steps resolve the issue, contact Concierge for assistance.
+

docs/articles/new-expensify/wallet-and-payments/Validate-a-Business-Bank-Account.md

@@ -1,7 +1,7 @@
 ---
 title: Validate a Business Bank Account
 description: Enter test transaction amounts to complete validation of a business bank account in Expensify.
-keywords: [New Expensify, validate bank account, test deposits, ACH validation, business bank verification, confirm test transactions, micro-transactions, pending bank account]
+keywords: [New Expensify, validate bank account, test deposits, ACH validation, business bank verification, confirm test transactions, micro-transactions, pending bank account, validation failed, test deposits wrong, Fix button missing, Unlock button missing, bank account pending, verification expired, wrong amounts, validation locked]
 internalScope: Audience is all members with a pending business bank account. Covers entering test transactions to validate a bank account. Does not cover initial bank account setup, sharing, unsharing, or unlocking.
 ---
 
@@ -70,7 +70,7 @@ The test transactions will have a name like "Expensify, Inc. Validation".
 
 ## What happens if I enter the wrong amounts?
 
-You’ll be prompted to try again. Multiple failed attempts may temporarily lock validation.
+You’ll be prompted to try again. Multiple failed attempts may temporarily lock validation. See the troubleshooting section below for common causes of incorrect amounts.
 
 ## Can I skip validation if the account was shared with me?
 
@@ -79,3 +79,51 @@ No. US bank accounts require validation by entering test transactions. Some non-
 ## What if I don’t have access to the bank account?
 
 Another member with access to the bank account must complete the validation.
+
+---
+
+# Troubleshooting
+
+## Test transactions arrived but the amounts I entered are rejected
+
+If you can see the test transactions in your bank account but validation keeps failing:
+
+- **Use posted amounts, not pending amounts.** Wait until the transactions have fully posted to your account. Pending transaction amounts can sometimes differ slightly from the final posted amounts.
+- **Check for rounding.** Enter the exact amounts shown in your bank statement, including cents. Even a one-cent difference will cause validation to fail.
+- **Make sure you have the right transactions.** Look for transactions labeled "Expensify, Inc. Validation" or similar. If you have connected multiple bank accounts, make sure you are not confusing test transactions from a different account.
+- **Check the transaction order.** Expensify expects two withdrawals and one deposit. Make sure you are entering each amount in the correct field.
+
+If you have confirmed all of the above and validation still fails, contact Concierge for assistance.
+
+## The Fix or Unlock button is missing
+
+If your bank account shows a **Locked** badge but you do not see a **Fix** or **Unlock account** option:
+
+1. Check **Settings > Wallet** in the **Bank accounts** section and click the locked bank account.
+2. If no option appears there, check **Workspaces > [Workspace Name] > Workflows** in the **Payments** section.
+3. Also look for a time-sensitive alert on the **Home** screen, which may include a **Fix** button.
+
+If you still cannot find the option, refer to [Unlock a Business Bank Account](https://help.expensify.com/articles/new-expensify/wallet-and-payments/Unlock-a-Business-Bank-Account) for detailed steps, or contact Concierge.
+
+## Validation is temporarily locked after failed attempts
+
+If you enter incorrect amounts multiple times, validation is temporarily locked to protect your account. The lock typically lasts a few hours. After the lock period ends, you can try again by going to **Settings > Wallet** and clicking the bank account.
+
+If you are still unable to validate after the lock period has passed, contact Concierge.
+
+## How long does validation stay open before expiring?
+
+Test transactions and the validation window remain active for a limited time. If you do not complete validation within this period, the test transactions may expire and you will need to request new ones by contacting Concierge.
+
+To avoid expiration, enter the test transaction amounts as soon as they appear in your bank account.
+
+## "Your bank account is almost set up" message but no test transactions after several days
+
+If Concierge has sent the "Your bank account is almost set up!" message but you have not received the test transactions after more than two business days:
+
+1. Confirm that the bank account number connected in Expensify matches the account you are checking.
+2. Ask your bank if they have blocked or filtered any small ACH transactions. Provide these details:
+   - **ACH Company IDs:** 1270239450, 4270239450, 2270239450
+   - **ACH Originator Name:** Expensify
+3. Check whether the transactions were returned or rejected by your bank.
+4. If none of the above resolves the issue, contact Concierge to re-trigger the test transactions.