Atomic logo

Verify Implementation Guide

Atomic's products empower users to access and update their payroll data. When users are authenticating with their payroll account, Atomic requires that the process be facilitated through Transact. Your integration with Transact will differ slightly depending on your specific use-case and tech stack.

An implementation of Atomic breaks down into five steps:

  • 1

    Request an access token from your server.

  • 2

    On your server, request an access token from Atomic's API.

  • 3

    Using your generated access token, instantiate our Transact SDK.

  • 4

    The user links their payroll account(s) via Transact.

  • 5

    Optionally, receive webhook events to your server.

Data Flow Diagram

To authenticate an end user and start Transact, you will need your API Key and Secret from the Atomic Console.

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

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

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

We will need the publicToken from the response for setting up your client-side code to initialize Transact, so once its been received on your server, send the publicToken to your client.

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

On the Atomic Console there is an Emulator page where you can interactively configure and launch an instance of Transact.

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": [
    {
      "product": "verify"
    }
  ]
}

Atomic's Transact is a client-side SDK that allows your users to connect their employer 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.

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).

No matter the outcome of your test authentication, you will have the opportunity to receive data from us about the end user’s actions and the created task in multiple ways.

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.

For full documentation of webhooks, please refer to the Webhooks Reference page.

Transact emits events and passes them to your application. 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.