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, Product, Scope } from "@atomicfi/transact-react-native"
// Your implementation goes here
Atomic.transact({
config: {
scope: Scope.PAYLINK,
publicToken: "PUBLIC_TOKEN",
tasks: [{ product: Product.PRESENT}]
},
onInteraction: interaction => {
console.log('Interaction event:', interaction.name, interaction.value)
},
onFinish: data => {
console.log('Finish event:', data.taskId, data.handoff)
},
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.
Monitoring progress
As Atomic connects a user’s account and processes actions, we provide several mechanisms for monitoring progress within the experience. To support this, you’ll need to implement one of the integration patterns outlined below.
Monitoring via Transact Events
The Transact SDK emits multiple kinds of events which can be handled with callbacks in your client-side application. Comprehensive documentation of these events can be found in the Transact SDK documentation, but a few are particularly important for rendering updates in your UI.
onTaskStatusUpdate is triggered multiple times during a task’s lifecycle. Use it to show a pending UI when the task enters a processing state, and to update or clear the UI when it completes or fails. It also provides task and company details—useful for retrieving data later and displaying more specific progress indicators, especially when users connect multiple companies.
Atomic provides other Transact events, such as onFinish or onClose, but since these are not compatible with Actions, we recommend using onTaskStatusUpdate for consistency in all Manage products.
Monitoring via Webhooks
Webhooks provide a real time update to your backend when we retrieve data, complete tasks, or complete other important milestones. As they are a core part of Atomic's product, detailed documentation can be found both in the Ingest Data guide or the Webhooks reference.
In brief, webhooks return events on similar milestones as the above onTaskStatusUpdate hook. The task-status-updated webhook will be called on transitions between processing, failed, or completed states. Typically, you will retrieve data from Atomic either directly from a webhook, or from the API when you receive a webhook indicating a task is complete.
Monitoring via API Polling
If you are unable to consume webhooks, it is also possible to keep track of task status by polling the Get Task Status endpoint. This endpoint is designed to be lightweight to be called repeatedly. To call this endpoint, you will need to collect the task _id from the client-side events.
We are able to support a number of polling strategies, but please be considerate when polling this endpoint. We recommend a 5 second interval, and backing off the polling interval after 2 minutes. Tasks should complete after five minutes, so we recommend terminating your poll if it has not completed in that time frame.