Atomic logo
Transact SDK

Transact SDK Reference

Atomic Transact SDK is a UI designed to securely handle interactions with our products while performing the heavy-lifting of integration.

The Transact iOS SDK can be installed either with the Swift Package Manager or through CocoaPods.

Requirements

  • Xcode 12.0 or greater
  • iOS 13.0 or greater

Swift Package Manager

Inside Xcode, go to Project Settings -> Project -> Package Dependencies and click the + to add a new Package.

Swift Package Installation
Enter the Package URL
https://github.com/atomicfi/atomic-transact-ios

CocoaPods

Installation
pod 'AtomicSDK'
# pod 'AtomicSDK/SwiftUI'

The AtomicConfig class can be used to customize the Transact experience using any of the Transact SDK Parameters.

UIKit Example
import AtomicTransact

// Your implementation goes here

let config = AtomicConfig(publicToken: "6e93549e-3571-4f57-b0f7-77b7cb0b5e48", tasks: [.init(product: .deposit)])

Atomic.presentTransact(from: self, config: config, onInteraction: { interaction in
    print("Interaction event: \(interaction.name) \(interaction.value)")
  }, onCompletion: { result in
  switch result {
    case .finished(let response):
      print("Finish event: \(response.taskId) \(response.handoff)")
    case .closed(let response):
      print("Close event: \(response.reason)")
    case .error(let error):
      print("Transact returned with error: \(error)")
  }
})
SwiftUI Example
import AtomicTransact
import AtomicTransactSwiftUI

// Your implementation goes here

struct MyView: View {
  @State var showingTransact = false
  
  var body: some View {
    // Your implementation goes here
    .atomicTransact(
      isPresented: $showingTransact,
      config: {
        AtomicConfig(publicToken: "6e93549e-3571-4f57-b0f7-77b7cb0b5e48", tasks: [.init(product: .deposit)])
      },
      onCompletion: { result in
        switch result {
        case .finished(let response):
          print("Finish event: \(response.taskId) \(response.handoff)")
        case .closed(let response):
          print("Close event: \(response.reason)")
        case .error(let error):
          print("Transact returned with error: \(error)")
        }
      })
      .onReceive(Atomic.interactions) { interaction in
        print("Interaction event: \(interaction.name) \(interaction.value)")
      }
  }
}

Update your project plugins

In your root-level (project-level) Gradle file (build.gradle), add rules to include the Android Gradle plugin. Check that you have Google's Maven repository as well.

build.gradle (Project-level)
buildscript {
  repositories {
    // Check that you have the following line (if not, add it):
    google()  // Google's Maven repository
    mavenCentral() // Include to import Transact Android SDK
  }
  dependencies {
    // ...
  }
}

Add the Transact SDK to your app

In your module (app-level) Gradle file (usually app/build.gradle), add a line to the bottom of the file. The latest version of the SDK is Maven Central.

build.gradle (App-level)
android {
  defaultConfig {
    minSdkVersion 21 // or greater
  }

  // Enable Java 8 support for Transact to work
  compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
  }
}

dependencies {
  // ...
  implementation 'financial.atomic:transact:<insert latest version>'
}
Kotlin Example
import org.json.JSONObject
import financial.atomic.transact.*
import financial.atomic.transact.receiver.TransactBroadcastReceiver

// Your implementation goes here

val config = Config(
  publicToken = "6e93549e-3571-4f57-b0f7-77b7cb0b5e48",
  tasks = listOf(Config.Task(product = Config.Product.DEPOSIT))
)

Transact.registerReceiver(context, object: TransactBroadcastReceiver() {
  override fun onClose(data: JSONObject) {
    Log.d("APP", "Close event: ${data.getString("reason")}")
  }
  override fun onFinish(data: JSONObject) {
    Log.d("APP", "Finish event: ${data.getString("taskId")} ${data.optString("handoff")}")
  }
  override fun onInteraction(data: JSONObject) {
    Log.d("APP", "Interaction event: ${data.getString("name")} ${data.getJSONObject("value")}")
  }
})

Transact.present(context, config)

Transact can be initialized by including our React Native SDK in your app and then calling the Atomic.transact method and passing it a configuration object.

Installation
yarn add @atomicfi/transact-react-native

iOS Setup

  • Xcode 12.0 or greater
  • iOS 13.0 or greater
Install CocoaPods Dependencies
(cd ios && pod install)

