Insurance 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.
Overview
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.
Authentication
To authenticate an end user and start Transact, you will need your API Key and Secret from the Atomic Console.
Request an AccessToken server-side
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-tokenSend publicToken to your client
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.
{
"data": {
"publicToken": "6e93549e-3571-4f57-b0f7-77b7cb0b5e48"
}
}Try it in the Emulator
On the Emulator page on the Atomic Console you can interactively configure and launch an instance of Transact.
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.
{
"publicToken": "6e93549e-3571-4f57-b0f7-77b7cb0b5e48",
"tasks": [
{
"product": "insurance"
}
]
}Add Transact to your app
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.
Testing
To aid in testing various user experiences, you may use any of these pre-determined "test" credentials for authentication. Any password will work as long as the username is found in these lists. If the authentication requires an email, simply append @example.com to the end of the chosen username.
Upon submission of your credentials, a test task is created in Atomic’s system to process the end user’s data. These credentials can be toggled off for production use in the Atomic Console.
Successful authentication
Test where the user's credentials are correct and the task completes. When answering MFA questions, any answer will be accepted.
| Username | Phone Number | Description |
|---|---|---|
test-good | (555) 555-0100 | Test a successful authentication. |
test-code-mfa | (555) 555-0101 | Test an authentication that includes a device code based MFA flow. |
test-push-mfa | (555) 555-0102 | Test an authentication that simulates push-based MFA. |
test-question-mfa | (555) 555-0103 | Test an authentication that simulates question-based MFA. |
Payroll system issue
Test where the user encounters an issue in the payroll system.
| Username | Phone Number | Description |
|---|---|---|
test-system-unavailable | (555) 555-0104 | Test the user experience during a payroll system outage. |
test-unknown-failure | (555) 555-0105 | Test the user experience when there is an unexpected error. |
test-session-timeout | (555) 555-0106 | Test a user whose payroll auth session has timed out. |
test-connection-error | (555) 555-0107 | Test the user experience when there is a connection error caused by a network failure. |
test-high-latency | (555) 555-0108 | Test the flow which occurs when there is high latency communicating with backend systems. |
test-post-auth-delay | (555) 555-0109 | Test the flow when there is a post-auth delay happening. This may occur due to an unanticipated change in the payroll system. |
test-failure | (555) 555-0110 | Test a failure that occurs after a successful authentication. |
Payroll system configuration
Test where the user encounters an issue with their payroll system configuration or access.
| Username | Phone Number | Description |
|---|---|---|
test-distribution-not-supported | (555) 555-0111 | Test a user who enters an unsupported deposit amount. |
test-routing-number-not-supported | (555) 555-0112 | Test a user whose payroll system rejects the routing number of the target deposit account. |
test-product-not-supported | (555) 555-0113 | Test a user who is not an active employee in the payroll system. |
User issue
Test where there is an error that occurs due to an action of the user.
| Username | Phone Number | Description |
|---|---|---|
test-bad | (555) 555-0114 | Test an unsuccessful authentication. |
test-lockout | (555) 555-0115 | Test a user who has been locked out of their account. |
test-account-unusable | (555) 555-0116 | Test a user whose payroll account rejects the target deposit account. |
test-enrolled-in-paycard | (555) 555-0117 | Test a user enrolled in a paycard, which prevents payment via direct deposit. |
test-expired | (555) 555-0118 | Test a user whose payroll password has expired. |
test-transaction-pending | (555) 555-0119 | Test a user who already has a direct deposit change in progress. |
test-account-setup-incomplete | (555) 555-0120 | Test a user who has not fully onboarded to their employee payroll system. |
test-work-status-terminated | (555) 555-0121 | Test a user who is not an active employee in the payroll system. |
Receiving Data
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.
Webhooks
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.
Transact Events
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.