Bank Connect
Bank Connect
Breadcrumbs

Troubleshooting

How to Use This Guide

For each issue:

  1. Match the Symptoms to what the user or record shows.

  2. Confirm the Root Cause using the listed fields, logs, or settings.

  3. Apply the Resolution steps.

  4. Use Prevention to avoid recurrence.

Primary diagnostic fields on Bank_Verification__c:

Field

What it tells you

Status__c

Overall verification lifecycle

Transaction_Api_Status__c / Transaction_Description__c

Transaction import health

Balance_Api_Status__c

Balance refresh health

Asset_Api_Status__c / Asset_Description__c

Asset report health

Income_Api_Status__c / Income_Description__c

Income API health

Auth_Api_Status__c / Micro_Deposit_Status__c

Auth / micro-deposit state

Encrypted_Plaid_token__c

Whether a stored access token exists

Item_ID__c

Plaid item used for webhook matching

Issue 1: Transactions Not Refreshing Automatically

Severity

Critical

Symptoms

No new transactions after Plaid updates; Last_Transaction_Refresh_Date__c not updating; webhook received but no data change

Root Cause

DisableAutomaticRefreshTransactions is set to true, webhook URL is misconfigured, or Plaid item is disconnected

Affected Code

PlaidTransactionsCallBackService.cls — webhook handler skips refresh when setting is enabled

Resolution:

  1. Check Plaid Common Setting: DisableAutomaticRefreshTransactions → must be false.

  2. Confirm webhook URL in Plaid Credentials points to:
    https://{org-domain}/services/apexrest/bankconnect/Plaid_Callback

  3. Verify Item_ID__c on the Bank Verification matches the webhook item_id.

  4. Check Transaction_Api_Status__c and Transaction_Description__c for Plaid error codes.

  5. Manually trigger refresh via InvocableRefreshPlaidProducts or Admin refresh if needed.

Prevention: Document webhook URL during go-live; monitor DisableAutomaticRefreshTransactions in change control.

Issue 2: Asset Report Stuck in "In Progress"

Severity

Critical

Symptoms

Asset_Api_Status__c = In Progress indefinitely; no PDF generated; Asset_PDF__c remains unchecked

Root Cause

Plaid asset webhook not received, batch processing not scheduled, or Delay_Asset_Processing__c never cleared

Affected Code

PlaidCallbackService.cls, BatchAssetWebhookProcessing.cls, ScheduableBatchAssetWebhookProcessing.cls

Resolution:

  1. Confirm asset webhook URL in Plaid Dashboard:
    https://{org-domain}/services/apexrest/bankconnect/Asset_Callback

  2. Check Asset_Report_Id__c and Encrypted_Asset_Report_Token__c are populated.

  3. If EnableAssetWebhookBatchProcessing = true:

    • Verify Delay_Asset_Processing__c = true after webhook

    • Confirm ScheduableBatchAssetWebhookProcessing is scheduled

    • Check NextAssetBatchRunTime setting

  4. If batch is disabled, webhook should call WSProductsService.getAssetDetail() directly — review Apex debug logs.

  5. Retry via manual asset refresh or PlaidRetryAuthService if status is Failed.

Prevention: Schedule asset webhook batch during implementation; validate webhook delivery in Plaid Dashboard.

Issue 3: Bank Item Disconnected (ITEM_LOGIN_REQUIRED)

Severity

Critical

Symptoms

All product API statuses fail; error contains ITEM_LOGIN_REQUIRED; user cannot refresh data

Root Cause

Plaid access token is invalid — user changed password, MFA expired, or institution requires re-link

Affected Fields

Encrypted_Plaid_token__c, Status__c, all *_Api_Status__c fields

Resolution:

  1. Read Transaction_Description__c, Balance_Description__c, or other product description fields for ITEM_LOGIN_REQUIRED.

  2. Instruct end user to re-authenticate via Plaid Link (update mode).

  3. After re-link, confirm new Encrypted_Plaid_token__c and Item_ID__c are stored.

  4. Re-run product imports via BatchCallPlaidProductsService or manual refresh.

  5. Optionally use WSRemoveAccessToken / BatchRemoveAccessToken to clean up stale tokens.

Prevention: Monitor failed API statuses; set up reporting on ITEM_LOGIN_REQUIRED occurrences.

Issue 4: Transactions Status "In Progress" — PRODUCT_NOT_READY

Severity

High

Symptoms

Transaction_Api_Status__c = In Progress; description mentions product not ready; no transactions imported yet

Root Cause

Plaid has not finished initial transaction sync — normal for newly linked items

Affected Code

WSProductsService.getTransactionsDetail() — treats PRODUCT_NOT_READY as In Progress, not Failed

Resolution:

  1. Confirm this is a newly linked item (within first few minutes/hours).

  2. Wait for Plaid TRANSACTIONS webhook (HISTORICAL_UPDATE or DEFAULT_UPDATE).

  3. Do not mark as failed — status should auto-update when webhook fires.

  4. If stuck >24 hours: verify Transactions product is enabled in Plaid Link config and institution supports it.

