Reconnect Flow

Connections can sometimes enter into an error state that prevents new data from being synced. While some errors are intermittent in nature due to upstream connectivity issues with the institution, Connections can also break due to a simple password change or security upgrade at the bank. When Quiltt detects that a Connection that can be repaired by user interaction with the Connector, the following will occur:

1. The Connection status will change to ERROR_REPAIRABLE, firing the connection.synced.errored.repairable webhook event.
2. Regular syncing will be interrupted and no new data will be synced, including associated accounts and transactions, until the Connection is repaired.
3. Account Balance Refreshes and other per-Connection actions in the Platform API will start returning 403 Forbidden.
4. To restore syncing, the user will need to complete the Reconnect Flow by re-authenticating with their financial institution.

Link to this section#Implementing Reconnect

To allow your end-user to repair the Connection, simply pass the Connection ID to the Connector SDK. See the examples below and the relevant SDK docs for platform-specific instructions.

Upon launching the Connector, your user will be automatically prompted to re-authenticate to their institution using the current upstream provider (i.e. MX, Finicity or Plaid). Once they have successfully re-authenticated, the Connection will resume syncing. You can track the Connection status via webhooks, GraphQL subscription or via polling.

Link to this section#Examples

Link to this section#Client-side Connector Events

When the user successfully completes the flow, the Connector exited.successful event will fire. You can attach a callback with the JavaScript API or use the onExitSuccess prop on the React component. The connectionId will be passed to the callback as metadata, alongside the connectorId and profileId.

See the JavaScript API guide for more information about the event.

Link to this section#Server-side Webhooks

To have your server be notified when a Connection needs to be repaired, you can subscribe to the connection.synced.errored.repairable event via Webhooks.

When the Connection successfully syncs, a connection.synced.successful event will fire, and the Connection status will change to SYNCED.

Link to this section#GraphQL Subscriptions

You can also subscribe to real-time updates on the Connection status with the connectionSynced GraphQL Subscription. This approach can be used client-side or server-side.

Link to this section#How to Simulate a Connection Error

To test the flow, you can place SANDBOX Connections into a user-repairable state using the connectionSimulateError GraphQL mutation.

You can call the mutation in the GraphQL Explorer from the Quiltt Dashboard, or by calling the Profile GraphQL API.

You can simulate an error in the Quiltt Hub demo to see what the experience is like for the user.

Link to this section#Request

Link to this section#Response

Link to this section#Reconnecting DISCONNECTED Connections

In addition to repairing connections that enter an ERROR_REPAIRABLE state, you can use Reconnect to "revive" connections that were previously put in a DISCONNECTED state. This can be used to support migrating connections between different providers.

With a DISCONNECTED Connection, the end-user will be prompted to authenticate into the Connection's institution using the best-suited provider provisioned on the Connector. Once the user has successfully authenticated, Quiltt will create a new Connection, and any relevant data from the DISCONNECTED Connection will be transferred to the new Connection.

Since a new Connection ID will be generated, you will want to listen to the onExitSuccess callback to capture the new ID and, if your implementation requires it, register it with your backend.