Skip to main content
Using Plaid for personal use might be against their terms of service. This integration is intended for technically savvy users who understand the implications and requirements.
Plaid integration currently only works for Western users. Plaid Production support is not available to European users.
For Plaid integration, your Sure instance needs to be accessible from the internet behind a domain with working SSL. See additional context in maybe-finance/maybe#2419.
Plaid is a US-focused banking provider that offers comprehensive account connectivity. However, it requires significant technical setup and may not be suitable for personal use according to their terms of service.

​
Prerequisites

Before setting up Plaid:
  • Your Sure instance must be publicly accessible via HTTPS
  • You need a valid domain with working SSL certificate
  • You must be comfortable with technical configuration
  • You should review Plaid’s terms of service for personal use

​
Creating a Plaid account

  1. Go to dashboard.plaid.com and register for a new account
  2. Complete the registration process
  3. Request production access based on your bank type (see below)

​
Requesting production access

The process differs depending on whether your bank requires OAuth authentication.

​
For banks without OAuth

  1. On the Home page, find “Learn how to build with Plaid” and click Unlock real data
  2. Enter your real name and phone number
  3. In the description box, write:
    This is for personal use only on a self-hosted version of the Sure Finance software. I am only using it to manage my finances, sync my bank accounts, track my spending, and create a budget.
  4. Leave “Additional products” unchecked
  5. Click Request Access
  6. Wait for approval (may take more than 24 hours)

​
For banks with OAuth

Per Plaid Support as of July 2025, certain banks have extended OAuth approval timelines:
  • Chase Bank: 3-4 months
  • Schwab: Up to 2 months
  1. In the left sidebar, click Get production access
  2. Enter your real address
  3. For business profile, write:
    This is for personal use only on a self-hosted version of the Sure Finance software. I am only using it to manage my finances, sync my bank accounts, track my spending, and create a budget.
  4. Leave company website blank
  5. Enter your real name, phone number, email, and date of birth
  6. Click Next
  7. Indicate:
    • 0 employees
    • Your country of data access
    • You do not sell data
    • No security breach in past 12 months
  8. Click Next
  9. Select industry: Budgeting and financial management tools
  10. Click Next
  11. Enter any name for your application
  12. Upload a logo (1024x1024px, under 4MB)
  13. Leave brand color as #22CCEE
  14. Set Website URL to: https://github.com/we-promise/sure
  15. In “Reason for data access”, enter:
    This is for personal use only on a self-hosted version of the Sure Finance software. I am only using it to manage my finances, sync my bank accounts, track my spending, and create a budget.
  16. Enter your real email as support email
  17. Click Next
  18. Enter your country for “Where do you want to launch?”
  19. For products:
    • Payments: Check only Auth and Balance
    • Credit Underwriting: Leave all unchecked
    • Fraud & Compliance: Leave all unchecked
    • Financial Management: Check all products
  20. Click Next
  21. For use cases:
    • Payments: Select Consumer bill pay
    • Financial Management: Select Personal budgeting and financial advice for all products
  22. Click Next
  23. Select Pay As You Go plan
  24. Click Next
  25. Enter billing details and check agreement boxes
  26. Click Next
  27. Click Start Security Practices Questionnaire
  28. For each question:
    • Select Other - please see comments
    • Write in notes:
      This is for personal use only on a self-hosted version of the Sure Finance software. I am only using it to manage my finances, sync my bank accounts, track my spending, and create a budget.
  29. Continue through all sections, repeating step 28
  30. Click Submit
  31. Wait for approval (may take more than 24 hours)

​
Configuring Sure