Prevention: Set client expectations on initial sync delay; rely on webhooks rather than immediate polling.

Issue 5: Income API Failed — "User Token does not exists"

Severity

Critical

Symptoms

Income_Api_Status__c = Failed; Income_Description__c = User Token does not exists

Root Cause

User_Token__c is blank — Income product requires a Plaid user token created during Link

Affected Code

WSIncomeVerification.cls (Bank Income and Payroll Income paths)

Resolution:

  1. Confirm Income is included in Plaid_Products__c on the Bank Verification.

  2. Verify User_Token__c and User_Id__c are populated after Link completion.

  3. Re-run Link flow with Income product enabled if tokens are missing.

  4. Check Income_Source_Type__c matches the intended flow (Bank Income vs Payroll).

  5. Use Plaid Retry Auth Service after token is restored.

Prevention: Validate Income product configuration in Plaid Credentials and Link token creation (WSProductsService link token method).

Issue 6: Income API Failed — Warning / ITEM_UNAPPROVED

Severity

High

Symptoms

HTTP 200 from Plaid but Income_Api_Status__c = Failed; description like ITEM_UNAPPROVED::Data was not approved by user...

Root Cause

User did not grant consent for Bank Income during Link; Plaid returns warnings in response

Affected Code

WSIncomeVerification.getBankIncome(), PlaidBankIncomeJSONParser.cls

Resolution:

  1. Review Income_Description__c — error code is prefixed (e.g., ITEM_UNAPPROVED::...).

  2. Confirm end user completed Income consent screens in Plaid Link.

  3. Re-initiate Link with Income product and ensure user approves data sharing.

  4. Check stored JSON response in ContentVersion (Title like '%Income Response%') for full warning details.

Prevention: Include Income consent messaging in client-facing instructions before Link launch.

Issue 7: Trigger Error — System.MathException: Divide by 0

Severity

High

Symptoms

Bank Verification update fails; Apex error on BankVerificationTrigger line 63 or 69

Root Cause

Income_Start_Date__c and Income_End_Date__c are the same day, end is before start, or month span is zero when calculating average monthly income

Affected Code

BankVerificationTrigger.calculateAverageMonthlyIncome()

Resolution:

  1. Check Income_Start_Date__c, Income_End_Date__c, Payroll_Start_Date__c, Payroll_End_Date__c.

  2. Ensure end date is after start date with a valid range.

  3. If dates are equal, income calculation should return 0 (fix should guard against division by zero).

  4. Correct dates on the record and retry the update.

Prevention: Add validation rules on date fields; validate payroll date mapping before bulk updates.

Issue 8: Plaid API Callouts Failing — Credentials / Connection

Severity

Critical

Symptoms

All API statuses fail simultaneously; callout exceptions; blank responses; 401/403 errors

Root Cause

Missing or incorrect Plaid Credentials custom setting, wrong environment (Sandbox vs Production), or Remote Site not configured

Affected Code

ConfigurationService.cls (ApiConnection), Utility.getPlaidCredentials(), all WS* service classes

Resolution:

  1. Verify Plaid Credentials record exists for the correct environment (Sandbox / Production).

  2. Confirm Plaid_Client_Id__c, Plaid_Client_Secret__c, and endpoint URIs are correct.

  3. Check Plaid Common Setting ApiConnection matches intended environment.

  4. Confirm Remote Site Settings / Named Credentials allow callouts to Plaid endpoints.

  5. Verify ApplicationName__c on Bank Verification maps to the correct credential record.

Prevention: Include credential validation in Maker-Checker checklist; test callouts in sandbox before production cutover.

Issue 9: API Callout Timeouts

Severity

High

Symptoms

Intermittent failures on large transaction pulls or asset report retrieval; Failed status with timeout-related exception text

Root Cause

Default callout timeout exceeded; large data sets (500+ transactions with pagination)

Affected Settings

APICalloutTimeout (default: 90000 ms) in Plaid Common Settings

Resolution:

  1. Review Apex debug logs for timeout exceptions during WSProductsService callouts.

  2. Adjust APICalloutTimeout if supported (within Salesforce limits).

  3. For transactions: system uses pagination via InvocablePlaidTransactionsService queueable — confirm subsequent batches are running.

  4. Retry failed product individually rather than all products at once.

Prevention: Schedule heavy refreshes during off-peak hours; monitor queueable job failures.

Issue 10: Experience Cloud — IDV Icons / Images Not Displaying

Severity

High

Symptoms

Pass/fail/status icons missing in View IDV Result component on Experience Cloud site; broken image placeholders

Root Cause

LWC not exposed to Experience Cloud, static resource path mismatch, or ContentDocument URLs inaccessible to guest users

Affected Code

viewIDVResult.js, viewIDVResult.js-meta.xml, static resources (Passed, Failed_Identity, IdentityVerification_Resource)