For applications using the Expo managed workflow, see the Expo documentation about using Native Modules.

Android Setup

Autolinking should set up everything when building.

React Native Example
import { Atomic, Product } from "@atomicfi/transact-react-native"

// Your implementation goes here

Atomic.transact({
  config: {
    publicToken: "6e93549e-3571-4f57-b0f7-77b7cb0b5e48",
    tasks: [{ product: Product.DEPOSIT }]
  },
  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)
  }
})

A Flutter plugin that wraps the native Atomic Transact SDKs. View the plugin with a code example on Github

Add atomic_transact_flutter as a dependency in your pubspec.yaml file

Dependency in pubspec.yaml file
dependencies:
  ...
  atomic_transact_flutter: <version>

iOS Requirements

  • Xcode 12.0 or greater
  • iOS 13.0 or greater

Android Requirements

Set the minSdkVersion in android/app/build/gradle

Minimum SDK Version
android {
  defaultConfig {
    minSdkVersion 21 // or greater
  }
}
Flutter Example
import 'package:atomic_transact_flutter/atomic_transact_flutter.dart';
// Your implementation goes here

Atomic.transact(
  config: AtomicConfig(
    publicToken: "6e93549e-3571-4f57-b0f7-77b7cb0b5e48",
    tasks: [AtomicTask(product: AtomicProductType.deposit)],
  ),
  onInteraction: (AtomicTransactInteraction interaction) {
    print("onInteraction");
  },
  onDataRequest: (AtomicTransactDataRequest request) {
    print("onDataRequest");
  },
  onCompletion: (AtomicTransactCompletionType type,
      AtomicTransactResponse? response, AtomicTransactError? error) {
    print("onCompletion");
  },
);

Transact can be initialized by including our JavaScript SDK in your page and then calling the Atomic.transact method and passing it a configuration object.

Installation
npm install @atomicfi/transact-javascript
Browser Example
import { Atomic, Product } from "@atomicfi/transact-javascript"

// Your implementation goes here

Atomic.transact({
  config: {
    publicToken: "6e93549e-3571-4f57-b0f7-77b7cb0b5e48",
    tasks: [{ product: Product.DEPOSIT }]
  },
  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)
  }
})
Atomic does not recommend the use of webviews for new integrations. Atomic's SDKs for Android, iOS, and React Native provide the easiest and best way to build a mobile Transact experience and are recommended for all developers.

Within the context of a mobile app, you may use a web view (for example, WKWebView on iOS) by building a simple self-hosted wrapper page.

The BASE64 Encoded String is made up of an object containing the parameters used within the SDK (excluding onFinish, onClose, and onInteraction).

Configuration object
{
  "publicToken": "6e93549e-3571-4f57-b0f7-77b7cb0b5e48",
  "tasks": [
    {
      "product": "deposit"
    }
  ]
}
Example Initialize URL
https://transact.atomicfi.com/initialize/ewogICAgInB1YmxpY1Rva2VuIjogIjZlOTM1NDllLTM1NzEtNGY1Ny1iMGY3LTc3YjdjYjBiNWU0OCIsCiAgICAicHJvZHVjdCI6ICJkZXBvc2l0Igp9

When using the Transact SDK, the configuration object can be heavily customized to change the look and user experience. Below are all of the available options for customization.

publicTokenstring
The public token returned during AccessToken creation.
tasks[TaskConfiguration]
Defines configuration for the tasks you wish to execute as part of the task workflow.
Child Properties
productstring
One of deposit or verify.
onCompletestring
The action to take on completion of the task. Can be either "continue" or "finish." To execute the next task, use "continue." To finish the task workflow and not execute any of the subsequent tasks, use "finish."

Default value: "continue"

onFailstring
The action to take on failure of the task. Can be either "continue" or "finish." To execute the next task, use "continue." To finish the task workflow and not execute any of the subsequent tasks, use "finish."

Default value: "continue"

distributionobject
Optionally pass in enforced deposit settings. Enforcing deposit settings will eliminate company search results that do not support the distribution settings.
Child Properties
typestring
Can be total to indicate the remaining balance of their paycheck, fixed to indicate a specific dollar amount, or percent to indicate a percentage of their paycheck.
amountnumber

When distribution.type is fixed, it indicates a dollar amount to be used for the distribution. When distribution.type is percent, it indicates a percentage of a paycheck. This is not required if distribution.type is total.

This value cannot be updated by the user unless canUpdate is set to true.