After your Plaid account is approved:
  1. Go to dashboard.plaid.com/developers/api or click Developers > API
  2. Click Configure next to Allowed redirect URIs
  3. Click Add new URI
  4. Enter your domain with /accounts appended (e.g., https://budget.yourdomain.com/accounts)
  5. Click Save changes
  6. Go to dashboard.plaid.com/developers/keys or click Developers > Keys
  7. Copy your client_id and Production secret key
After production access is approved, finish the Plaid Link configuration before testing bank connections:
  1. In the Plaid Dashboard, go to Link > Link Customization
  2. Add Track and manage your finances as a use case
  3. Publish the changes
If this step is missing, Plaid may let you select and validate a bank but then show an empty Link popup afterward. This can look like a Sure application issue, but it usually means Plaid still has a configuration or validation step left to complete.

​
Docker Compose configuration

In your docker-compose.yml file, add these environment variables:

​
Environment variables

In your .env file, add:

​
Restart Sure

After updating your configuration, restart your Sure instance. You should now see the Link account option in the Sure UI.

​
Managing accounts

​
Adding accounts to an existing connection

If you have an existing US Plaid connection and want to add more accounts from the same institution, you do not need to create a new connection.
  1. Go to Settings > Providers and find your Plaid connection
  2. Click Add accounts next to the connection
  3. The Plaid Link flow opens with account selection enabled
  4. Select the additional accounts you want to add
  5. Complete the flow — Sure will sync the new accounts automatically
The Add accounts button is only available for US Plaid connections.

​
Linking an unlinked Plaid account to an existing Sure account

If you have a Plaid account that is not yet linked to any Sure account, you can connect it to an existing account rather than creating a new one.
  1. Go to Settings > Providers and find the account you want to link
  2. Open the account menu and choose the option to link to a Plaid account
  3. A dialog lists all unlinked Plaid accounts available in your family
  4. Select the Plaid account and click Link account
If no accounts appear in the list, all of your Plaid accounts are already linked. Connect a new Plaid account first.

​
How Sure selects Plaid products

When you initiate a Plaid Link flow, Sure requests a specific set of Plaid products based on the type of account you are linking. Plaid filters out any institution that does not support every product in the requested set, so the product selection directly controls which institutions appear in the Link UI. Because liabilities is only requested when linking a liability account (credit card or loan), investment-only institutions such as E*TRADE that do not offer Plaid’s liabilities product are now visible when you link an investment account. Previously, requesting liabilities for every account type caused those institutions to be silently hidden in the Link flow.

​
Features

  • US bank coverage: Comprehensive support for US financial institutions
  • Real-time data: Access to account balances and transactions
  • OAuth support: Secure authentication for supported banks
  • Multiple accounts: Connect accounts from different institutions
  • Investment-only institutions: Brokerages that do not offer liabilities (such as E*TRADE) can be linked as investment accounts

​
Pricing

Plaid uses a pay-as-you-go pricing model. Check plaid.com/pricing for current rates.

​
Limitations

  • US-focused: Primarily supports US institutions, not available for European users
  • Complex setup: Requires significant technical configuration
  • TOS concerns: Personal use may violate Plaid’s terms of service
  • Public accessibility: Requires publicly accessible HTTPS endpoint
  • Long approval times: OAuth-enabled banks can take months to approve
  • Technical expertise: Not recommended for non-technical users

​
Alternatives

Consider these alternatives to Plaid:
  • SimpleFIN: Simpler setup, more affordable, US-focused
  • Enable Banking: Free, EU-focused, easier setup
  • Lunch Flow: Global coverage, paid service

​
Transaction refresh behavior

Sure requests a fresh transaction pull from Plaid before reading new data in several situations, not only during manual syncs. The refresh is asynchronous: Sure sends a refresh request to Plaid, then polls for an updated transaction cursor, then triggers a follow-up sync once the cursor advances.

​
When automatic refreshes run

A transaction refresh is requested automatically in the following cases:
  • Scheduled sync — the nightly background job that syncs all families
  • Provider-wide sync — triggered when you sync all accounts from Settings or the accounts page
  • Login sync — when auto-sync on login is enabled and Sure detects a family has not synced today
In all three cases, Sure fires the refresh request alongside the normal sync. Because Plaid processes the refresh asynchronously, the baseline sync may run first with existing data. A follow-up sync is queued automatically once Plaid finishes refreshing and the cursor advances, so the latest transactions are imported even if the first sync completes before Plaid is ready.

​
Manual sync behavior

Manual syncs also request a transaction refresh before fetching data. After sending the refresh request, Sure polls Plaid for the updated cursor and syncs once new data arrives. If no new transactions appear within the polling window (roughly 3 minutes), Sure falls back to a normal sync with whatever data Plaid currently has.

​
Coalescing and the cache store requirement

To prevent duplicate refresh requests, Sure uses a shared cache to coalesce calls: if a refresh has already been requested for a given Plaid item within the last 5 minutes, subsequent requests are dropped and the in-progress refresh continues normally. The coalescing logic requires a shared cache store. Sure skips the Plaid refresh request (and logs a warning) if the cache store is the default file-based or in-memory store. To enable refresh on a self-hosted instance, configure one of the following:
  • Redis — set CACHE_URL to a Redis connection string
  • Memcache — configure MEMCACHE_SERVERS
  • SolidCache — enabled by default in the Docker Compose setup
Without a shared cache, syncs still work but do not trigger a fresh pull from Plaid before fetching transactions.

​
Reconnect status

When Plaid requires you to re-authenticate (for example, after a password change), Sure marks the connection with a “requires update” warning. Clicking the Update button in Settings > Providers opens the Plaid Link re-authentication flow. After you complete re-authentication, the warning is not cleared immediately. Sure clears the “requires update” status only after the next full import succeeds. This means the warning may persist briefly after you reconnect — it disappears once the subsequent sync completes without a login error. If the login issue is still present, the status remains until authentication succeeds and a full import runs cleanly.

​
Troubleshooting

If you run into Plaid errors that are not visible in Sure, check the Plaid Dashboard logs under Developers > Logs. These logs can show whether the issue is coming from Plaid Link configuration, product approval, institution support, or another Plaid-side validation error. If the Plaid popup closes immediately after you select a bank, and Sure shows no useful app logs, the problem may be on Plaid’s side rather than in your Sure configuration. Things to verify first:
  • Your instance is publicly reachable over HTTPS
  • Your allowed redirect URI is set correctly in Plaid, for example https://budget.yourdomain.com/accounts
  • PLAID_ENV=production when using Limited or Full Production access
  • Your PLAID_CLIENT_ID and PLAID_SECRET are the Production credentials, not Sandbox keys
If all of that looks correct and the flow still closes with no obvious error, Plaid may need to review or reprocess your onboarding / client registration. This has happened in the wild with Sure. In one confirmed Chase case, the integration started working without app changes after Plaid support escalated the issue to their Chase team and reprocessed the user’s client registration. When contacting Plaid support, include:
  • Your Plaid environment and access tier (for example, Limited Production)
  • The institution you are trying to connect (especially if it is Chase or another OAuth-heavy institution)
  • Confirmation that /link/token/create succeeds (can be verified in the Activity section of your Plaid Dashboard)
  • Confirmation that your redirect URI is configured correctly
  • A note that the Link popup closes without completing the connection
  • A request for them to verify or reprocess your client registration / onboarding

​
Support

For Plaid-specific issues, consult the Plaid documentation or contact Plaid support.