Answers to the questions and Plaid errors that come up most often.
Link says “INVALID_LINK_TOKEN” or closes immediately
Link tokens expire (4 hours; 30 minutes in update mode). BankBridge fetches a fresh token automatically — reload the page. If it persists, run wp bankbridge test.
OAuth banks (Chase, Wells Fargo…) fail to return
Register the exact redirect URI from the Setup Wizard in the Plaid Dashboard. It must be HTTPS with no query string in Production, and your Plaid application profile must be complete — some banks take extra days to approve.
A customer’s connection shows “Needs attention”
The bank requires a new login (ITEM_LOGIN_REQUIRED) or consent is expiring. Customers click Reconnect in their accounts page; BankBridge also emails them (once a day at most).
“This bank is already connected” (DUPLICATE_ITEM)
BankBridge blocks a second connection to the same bank and accounts for a user. Reconnect the existing one instead, or disable Prevent duplicate connections.
PRODUCT_NOT_ENABLED or INVALID_PRODUCT
The product isn’t enabled for your Plaid team or environment. Request access in the Plaid Dashboard (Products). Connections stay healthy; only that feature is unavailable.
Payments stay “pending” forever
Transfers move on Plaid’s schedule. In Sandbox use Transfers → Simulate…. In Production check that webhooks arrive and that cron runs (the transfer event sync runs hourly; wp bankbridge transfers sync runs it now).
Payment declined
Plaid’s authorization declined the debit (for example insufficient funds risk) or your Signal rules blocked it. The customer is asked to choose another account; details are on the transfer row.
Webhooks return 401
Signature verification failed. Make sure nothing (proxy, security plugin) strips the Plaid-Verification header or modifies the body, and that the server clock is correct.
Secrets can’t be decrypted after a migration
The encryption key changed (usually WordPress salts). Restore the old key or run wp bankbridge rotate-key --from=… with the old material, then wp bankbridge key-audit.
Where do I see what happened?
BankBridge → API Logs (every Plaid call with request ID), Webhooks (events with replay) and Tools & Status, or run wp bankbridge doctor.