canUpdateboolean
Allows a user to specify any amount they would like, overwriting the default amount.

Default value: false

inSdkboolean
When false, close buttons and SDK events are not broadcast.

Default value: true

themeobject
Object containing properties to customize the look of Transact.
Child Properties
brandColorstring
Accepts valid values for use with the color CSS property. For example: #FF0000 or rgb(255, 0, 0). This property will mostly be applied to buttons.
overlayColorstring
Accepts valid values for use with the background-color CSS property. For example: #FF0000 or rgb(255, 0, 0). This property will change the overlay background color. This overlay is mainly only seen when Transact is used on a Desktop.
darkboolean
Change the overall theme to be dark mode.
deeplinkobject
Object containing properties to deeplink users into a specific step.
Child Properties
stepstring
Acceptable values are search-company, search-payroll, and login-company. If the value is login-company, then the companyId is required.
companyIdstring
Required if the step is login-company. Accepts the ID of the company.
companyNamestring
Required if the step is search-payroll or login-payroll. Accepts a string of the company name.
languagestring
Optionally pass in a language. Acceptable values: en for English and es for Spanish.

Default value: en

linkedAccountstring
Optionally pass the _id of a LinkedAccount. When used, Transact will immediately begin authenticating upon opening. This parameter is used when the LinkedAccount's transactRequired flag is set to true.
searchobject
Optionally, enforce search queries.
Child Properties
tags[string]
Filters companies by a specific tag. Possible values include gig-economy, payroll-provider, and unemployment.
excludedTags[string]
Exclude companies by a specific tag. Possible values include gig-economy, payroll-provider, and unemployment.
metadataobject
Optionally pass data to Transact that will be returned to you in webhook events. Common use-cases for this include application version, build number, or commit hash for issue tracking and test name and variant for A/B testing.
handoff[string]
Handoff allows views to be handled outside of Transact. In place of the view, corresponding SDK events will be emitted that allows apps to respond and handle these views. Accepts an array. The values available are exit-prompt, authentication-success, and high-latency. See Handoff Pages for more detail.
experimentsobject
Object containing properties to override feature flags found in your Atomic Console settings. This parameter can help run A/B tests on features within Transact.
Child Properties
fractionalDepositsboolean
Override the Fractional Deposit feature value set within your Atomic Console settings.
unemploymentCarouselboolean
Override the Unemployment Carousel feature value set within your Atomic Console settings.
onFinishfunction
A function that is called when the user finishes the transaction. The function will receive a data parameter which contains metadata about the executed task.
onClosefunction
Called when the user exits Transact prematurely.
onInteractionfunction
Called when the user interacts with Transact.
Sample SDK parameters
{
  "publicToken": "PUBLIC_TOKEN",
  "tasks": [
    {
      "product": "deposit",
      "distribution": {
        "type": "fixed",
        "amount": 50,
        "action": "create"
      }
    }
  ],
  "theme": {
    "brandColor": "#1b1464",
    "overlayColor": "#CCCCCC"
  },
  "deeplink": {
    "step": "search-company"
  },
  "language": "en",
  "metadata": {
    "version": "1.2.1",
    "test": "New User Experience",
    "testVariant": "B"
  }
}

The below page names can be added to the handoff array to allow views to be handled outside of Transact.

exit-prompt
If the user has reached the login page and decides to exit, they are prompted with a view that asks them to confirm their exit. When exit-prompt is passed into the handoff array, users will no longer be presented with the exit confirmation. The atomic-transact-close event will be triggered in its place. The event will also send the following data: { handoff: 'exit-prompt' }.
authentication-success
When authentication is successful, the user is taken to the success view within Transact. When authentication-success is passed into the handoff array, users will no longer be taken to the success view. The atomic-transact-finish event will be triggered in its place. The event will also send the following data: { handoff: 'authentication-success' }.
high-latency
When authentication takes much longer than expected, the user is taken to the the high latency view within Transact. When high-latency is passed into the handoff array, users will no longer be taken to this view. The atomic-transact-close event will be triggered in its place. The event will also send the following data: { handoff: 'high-latency' }.

When using the SDK, events will be emitted and passed to the native application. Such events allow native applications to react and perform functions as needed. Some events will be passed with a data object with additional information.

onClose