Resolution:

  1. Add Experience Cloud targets to viewIDVResult.js-meta.xml:

    • lightningCommunity__Page

    • lightningCommunity__Default

  2. Confirm static resources have cacheControl = Public.

  3. Check browser Network tab for 404s on static resource URLs.

  4. Verify serviceIconMap filenames match actual files inside IdentityVerification_Resource zip.

  5. Replace /sfc/servlet.shepherd/version/download/ URLs with Experience Cloud-compatible file delivery for guest users.

Prevention: Test all LWC components on Experience Cloud before go-live; include static resource verification in UAT.

Issue 11: No Transactions Stored Despite Successful API

Severity

High

Symptoms

Transaction_Api_Status__c = Completed but no Transactions__c records; account summary shows zero activity

Root Cause

storeEmptyTransactions = false (default) skips zero-amount transactions; account not linked via Selected_Account_Ids__c

Affected Settings

storeEmptyTransactions, EnableStoringPendingTransactions

Resolution:

  1. Check Selected_Account_Ids__c includes the Plaid account IDs returned by API.

  2. Verify Bank_Account__c records exist for those account IDs.

  3. If client needs pending/zero transactions, set storeEmptyTransactions = true.

  4. Review EnableStoringPendingTransactions for pending transaction handling.

  5. Confirm composite unique keys are not blocking upserts silently.

Prevention: Document transaction filtering behavior for clients; validate account selection during Link.

Issue 12: Micro-Deposit Verification Expired

Severity

High

Symptoms

Micro_Deposit_Status__c = VERIFICATION_EXPIRED; Auth API fails for manual verification accounts

Root Cause

User did not complete micro-deposit verification within Plaid's allowed window

Affected Code

PlaidTransactionsCallBackService — AUTH webhook handler for VERIFICATION_EXPIRED

Resolution:

  1. Confirm Micro_Deposit_Status__c value on Bank Verification.

  2. Instruct user to re-link the account through Plaid Link.

  3. Monitor for AUTOMATICALLY_VERIFIED webhook after successful verification.

  4. Re-trigger Auth via WSProductsService.getAuthDetail() once verified.

Prevention: Communicate micro-deposit timelines to end users at Link initiation.

Issue 13: Scheduled Batch Jobs Not Running

Severity

Critical

Symptoms

Daily refreshes never occur; asset webhook backlog; statement downloads stop

Root Cause

Batch/schedulable jobs not scheduled or aborted

Affected Jobs

ScheduableBatchAssetWebhookProcessing, BatchDownloadPlaidStatements, BatchRemoveAccessToken, Batch_CallOcrolusFraudDetect

Resolution:

  1. Go to Setup → Apex Jobs → Scheduled Jobs and verify schedules exist.

  2. Check Setup → Apex Jobs for failed/aborted batch runs.

  3. Confirm related settings:

    • NextAssetBatchRunTime

    • NextStatementsBatchRunTime / PlaidStatementsBatch_LastNMinutes

    • NextRunTime_OcrolusFraudDetect

  4. Re-schedule missing jobs per implementation runbook.

  5. Review batch scope queries for records stuck in processing states.

Prevention: Include batch job verification in post-deployment checklist; monitor Scheduled Jobs weekly.

Issue 14: Permission / FLS Errors Blocking Data Operations

Severity

High

Symptoms

Webhook received but no update; guest user sees empty data; INSUFFICIENT_ACCESS in logs

Root Cause

FLS enforcement enabled (enforceFLSSetting) without proper permission set assignment; Experience Cloud guest profile lacks object/field access

Affected Code

All classes using ConfigurationService.enforceFLSSetting() and data.read/modify with FLS checks

Resolution:

  1. Assign Bank Connect permission set(s) to integration user, community users, and guest profile as applicable.

  2. Verify CRUD/FLS on: Bank_Verification__c, Bank_Account__c, Transactions__c, Holdings__c, Income__c.

  3. For Experience Cloud: check guest user profile and sharing rules.

  4. Review GuestUsers and EnableCommunity_NetworkIDUpdate settings for community-specific config.

  5. Review whether the FLS enforcement setting is appropriate for the deployment model.

Prevention: Permission set assignment is a mandatory Maker-Checker checklist item.

Issue 15: Document Insight / PDF Parsing Failures

Severity

High

Symptoms

Document Insight status = Failed or Extraction Failed; duplicate key errors; Ocrolus/MoneyThumb integration errors

Root Cause

Invalid document category, file size exceeds limit, duplicate keys in parsed data, or third-party API auth failure

Affected Settings

PDFInsight_ValidCategories, MT_ContentSizeLimit, Halt_Parsing_When_Duplicate_Keys_Found

Resolution:

  1. Check Document Insight record Status__c and error description fields.

  2. Verify document category is in PDFInsight_ValidCategories.

  3. Confirm file size is under MT_ContentSizeLimit (default: 3,000,000 bytes).

  4. If Duplicate_Keys__c is populated and parsing halted, review source document or set Halt_Parsing_When_Duplicate_Keys_Found = false.

  5. For Ocrolus failures: verify auth token creation and reprocess via Batch_OcrolusReprocessingJob.

Prevention: Validate document types and sizes at upload; monitor Ocrolus/MoneyThumb credential expiry.