PayLink API Reference
Atomic's API is built around RESTful principles, using JSON encoded request and response bodies.
To get going quickly, we recommend using Postman - an API collaboration tool. Atomic provides a public workspace which you can fork into your own workspace. Use the button below to get started.
The workspace comes fully documented with:
- several useful flows using our APIs
- requests for all of the Atomic endpoints
- an environment containing placeholders for all the variables needed to connect to your Sandbox instance of Console
Authentication
Atomic uses a combination of API keys and access tokens to authenticate requests. Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, etc.
API Key and Secret
You can retrieve and manage your API key and secrets on the credentials page on the Atomic Console. Include these headers in requests that are secured with your API Key and Secret:
Header | Description |
---|---|
x-api-key | API Key for your Atomic account |
x-api-secret | API Secret for your Atomic account |
Access Token
These headers are included in requests that are made via the end user from client-side code, e.g. searching for their employer. The public token
defaults to a 24 hour expiry, but can be set to a minimum of 30 minutes by passing in the desired duration using the optional tokenLifetime
property in the call to /access-token
. This minimum is to allow for users to complete variations of the flows, such as MFA, which can take time.
Header | Description |
---|---|
x-public-token | Public token generated during access token creation. |
Errors
Our API returns standard HTTP success or error status codes. For errors, we will also include extra information about what went wrong encoded in the response as JSON. The various HTTP status codes we might return are listed below.
Code | Title | Description |
---|---|---|
200 | OK | The request was successful. |
400 | Bad Request | The request was unacceptable. |
401 | Unauthorized | Missing or invalid credentials. |
404 | Not Found | The resource does not exist. |
422 | Validation error | A validation error occurred. |
50X | Internal Server Error | An error occurred with our API. |
API Versioning
The Atomic API accepts an x-atomic-version
header. This is a mechanism we have put in place to ensure stability as the surface of the API changes over time. A new version will be released when there are backward incompatible changes to the API. We will publish a changelog and migration guides as new versions are rolled out to highlight any relevant changes and make migrations seamless for consumers of our API.
To use the version header, append the x-atomic-version
header to all calls to the Atomic API. The value of the header will follow standardized CalVer practices. The current version is 2022-12-02
.
x-atomic-version
Date- A Date-string in the form of
YYYY-MM-DD
. Specific versions to be provided by Atomic.
Header | Description |
---|---|
x-atomic-version | Date string of the required API version |
Access Token
An AccessToken
grants access to Atomic's API resources for an end user when its value is used as the x-public-token
header.
To create an access token pass in an identifier and identity data for the end user as well as associated account or card details.
- If you control all the account and/or card data you would like the end user to select from when updating their payments in the vendor systems, use the Create an Access Token.
- If your card data is managed by a 3rd party, we have a flow where we can pull the tokenized card data. Replace the card details object in the Create an Access Token with the data as shown in the Access Token with BaaS passthrough section.
- If you want to transmit card data after the user has authenticated with the merchant, use the Create an Access Token api, but
lastFour
andtitle
are the only required properties on the card object.
Create Access Token
This API is intended to be used when the calling application is able to send all required data fields to Atomic directly.
pci.atomicfi.com
in production, and sandbox-pci.atomicfi.com
in sandbox. Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.
Required Properties
identifier
string- A unique identifier from your system that will be used to reference this user. This could be a primary key used in your system or another unique identifier. Creating multiple access tokens with the same identifier will tie those tokens to the same user in Atomic's system.
cards
[CardDetails]- An array of card detail objects which the end user can select from to update their card on file. Details for either an account or a card must be provided to complete the operation.
accounts
[AccountDetails]- An array of account detail objects which the end user can select from to update their account on file. Details for one of either an ACH account or card must be provided to complete the operation.
identity
object- Details about the end user's identity. These details are regularly required to make an update to a vendor system.
POST
/access-tokenBaaS passthrough variation
This version of the API is intended to be used when the calling application is not PCI compliant itself, but rather relies on a BaaS provider to handle the card data. See our guide on transmitting card data for details on whether or not this endpoint is for you.
Properties not explicitly defined in this section will function and be required in the same manner as the Create Access Token flow.
Required Properties
cards
[CardDetails]- An array of card detail objects which the end user can select from to update their card on file. Details for either an account or a card must be provided to complete the operation.
Child Properties
Required Properties
lastFour
string- The last four digits of a card number.
title
string- Title for the card
paymentService
object- Object containing details required for Atomic to connect to and utilitize a BaaS card provider
Child Properties
Required Properties
galileo
object- String which indicates the associated BaaS you use as your card provider. This example uses Galileo, if another other BaaS provider is required, please reach out to your contacts at Atomic.
Child Properties
Required Properties
apiLogin
string- Web service username, as provided by Galileo.
apiTransKey
string- Web service password, as provided by Galileo.
providerId
string- Galileo-issued provider identifier.
transactionId
string- A unique provider-generated ID to identify this API call. A UUID is preferred.
accountNo
string- The PRN, PAN or CAD of the account. For card-specific endpoints such as this one, the CAD is preferred. Do not use the PRN if more than one card has ever been associated with this account.
apiUrl
string- The production url that your organization uses to connect to Galileo.
POST
/access-tokenTask
Each discrete payroll operation, such as a verification of income, direct deposit switch, or update to a payment account of file, will instantiate what is referred to as a Task in our system. A Task consists of an authentication step where Atomic logs into a payroll or service provider and an operation step where we read data or write to the system; either a direct deposit allocation or updating a payment account on file, depending on the Task.
Get Task Details
This endpoint returns the details of a Task. Submit the corresponding taskId
and receive the details of that Task.
Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.
Required Properties
taskId
string- The id of the Task. The
taskId
property is sent in mulitple webhooks or any of the interaction events which are fired after the authentication phase of the flow has begun.
GET
/task/:taskId/detailsResponse
A successful request will return the details of the task.
_id
string- The id of the task.
authenticated
boolean- Indicates whether or not the task has successfully authenticated against the payroll system.
company
object- Metadata for the employer.
Child Properties
connector
object- Metadata for the connector.
Child Properties
createdAt
date- The timestamp when the task was created, stored in UTC and ISO 8601 format.
updatedAt
date- The timestamp when the task was last updated, stored in UTC and ISO 8601 format.
depositData
objectOptional- If the task is a deposit task, this data will indicate the type of deposit switch performed.
Child Properties
Optional Properties
accountType
stringThe type of the account. Possible values includesavings
,checking
, orpaycard
.distributionAmount
numberThe amount being distributed to the account. WhendistributionType
ispercent
, the number represents a percentage of the total pay. WhendistributionType
isfixed
, this number represents a fixed dollar amount. This value is not set whendistributionType
istotal
.distributionType
stringThe type of distribution for the account. Possible values includetotal
,percent
, orfixed
.lastFour
stringThe last digits of the account number.routingNumber
stringThe routing number.title
stringThe title of the account. failReason
stringOptional- The failure reason associated with a failed task. Will consist of one of the failure values.
linkedAccount
stringOptional- The id of the linked account used to create the task.
metadata
objectOptional- The
metadata
provided by your system when the task was initialized. payrollDataAvailable
boolean- A boolean value indicating whether or not the user's payroll data is ready for retrieval via api.
product
string- The product of the task. Possible values include
deposit
,verify
, andtax
. status
string- The status of the task which may be
queued
,processing
,failed
, orcompleted
. taskWorkflow
object- The task workflow of the task.
user
object- The user that ran the task.
Child Properties
Optional Properties
_id
stringThe id of the user in atomic's system.identifier
stringThe user's unique identifier, as sent to Atomic during AccessToken creation.
{
"data": {
"task": {
"_id": "65b15fd99b3f03aa9edff9de",
"authenticated": true,
"company": {
"_id": "607e249736b9f053b536bde0",
"branding": {
"logo": {
"url": "https://cdn-public.atomicfi.com/b02670fa-ce1b-4171-855b-6856b37bb938.png"
}
},
"name": "Test Company"
},
"connector": {
"_id": "607e249736b9f053b536bde1",
"branding": {
"logo": {
"url": "https://cdn-public.atomicfi.com/b02670fa-ce1b-4171-855b-6856b37bb938.png"
}
},
"name": "Test Connector"
},
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:05.000Z",
"depositData": {
"accountType": "checking",
"distributionAmount": 10,
"distributionType": "fixed",
"lastFour": "0000",
"routingNumber": "22000000",
"title": "Checking Account"
},
"failReason": "unknown-failure",
"linkedAccount": "645963a0b754649972f3d4ac",
"metadata": {
"data": "test"
},
"payrollDataAvailable": false,
"product": "deposit",
"status": "failed",
"taskWorkflow": {
"_id": "643f2ed34253e21bdbd2de31"
},
"user": {
"_id": "607e249736b9f053b536bdea",
"identifier": "GUID"
}
}
}
}
Get Task Status
Calling this API returns the status of a Task. Submit the corresponding taskId
and receive the status
of that Task and payrollDataAvailable
which indicates that any fetchable data is ready to be pulled via the corresponding API calls.
This endpoint is designed to be lightweight and intended for polling use cases.
Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.
Required Properties
taskId
string- The id of the Task. The
taskId
property is sent in mulitple webhooks or any of the interaction events which are fired after the authentication phase of the flow has begun.
GET
/task/:taskId/statusResponse
A successful request will return the createdAt
date, status
, and if a Task failed (Tasks with a status of "failed") a failReason
.
createdAt
date- The timestamp when the Task was created, stored in UTC and ISO 8601 format.
status
string- The status of the task which may be
queued
,processing
,failed
, orcompleted
. failReason
stringOptional- The failure reason associated with a failed task. Will consist of one of the failure values.
{
"data": {
"task": {
"createdAt": "2023-01-03T16:40:48.009Z",
"status": "failed",
"failReason": "no-data-found",
"payrollDataAvailable": false
}
}
}
Generate File URL
Generate a URL in order to download a user file (ex: paystubs PDFs). Each URL is valid for 1 hour.
Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.
Required Properties
taskId
string- The
_id
of the Task, which can be retrieved either from interaction events during the Transact session with the user or from the associated webhooks. fileId
string- The
_id
of the file. This is returned in API calls for relevant data categories, such as/taxes
for W-2's, or sent via relevant webhooks when a file is retrieved from the payroll system.
GET
/task/:taskId/file/:fileId/generate-urlResponse
A successful request will return a URL that can be used to download the file.
url
string- A URL that can be used to download the file. The URL is valid for 1 hour.
{
"url": "[ATOMIC-GENERATED-PRESIGNED-S3-URL]"
}
PrescreenBeta
Prescreen is an endpoint you can call prior to task creation in order to get a predicted conversion confidence, offering additional insight into your user and the likelihood they will succeed using our service.
Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.
POST
/task/prescreenResponse
The response returns an object with a single confidence property as a string value. We will make this determination based on a variety of proprietary considerations such as traffic volumes and calculations with other similar connector types.
confidence
string- The likelihood of the user being successful using our flow. Will return a value of "HIGH" or "LOW".
{
"data": {
"confidence": "HIGH"
}
}
User
A User
is an entity in the Atomic system that is created during the access token creation process. Details about a user's accounts are stored on the user object for reference as needed in an operation; ie. for adding a deposit account to a payroll system or updating the card-on-file for a merchant service.
Update User
This endpoint is used to add data to a user in response to an onDataRequest
event emitted from our Transact SDK. Any data passed will be upserted into the user's object. The typical use case is to delay the transmission of sensitive data (bank accounts, cards, identity information, etc.) until our system has need for such data.
The shape of the request body is similar to our access token creation endpoint, except the data to be added/updated will be nested in a data
key, and the identifier
will not be nested, but remain on the first-level of the object.
Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.
PUT
/userGet Tasks
This endpoint is used to retrieve tasks for the specified user.
Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.
Required Properties
identifier
string- The user's unique identifier, as sent to Atomic during AccessToken creation.
Optional Properties
status
string
queued
, processing
, failed
, or completed
.payrollDataAvailable
string
GET
/user/:identifier/tasksResponse
A successful response will return an object with data.tasks
equal to an array of task objects with the following properties.
_id
string- The id of the task.
authenticated
boolean- A boolean value indication whether or not the task has successfully authenticated against the payroll system.
createdAt
date- The timestamp when the task was created, stored in UTC and ISO 8601 format.
failReason
stringOptional- The failure reason associated with a failed task. Will consist of one of the failure values.
payrollDataAvailable
boolean- A boolean value indicating whether or not the user's payroll data is ready for retrieval via api.
product
enum- The product relevant to the executed task. Options are:
deposit
verify
status
string- The status of the task which may be
queued
,processing
,failed
, orcompleted
.
{
"data": {
"tasks": [
{
"_id": "65b3f3c8b871a9626c36d103",
"authenticated": true,
"createdAt": "2024-01-26T18:02:55.795Z",
"payrollDataAvailable": true,
"product": "verify",
"status": "completed"
},
{
"_id": "65b3f3c8b871a9626c36d103",
"authenticated": true,
"createdAt": "2024-01-26T18:02:55.795Z",
"failReason": "bad-credentials",
"payrollDataAvailable": false,
"product": "deposit",
"status": "failed"
}
]
}
}
End Monitoring
This endpoint is used to remove monitoring for users that have payroll data monitoring enabled via continuous access.
Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.
Required Properties
identifier
string- The user's unique identifier, as sent to Atomic during AccessToken creation.
PUT
/user/:identifier/end-monitoring