Manage Implementation Guide

Atomic offers solutions that enable users to view and modify their payroll information. The authentication process for users' payroll accounts must be conducted through our Transact interface. The specifics of your Transact integration may vary based on your particular use case and technology stack.

When users are authenticating into these systems, Atomic requires that the process be facilitated through one of our native Transact SDKs. Your integration with Transact will differ slightly depending on your specific use-case and tech stack.

Overview

Within an implementation with Atomic, data flows through the system as follows:

1
Request an access token from your server when the user opts to manage their account. Trigger this through a CTA (call-to-action) like "Manage Your Account," or use a suggested CTA if retrieving actions before establishing a connection.
2
On your server, request an access token from Atomic's API.
3
Using your generated access token, instantiate the Atomic Transact SDK using the manage operation for the Task.
4
The user authenticates into their account(s) via Transact. Your UI handles clientside events as they are emitted from the SDK.
5
Once connected, Atomic will pull relevant data from the account and make it available to your application.
6
Display available information and account management actions to users through your interface, such as payment dates, subscription modifications, or billing adjustments.
7
Optionally, receive webhook events to your server or pull Task data from the Atomic API.

Accordingly, you will need to build a few components to facilitate this process. You will need:

UI components to display any CTAs to your users
Client-side event handlers to handle the Transact SDK events
Server-side components to request access tokens from Atomic's API
Optional but recommended, a webhook receiver to listen for Atomic's webhook events

Refer to the Plan Your UX page for a more in-depth guide on design considerations.

Creating an AccessToken

To establish a connection to a 3rd party system, you will need to create an AccessToken via a call to the Atomic API, then instantiate Transact. These API calls are secured via your API Key and Secrets. You can retrieve your API credentials for the relevant environment from the Atomic Console.

Atomic uses client-side field level encryption with KMS keys to encrypt sensitive data such as account details in our system. If required, you can utilize a unique data key for encrypting data for your users. Reach out to your Atomic contact for more details.

Request an AccessToken server-side

An AccessToken for the end user is required to initialize Transact. To retrieve the AccessToken, make the following HTTPS request from your server.

This API call creates a user in the Atomic system using the identifier. All subsequent communications from Atomic, such as webhooks and client-side events, will contain this identifier to facilitate mapping corresponding data to the correct user.

POST/access-token

https://sandbox-api.atomicfi.com/access-token

Send publicToken to your client

The above request will result in a response with a publicToken.

You will need the publicToken from the response for setting up your client-side code to initialize Transact. Once it's been received on your server, send the publicToken to your client.

Response body

{
  "data": {
    "publicToken": "6e93549e-3571-4f57-b0f7-77b7cb0b5e48"
  }
}

Setting Up Transact

The Atomic Transact SDK is a client-side library that enables your application to connect users to merchants, subscription services, utility providers, and more. With this SDK, you can establish connections to external systems and present users with relevant data and actions, allowing them to manage their services directly within your application.

Create your configuration

Transact requires a configuration object when initialized in a live application. To get started you only need the publicToken from the previous step and the tasks you wish to execute. This configuration object has many options to customize the look and behavior of Transact.

For a full list of options, please refer to the Transact SDK Parameters Reference .

Configuration object

{
  "publicToken": "6e93549e-3571-4f57-b0f7-77b7cb0b5e48",
  "tasks": [
    {
      "operation": "manage"
    }
  ]
}

Add Transact to your app

Atomic's Transact is a client-side SDK that allows your users to connect their payroll accounts to your app.

Transact will handle credential validation, multi-factor authentication, and error handling for each system that we support. Transact supports browsers, native apps, and hybrid apps.

Receiving Data

As users navigate through the Transact flow, Atomic provides data about their actions and any created Tasks. The Transact SDK generates and emits client-side events during user interactions. Once a Task is created in the flow, you will receive webhooks containing Task-level details, such as the Task ID and Task status, all of these events will contain the identifier initially passed to Atomic when the AccessToken was created.

Transact Events

Transact emits events and passes them to your application as a user interacts with the UI. Such events allow applications to react and perform functions as needed. Some events will be passed with a data object with additional information.

When using the Atomic Console Emulator page all events emitted by the Transact instance are output on the page for you to explore.

For full documentation of Transact events, please refer to the Transact Events Reference .

PayLink APIs

The PayLink APIs enable you to retrieve account data and suggested actions to enhance your user experience. After a connection is established, you can access details such as account balances, due dates, and plan levels.

Alternatively, you can retrieve and present available actions for a company in your UI before a connection is made, if preferred. These actions, provided by Atomic, include options like canceling or pausing a subscription or adjusting a plan, allowing your system to determine the most relevant choices to present to the user.

Please refer to the PayLink API Reference documentation for more information.

Webhooks

As a Task is created and progresses, Atomic will issue webhooks to your configured endpoint(s).

You can configure webhook endpoints via the Atomic Console. Atomic will issue POST requests to the designated endpoint(s). We recommend using Hookbin as a way to inspect the payload of events during development without needing to stand up a server.

To aid building, we surface all webhooks for a Task in Console. Visit the details page of any Task in the Atomic Console and scroll down to the Webhooks Events section to view all of the data associated with that Task.

For full documentation of webhooks, please refer to the Webhooks Reference page. For more information on how to setup or secure webhooks, please refer to the Webhooks Guides Section section.

Presenting Data and Actions

