Connect Accounts

Bill Management typically begins by establishing a connection to a user's account using the Transact SDK.

This guide outlines how to initiate that connection, covering multiple methods of directing users into the Transact SDK, along with the tradeoffs of each approach. It also explains the account lifecycle and key considerations for managing linked accounts.

We assume you have previously viewed the Integration Guide and installed the Transact SDK.

Accounts can be connected in multiple ways.

• User-driven selection: Users choose from a list of supported companies within the Transact SDK.
• Deep linking: Link users directly from your app or site into a specific company.
• Pre-populated options: Provide a list of biller transactions, allowing Atomic to pre-populate account options for the user to link.

Launching the Transact SDK

The Transact SDK is the action layer for all Bill Management functionality.

The user will be guided through the Transact SDK experience, including any multi-factor authentication (MFA) steps required by their account provider. Once all necessary inputs have been collected, the user can exit the SDK. From there, any remaining actions—such as fetching account details or verifying credentials—can proceed in the background on the user’s device, without requiring further interaction.

User-driven selection

The Transact SDK includes views for a user to self-service account selection. If you do not have prior insights into which accounts a user has, or you don't wish to link user transactions to Atomic companies, this is the most straightforward way to launch the experience.

A product of present must be provided in order to launch the SDK within the Manage context.

Optionally, you can also include a deeplink parameter of "search-company" to skip the Welcome screen and take the user directly to the selection view. See the Transact SDK Parameters documentation for more information.

import { Atomic, Operation } from "@atomicfi/transact-react-native"

Atomic.transact({
  config: {
    scope: "pay-link",
    publicToken: "PUBLIC_TOKEN",
    tasks: [{ product: Product.PRESENT }],
    theme: {
      brandColor: "#9460FE",
      dark: false
    },
    language: "en",
    deeplink: {
      step: "login-company",
      companyId: "64ecca15ec669e000851d5d2"
    },
    search: {
      ruleId: "67571ed7b278a518d7d8abdf"
    },
    metadata: {
      version: "1.2.1",
      test: "New User Experience",
      testVariant: "B"
    }
  },
  onDataRequest: request => {
    // Handle data request for additional information
    console.log('Data request:', request.fields)
  },
  onAuthStatusUpdate: status => {
    console.log('Auth status:', status.status)
  },
  onTaskStatusUpdate: task => {
    console.log('Task', task.taskId, 'status:', task.status)
  },
  onError: error => {
    console.log('Error:', error)
  },
  onInteraction: interaction => {
    console.log('Interaction event:', interaction.name, interaction.value)
  },
  onClose: data => {
    console.log('Close event:', data.reason)
  }
})

At this point, users will complete the flow within the Transact SDK. You can pick up after we are done using the tools described in the Monitoring Progress section below.

Deeplinking

If you know which merchants a user pays or subscribes to, you can deeplink them directly to the account connection experience.

We recommend maintaining a mapping from a merchant (identified by name or by your id) to an Atomic _id. Atomic Company _ids can be acquired in two ways:

• By contacting your Customer Success Manager at Atomic.
• By consuming the Company Search API.

Company _ids are stable and do not change.

Pre-populated options

To streamline the process of onboarding multiple companies for a user, send Atomic a list of transactions or a list of merchants to pre-populate the experience for your users.

Account lifecycle

An Account is Atomic’s record of a user’s relationship with one company. Its connectionStatus tells you what Atomic can do with it right now.

Initial

The account exists in Atomic but the user has not signed in to the company. This is the state of an account created from transactions or company ids before the user connects. No bills, plans, or actions are available yet.

Connected

The user signed in to the company inside Transact, either through the connect flow or because they launched an action on a company they had not connected. Signing in is part of the first task: Atomic authenticates, keeps the session, and reads the account. From this point:

• Everything you read from Get Accounts, suggestions, and the actions list is a snapshot taken at lastSyncedAt.
• A refresh action, when listed on the account, re-reads the account against the stored session.
• Plan actions such as cancel, pause, and change plan run against the same session.
• Changes reach your backend through the pay-link-accounts-updated and task-status-updated webhooks. See the Ingest Data guide.

Disconnected

The session expired or the company revoked it. Atomic can no longer read or act on the account, and a refresh will not recover it. Atomic sends pay-link-accounts-updated with an updateType of disconnected. Show the user a reconnect prompt and launch Transact for the same company; a successful sign-in returns the account to connected.

UserLink deposit switching follows the same shape, with the user’s payroll provider in place of the merchant.