Triggered in several different instances:

  1. If a user does not find their employer and payroll provider, the data passed with the event will be { reason: 'zero-search-results' }.
  2. During the Transact process if a user is prompted to keep waiting or exit and they choose to exit, the data passed with the event will be { reason: 'task-pending' }.
  3. At any point if the user clicks on the x the data passed with the event will be { reason: 'unknown' }.
onFinish

Triggered when the user reaches the success screen and closes Transact. The data passed with the event will include the taskId.

onInteraction
Triggered on interactions within Transact. For example, when a user transitions to a news screen or presses the back button. The data passed with the event will be { name: "NAME OF THE EVENT", value: { OBJECT CONTAINING EVENT VALUES } }. Details can be found below in the interaction events list.

These are the event names that will appear in an onInteraction event.

Viewed Access Unauthorized Page
User did not have a valid token
Viewed Authentication Failed Page
User viewed the page indicating authentication failed
Viewed Authentication Paused Page
User viewed the page indicating authentication paused
Viewed Authentication Success Page
User viewed the page indicating authentication was successful
Viewed Distribution Confirmation Page
User viewed the distribution confirmation page
Viewed Expired Token Page
User has an expired token
Viewed Fixed Deposit Amount Page
User viewed the fixed deposit amount page
Viewed Fractional Deposit Error Page
User viewed the fractional deposit error page
Viewed High Latency Page
User viewed the high latency page
Viewed Learn How You Are Protected Page
User viewed the learn how you are protected page
Viewed Login Page
User viewed the login page
Viewed Login Help Page
User viewed the login help page
Viewed Login Recovery Page
User viewed the login recovery page
Viewed Manual Deposit Instructions Page
User viewed manual deposit instructions page
Viewed MFA Page
User viewed the multi factor authentication page
Viewed Percentage Deposit Amount Page
User viewed the percentage deposit amount page
Viewed Search By Company Page
User viewed the search by company page
Viewed Search By Configurable Connector Page
User viewed the search by configurable connector/payroll provider page
Viewed Search By Payroll Page
User viewed the search by payroll page
Viewed Select From Deposit Options Page
User viewed the select from deposit options page
Viewed Select From Multiple Accounts Page
User viewed the select from multiple accounts page
Viewed Select From Multiple Payroll Providers Page
User viwed the select from available payroll providers page
Viewed Terms And Conditions Are Required Page
User viewed the terms and conditions required page
Viewed Terms And Conditions Page
User viewed the terms and conditions page
Viewed Under Maintenance Page
User viewed a company/payroll provider that is under maintenance
Viewed Welcome Page
User viewed the welcome page
Sample interaction event
{
  "name": "Viewed Access Unauthorized Page",
  "value": {
    "customer": "Atomic",
    "language": "en",
    "product": "deposit"
  }
}

This includes a subset of our other events.

Search By Company
User has searched for a company/employer
Search By Payroll
User has searched for a payroll provider

When initializing the Transact SDK or creating a Task using a Linked Account you can pass a metadata parameter. You can use this parameter to attach key-value data that will be returned in webhook events.

Metadata is useful for storing additional, structured information on a Task. As an example, you could store an order ID from your system to track your user's process with a direct deposit. Metadata is not used by Atomic and won't be seen by your users.

Do not store any sensitive information (bank account numbers, card details, etc.) as metadata.

Once Transact has been initialized, you will be entered into the flow that your end users will experience where you will select or search for an employer or payroll provider. Upon selection, you will be prompted to enter credentials.

To aid in testing various user experiences, you may use any of these pre-determined "test" credentials for employer authentication. Any password will work as long as the username is found in this list. When answering MFA questions, any answer will be accepted. If the authentication requires an email, simply append @test.com to the end of the chosen username.

Upon submission of your credentials, a task is created in Atomic’s system to process the end user’s data.

UsernameDescription
test-goodTest a successful authentication.
test-badTest an unsuccessful authentication.
test-failureTest a failure that occurs after a successful authentication.
test-high-latencyTest the flow which occurs when there is high latency communicating with backend systems.
test-code-mfaTest an authentication that includes a device code based MFA flow.
test-push-mfaTest an authentication that simulates push-based MFA.
test-question-mfaTest an authentication that simulates question-based MFA.
test-lockoutTest a user who has been locked out of their account.

Post-Authentication

After authentication your user experience in Transact will differ depending on the credentials used for authentication. If you use credentials that result in a successful authentication, you will be greeted with a success page. If not, you will be greeted with a failure page explaining your next possible action(s).