> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sure.am/llms.txt
> Use this file to discover all available pages before exploring further.

# Sophtron

> Connect US and Canadian bank accounts via Sophtron's aggregation API

Sophtron is a third-party provider that connects bank, credit card, investment, loan, insurance, utility, and other financial accounts in the US and Canada. It is currently in **alpha**.

## How it works

Sophtron uses HMAC-SHA256 (FIApiAUTH) signed API calls to securely aggregate your financial data:

1. Obtain a Sophtron User ID and Access Key
2. Configure your credentials in Sure
3. Sure provisions a Sophtron Customer for your family (created or reused automatically through the API)
4. You connect a bank institution by searching for it and entering your bank login credentials
5. Sure fetches your accounts, balances, and transactions through Sophtron's API
6. Data syncs automatically to keep your information current

## Setting up Sophtron

<Note>
  Connecting institutions and managing Sophtron connections requires a family
  admin role. Non-admin members can view linked accounts but cannot start a new
  institution connection or submit MFA answers.
</Note>

To connect your accounts:

1. Register a Sophtron account at [sophtron.com](https://sophtron.com/account/register)
2. Obtain your **User ID** and **Access Key** from the [Sophtron dashboard](https://sophtron.com/Manage/Developer)
3. In Sure, go to **Settings > Bank Sync Providers** and add your Sophtron credentials
4. Open the Sophtron connection dialog and search for your bank institution
5. Enter your bank login credentials (and complete any MFA challenge if prompted)
6. Sure will discover your accounts and prompt you to select which ones to link

### Credential configuration

Sophtron credentials are stored per-family. Each family configures their own User ID and Access Key. Credentials are encrypted at rest when ActiveRecord Encryption is enabled.

You can optionally configure a custom **base URL** if you use a non-production Sophtron environment. The default base URL is `https://api.sophtron.com/api`.

When you save your credentials, Sure automatically creates or reuses a Sophtron **Customer ID** for your family by calling the Sophtron Customer API. You do not need to provision the customer manually.

### Connecting an institution

Before you can link accounts, you must connect a bank institution to Sophtron:

1. Search for your bank by name in the connection dialog
2. Select the institution from the results
3. Enter your bank username and password
4. If the institution requires it, complete the MFA challenge

#### Multi-factor authentication

Sophtron supports several MFA challenge types. Depending on your institution, you may be asked to:

* Answer one or more security questions
* Choose how you want to receive a verification code (for example, email or SMS)
* Enter a verification code (OTP) sent to your email or phone
* Type the text shown in a captcha image
* Confirm the login attempt by phone

Sure polls Sophtron for the connection status while the institution login is in progress and prompts you when an MFA step is required. After you submit a challenge, Sure continues polling so any follow-up step (such as entering an OTP after choosing a delivery method) is shown automatically.

#### Connection timeouts and retries

If Sophtron does not finish connecting within the expected time, the connection dialog gives you the option to check again or retry. Failed or timed-out connection jobs are reset so you can start a fresh attempt without re-entering your provider credentials.

### Linking accounts

After the institution is connected, Sure fetches available accounts from Sophtron. You can:

* **Link new accounts**: Select from your Sophtron accounts and choose the account type (depository, credit card, investment, or loan)
* **Link existing accounts**: Connect an existing Sure account to a Sophtron account for automatic syncing

## Supported account types

Sophtron supports the following account types:

| Account type | Description                                     |
| ------------ | ----------------------------------------------- |
| Depository   | Checking, savings, and other deposit accounts   |
| Credit card  | Credit card accounts                            |
| Investment   | Brokerage and retirement accounts               |
| Loan         | Mortgage, student loan, and other loan accounts |

When linking accounts, you can also select a subtype (e.g., checking vs. savings for depository accounts).

## Features

### Account syncing

* **Account discovery**: Automatically finds all accounts available on the connected institution
* **Balance tracking**: Fetches current balances for all linked accounts
* **Transaction history**: Imports transactions with date range filtering
* **Refresh polling**: Sync jobs poll Sophtron's job status endpoint and complete once the refresh job finishes
* **Reconnect on auth recovery**: When an institution refresh requires re-authentication or a new MFA challenge, Sure marks the connection as `requires_update` so you can complete the challenge and resume syncing

### Transaction syncing

When syncing transactions, Sure:

* Fetches transactions within a configurable date range
* Maps transaction data including amount, date, merchant, and description
* Supports both income and expense transaction types
* Defaults the currency to USD when not specified by the provider

### Sync start date

You can configure a **sync start date** to control how far back Sure fetches transaction history. This is useful when you only want recent transactions rather than a full history.

## Limitations

* **Alpha status**: Sophtron integration is currently in alpha and may have rough edges
* **US and Canada only**: Primarily supports financial institutions in the United States and Canada
* **Rate limits**: Subject to Sophtron API rate limits (returns a 429 status when exceeded)
* **No pending transactions**: Pending transaction support is not currently available
* **Holdings**: Investment holdings sync is not currently supported

## Troubleshooting

### Authentication errors

If you receive an "Invalid User ID or Access key" error:

* Verify your User ID and Access Key are correct
* Ensure your Access Key is the base64-encoded version provided by Sophtron
* Check that your Sophtron account is active

### Institution connection errors

If Sure cannot complete the institution connection:

* **Bank credentials**: Double-check the username and password you entered for the institution
* **Verification code**: Make sure you entered the latest MFA code before it expired
* **Institution timeout**: The bank login page may not have finished in time. Try connecting again
* **Unsupported MFA**: Sophtron may not support the institution's current verification flow

### No accounts found

If Sure cannot find any accounts:

* Confirm that you have completed the institution connection step
* Check that your credentials have the correct permissions
* Try re-entering your credentials in Sure's provider settings

### No institution connected

If Sure tells you that no bank institution is connected when syncing or linking accounts, open the Sophtron connection dialog and connect an institution before retrying. Sync attempts fail until at least one institution is linked.

### Sync failures

If syncing fails intermittently:

* Check whether you have hit the API rate limit (wait and retry)
* Verify your credentials have not been revoked
* If the connection is marked **requires update**, reopen the connection dialog and complete the new MFA challenge
* Review the sync status in your accounts page for specific error messages