With PayLink Manage, you can present users with account data and management actions either after establishing a connection or by retrieving and displaying the available actions for a specific service provider. The account data includes key details such as account balances, transaction history, and subscription plans. Additionally, you can provide both general actions applicable to the service provider and personalized actions tailored to the user's specific plan and account status, such as canceling or pausing a subscription, or adjusting a plan based on usage patterns.

Getting account data

Once a task-status-updated webhook indicating a successful Task has been received, data associated with the Task can be retrieved via an identifier for the user, which was passed to Atomic when the AccessToken was created. The API call will look something like this:

For more information and specifics on the APIs and webhooks, please refer to the associated reference pages.

Get User PayLink Accounts

// Using fetch
const identifier = 'USER_IDENTIFIER'
const response = await fetch(
  'https://api.atomic.com/:identifier/pay-link/accounts/',
  {
    method: 'GET',
    headers: {
      'x-api-key': 'YOUR_API_KEY',
      'x-api-secret': 'YOUR_API_SECRET',
      'Content-Type': 'application/json'
    }
  }
)
const accounts = await response.json()

Update your UI

Now that you have the account data, you can update your UI to display the account data and any actions or suggestions Atomic has for that user based on the state of their plan and access level within their account.

There is a full guide on how to take the information Atomic sends to you and layer it into your UI to build personalized and valuable UIs for your users here.

API Response

{
  "accounts": [
  "accounts": [
    {
      "_id": "67376c5befe988922e8aabc4",
      "company": {
        "_id": "6529a6eccb8e7200085c6ef6",
        "name": "Hulu",
        "branding": {
          "logo": {
            "url": "https://cdn-public.atomicfi.com/60e83c17-cda4-4b5a-98c6-c83199c54d48.png",
            "backgroundColor": "#040405"
      "_id": "67376c5befe988922e8aabc4",
      "company": {
        "_id": "6529a6eccb8e7200085c6ef6",
        "name": "Hulu",
        "branding": {
          "logo": {
            "url": "https://cdn-public.atomicfi.com/60e83c17-cda4-4b5a-98c6-c83199c54d48.png",
            "backgroundColor": "#040405"
          },
          "color": "#040405"
          "color": "#040405"
        }
      },
      "account": {
        "type": "subscription",
        "sourceId": "70236f02-dc3e-3419-bbf7-06d3da9d6685",
          "suggestions": [
          {
            "monthlySavings": 8.99,
            "category": "remove-service",
            "actionUrl": "Specific URL for launching into the cancel plan flow",
            "shortDescription": "Cancel mobile insurance.",
            "detailedDescription": "Cancel the Mobile Insurance Premium for the line 555-867-5309 to save $8.99 per month.",
            "buttonTitle": "Cancel Now"
          }
        ],
        "identities": [
          {
            "firstName": "test",
            "email": "test@email.com",
            "phone": "5558675309"
            "firstName": "test",
            "email": "test@email.com",
            "phone": "5558675309"
          }
        ],
        "billing": {
          "amount": 20.46,
          "dueDate": "2024-11-20T23:59:59.000Z",
          "autopay": {
            "status": "enabled",
            "cycle": "monthly"
        "billing": {
          "amount": 20.46,
          "dueDate": "2024-11-20T23:59:59.000Z",
          "autopay": {
            "status": "enabled",
            "cycle": "monthly"
          },
          "history": [
          "history": [
            {
              "date": "2024-10-20T18:00:54.761Z",
              "amount": 20.7
              "date": "2024-10-20T18:00:54.761Z",
              "amount": 20.7
            },
            {
              "date": "2024-09-20T09:48:31.093Z",
              "amount": 19.38
              "date": "2024-09-20T09:48:31.093Z",
              "amount": 19.38
            }
          ],
          "paymentMethods": [
          "paymentMethods": [
            {
              "type": "card",
              "lastFour": "2345",
              "brand": "Mastercard",
              "isPrimary": true
              "type": "card",
              "lastFour": "2345",
              "brand": "Mastercard",
              "isPrimary": true
            }
          ]
        },
        "data": {
          "plans": [
        "data": {
          "plans": [
            {
              "sourceId": "Hulu (No Ads)",
              "status": "active",
              "title": "Family Hulu Account",
              "description": "Hulu (No Ads)",
              "freeTrial": false
              "sourceId": "Hulu (No Ads)",
              "status": "active",
              "title": "Family Hulu Account",
              "description": "Hulu (No Ads)",
              "freeTrial": false
            }
          ],
          "usage": [
          "usage": [
            {
              "title": "profile",
              "description": "Test Profile"
              "title": "profile",
              "description": "Test Profile"
            }
          ]
        },
        _id: '67376c5befe988922e8aabc4'
      },
      "actions": [
      "actions": [
        {
          "type": "change-plan",
          "id": "BASE64_ENCODED_ID"
        },
        {
          "type": "cancel-plan",
          "id": "BASE64_ENCODED_ID"
          "type": "cancel-plan",
          "id": "BASE64_ENCODED_ID"
        }
      ],
      "type": "linked"
      "type": "linked"
    }
  ]
}

Suggested actions

Atomic will suggest actions to take based on the state of the user's account. These actions are returned in the API response and can be displayed in your UI as buttons. There will be recommended button text in the suggestions array, but these can be overridden as needed.

This is an example of what the suggested actions might look like in the API response: For more information on suggested actions, please refer to the API reference page.

Suggested Actions

// ...In response from PayLink Accounts API call
{
  "actions": [
    {
      "type": "change-plan",
      "id": "BASE64_ENCODED_ID"
    }
  ]
}