API

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:

HeaderDescription
x-api-keyAPI Key for your Atomic account
x-api-secretAPI Secret for your Atomic account

Access Token

A publicToken will be included in the headers of requests which are made via the end user from client-side code, e.g. searching for their employer or initializing a Task. The publicToken defaults to a 24 hour expiry, but can be set to a minimum of 30 minutes or a maximum of 30 days by passing in the desired duration using the optional tokenLifetime property in the call to /access-token. The minimum is to allow for users to complete variations of the flows, such as MFA, which can take time.

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

CodeTitleDescription
200OKThe request was successful.
400Bad RequestThe request was unacceptable.
401UnauthorizedMissing or invalid credentials.
404Not FoundThe resource does not exist.
422Validation ErrorA validation error occurred.
429Too Many RequestsToo may requests, please try again later.
50XInternal Server ErrorAn error occurred with our API.

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.

For PayLink Manage use cases, only an identifier for the user is required when creating an AccessToken to initialize the Transact SDK.

Create Access Token

This API is how a flow through the Atomic experience is initialized. You will first create an AccessToken which is used to instantiate the Transact SDK. There are variations on how this AccessToken is created and will vary depending on the operation to be called.

For PayLink Manage use cases, you only need to pass an identifier for the user.

For PayLink Switch use cases, you will need to pass all of the data fields listed below.

When passing card data, make sure to send this request to our PCI-compliant environment. You may use 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

identifierstring
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.
Child Properties
Required Properties
numberstring
Card number, should be between 15 and 19 digits in length.
expirystring
Expiry for the card. MM/YY format expected.
cvvstring
CVV number associated with the card.
titlestring
Title for the card.
Optional Properties
brandstring
Brand of card. Possible values include mastercard, visa, american-express, or discover.
subtitlestring
Subtitle for the card.
cardStatusstring
Status of the card. Possible values are currently limited to: frozen.
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.
Child Properties
Required Properties
accountNumberstring
Account number used to identify the account
routingNumberstring
The ABA routing number.
typeenum
Type of account. Possible values include checking, savings, or paycard.
titlestring
Title or nickname for the account.
identityobject
Details about the end user's identity. These details are regularly required to make an update to a vendor system.
Child Properties
Required Properties
firstNamestring
End user's first name
lastNamestring
End user's last name
postalCodestring
End user's postal code from their address
addressstring
End user's street address
citystring
End user's home city
statestring
End user's home state. 2 digit state code is expected
Optional Properties
address2string
Optional second line for the end user's street address
phonestring
End user's 9 digit phone number without () or -
emailstring
End user's email address

Optional Properties

tokenLifetimeinteger
The number of seconds until the token expires. The minimum allowed is 1,800 (30 min). The max allowed is 2,592,000 (30 days). Shorter token lifetimes are recommended for security purposes.

Default value: 86,400 (24 hours).

PayLink Manage

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

PayLink Switch

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

BaaS 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
lastFourstring
The last four digits of a card number.
titlestring
Title for the card
paymentServiceobject
Object containing details required for Atomic to connect to and utilitize a BaaS card provider
Child Properties
Required Properties
galileoobject
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
apiLoginstring
Web service username, as provided by Galileo.
apiTransKeystring
Web service password, as provided by Galileo.
providerIdstring
Galileo-issued provider identifier.
transactionIdstring
A unique provider-generated ID to identify this API call. A UUID is preferred.
accountNostring
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.
apiUrlstring
The production url that your organization uses to connect to Galileo.
Optional Properties
brandstring
Brand of card. Possible values include visa, mastercard, american-express, or discover. Transact will use this field to display an icon specific to the card brand.
expirystring
Expiry for the card. MM/YY format expected
subtitlestring
Subtitle for the card

Optional Properties

tokenLifetimeinteger
The number of seconds until the token expires. The minimum allowed is 1,800 (30 min). The max allowed is 2,592,000 (30 days). Shorter token lifetimes are recommended for security purposes.

Default value: 86,400 (24 hours).

PayLink Switch - BaaS passthrough

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

Response

Successfully creating an Access Token will return a payload with a data object containing a publicToken. The publicToken may be used to initialize the Transact SDK and is valid for tokenLifetime seconds.

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

PayLink Accounts

A PayLinkAccount refers to the connection established to a 3rd party system which has been authenticated by an end-user. Once established, this connection can be used to perform read and write operations on the connected system as directed by the user. For example, once Netflix has been linked, Atomic can then pull data about the user's Netflix account or drive an action like pausing the account or managing their plan.

Get PayLink Accounts

This endpoint returns all PayLink Accounts associated with a specific end 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

identifierstring
The identifier of the end user. Passed with the URL as a path parameter where :identifier is the identifier of end user
GET/:identifier/pay-link/accounts
https://sandbox-api.atomicfi.com/:identifier/pay-link/accounts

Response

The response contains an array of Account objects containing and relevant metadata relating to the PayLink Accounts connected by the end user.

accounts[Account]
An array of Account objects.
Child Properties
Optional Properties
_idstring
Unique identifier for the PayLink Account connected by the end user.
companyCompany
An object containing details of the company to which the PayLink Account is connected.
Child Properties
Optional Properties
_idstring
Unique identifier for the company.
namestring
The name of the company.
brandingobject
The branding information of the company. Useful if you are surfacing logos in your experience.
Child Properties
Optional Properties
logoobject
A PNG of the logo of the company.
Child Properties
Optional Properties
urlstring
The URL of the logo, served from our CDN.
backgroundColorstring
The background color of the logo.
colorstring
The color of the company. Atomic uses this color to style the experience - buttons and other UI elements.
accountAccount
An object containing specific details of the account connected by the end user.
Child Properties
Optional Properties
typeenum
An enum of the type of account. Options include:
    subscriptionloanpolicytelecom
sourceIdstring
An ID of the account pulled from the connected system.
suggestions[Suggestions]
An array of suggestion objects containing information about suggestions Atomic recommends presenting to the user based on the state of their account in the connected system
Child Properties
Optional Properties
monthlySavingsnumber
The projected monthly savings if the user were to take the recommended action.
categoryenum
An enum of the types of categories of suggetions
    change-plancancel-plandowngrade-planremove-servicecommon-cancellationredundant-servicescostly-featurealternative-serviceunderutilizationhigh-interest-rate
actionUrlstring
A URL used to launch the suggested action.
shortDescriptionstring
A short description of the suggestion.
detailedDescriptionstring
A longer, more detailed description of the suggestion.
buttonTitlestring
A short string intended to be used as the CTA in a button for this suggestion.
identities[Identity]
The identities connected to the account.
Child Properties
Optional Properties
firstNamestring
The first name of the identity.
emailstring
The email associated with the identity.
phonestring
The phone number associated with the identity.
billingobject
An object containing the billing details of the account.
Child Properties
Optional Properties
amountnumber
The amount of the bill.
dueDatestring
The upcoming due date for the bill.
autopayobject
The autopay details of the bill, if enabled.
Child Properties
Optional Properties
statusenum
The status of the autopay. Options are:
    enableddisabledpaused
cycleenum
The type of cycle the bill is paid on. Options are:
    biweeklymonthlysemimonthlyweekly
history[BillingHistory]
An array of objects containing the transaction history of the bill.
Child Properties
Optional Properties
datestring
The date of the associated transaction.
amountnumber
The amount of the associated transaction.
paymentMethods[PaymentMethod]
An array of objects containing the payment methods associated with the account.
Child Properties
Optional Properties
typestring
The type of the payment method.
lastFourstring
The last four digits of the payment method.
brandstring
The brand of the payment method.
isPrimaryboolean
Whether the payment method is the primary payment method.
dataobject
An object containing data of the account which is relevant to the type of account. Each of the enums list above in the type property will have a corresponding object as described in the Bill Data reference.
Child Properties
Optional Properties
plans[Plan]
The plans associated with the account.
Child Properties
Optional Properties
sourceIdstring
The source ID of the plan.
statusstring
The status of the plan.
titlestring
The title of the plan.
descriptionstring
The description of the plan.
freeTrialboolean
Whether the plan is on a free trial.
usage[Usage]
The usage of the account.
Child Properties
Optional Properties
titlestring
The title of the usage.
descriptionstring
The description of the usage.
actions[Actions]
The actions that can be performed on the account.
Child Properties
Optional Properties
idstring
The ID of the action.
typeenum
An enum representing the possible actions that can be performed on a PayLink Account. This comprehensive list includes all actions available for a company. However, each user will only see a subset of these actions, tailored to their specific account and plan.
    change-plancancel-planpause-plan
Example response 
{
  "accounts": [
    {
      "_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"
        }
      },
      "account": {
        "type": "subscription",
        "sourceId": "70236f02-dc3e-3419-bbf7-06d3da9d6685",
        "suggestions": [
          {
            "monthlySavings": 10,
            "category": "remove-service",
            "actionUrl": "Specific URL for the action within the related service",
            "shortDescription": "Remove Disney Bundle",
            "detailedDescription": "You are currently paying $10 per month for the Disney Bundle. If you are not using this service, consider removing it to save $10 monthly.",
            "buttonTitle": "Remove Now"
          },
          {
            "monthlySavings": 5,
            "category": "underutilization",
            "actionUrl": "Specific URL for the action within the related service",
            "shortDescription": "Switch to 5G Start Plan",
            "detailedDescription": "Your line is on the 5G Start plan with a $3 rate adjustment. Consider switwmching to a plan without the adjustment or a lower-tier plan if the current plan features are underutilized.",
            "buttonTitle": "Switch Plan"
          }
        ],
        "identities": [
          {
            "firstName": "test",
            "email": "test@email.com",
            "phone": "5558675309"
          }
        ],
        "billing": {
          "amount": 20.46,
          "dueDate": "2024-11-20T23:59:59.000Z",
          "autopay": {
            "status": "enabled",
            "cycle": "monthly"
          },
          "history": [
            {
              "date": "2024-10-20T18:00:54.761Z",
              "amount": 20.7
            },
            {
              "date": "2024-09-20T09:48:31.093Z",
              "amount": 19.38
            }
          ],
          "paymentMethods": [
            {
              "type": "card",
              "lastFour": "2345",
              "brand": "Mastercard",
              "isPrimary": true
            }
          ]
        },
        "data": {
          "plans": [
            {
              "sourceId": "Hulu (No Ads)",
              "status": "active",
              "title": "Family Hulu Account",
              "description": "Hulu (No Ads)",
              "freeTrial": false
            }
          ],
          "usage": [
            {
              "title": "profile",
              "description": "Test Profile"
            }
          ]
        },
        "_id": "67376c5befe988922e8aabc4"
      },
      "actions": [
        {
          "type": "change-plan",
          "id": "BASE64_ENCODED_ID"
        },
        {
          "type": "cancel-plan",
          "id": "BASE64_ENCODED_ID"
        },
        {
          "type": "pause-plan",
          "id": "BASE64_ENCODED_ID"
        }
      ],
      "type": "linked"
    }
  ]
}

Task

Each discrete operation processed through the Atomic system, such as an update to a payment account on file or an action against a merchant system on behalf of a user, will instantiate what is referred to as a Task. A Task consists of an authentication step where Atomic logs into merchant system or service provider and an operation step either data is read or an update is written to the system in question.

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

taskIdstring
The id of the Task. The taskId property is sent in multiple webhooks or any of the interaction events which are fired after the authentication phase of the flow has begun.
GET/task/:taskId/details
https://sandbox-api.atomicfi.com/task/:taskId/details

Response

A successful request will return the details of the Task.

_idstring
The id of the Task.
authenticatedboolean
Indicates whether or not the Task has successfully authenticated against the merchant system.
companyobject
Metadata for the employer.
Child Properties
Required Properties
_idstring
Unique identifier for the company.
namestring
The name of the company
Optional Properties
brandingobject
Metadata for the company's branding.
Child Properties
Optional Properties
logoobject
Metadata for the company's logo.
Child Properties
Optional Properties
urlstring
URL for the company's logo.
connectorobject
Metadata for the connector.
Child Properties
Required Properties
_idstring
Unique identifier for the connector.
namestring
The name of the connector
Optional Properties
brandingobject
Metadata for the connector's branding.
Child Properties
Optional Properties
logoobject
Metadata for the connector's logo.
Child Properties
Optional Properties
urlstring
URL for the connector's logo.
createdAtdate
The timestamp when the task was created, stored in UTC and ISO 8601 format.
updatedAtdate
The timestamp when the task was last updated, stored in UTC and ISO 8601 format.
failReasonstringOptional
The failure reason associated with a failed task. Will consist of one of the failure values.
linkedAccountstringOptional
The id of the linked account used to create the task.
metadataobjectOptional
The metadata provided by your system when the task was initialized.
productstring
The product of the task. Possible values include present and switch.
statusstring
The status of the task which may be queued, processing, failed, or completed.
taskWorkflowobject
The Task Workflow of the Task. When multiple tasks are associated with a single workflow, they will all have the same taskWorkflow object. Every Task is associated with a Task Workflow, even if it not associated with another Task.
Child Properties
Required Properties
_idstring
The id of the Task Workflow.
userobject
The user who processed the Task.
Child Properties
Required Properties
_idstring
The id of the user in atomic's system.
identifierstring
The user's unique identifier, as sent to Atomic during AccessToken creation.
Example response 
{
  "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",
      "failReason": "unknown-failure",
      "linkedAccount": "645963a0b754649972f3d4ac",
      "metadata": {
        "data": "test"
      },
      "product": "switch",
      "status": "completed",
      "taskWorkflow": {
        "_id": "643f2ed34253e21bdbd2de31"
      },
      "user": {
        "_id": "607e249736b9f053b536bdea",
        "identifier": "IDENTIFIER_FROM_YOUR_SYSTEM"
      }
    }
  }
}

Get Task Status

Calling this API returns the status of a Task. Submit the corresponding taskId and receive the status of that Task.

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

taskIdstring
The id of the Task. The taskId property is sent in multiple webhooks or any of the interaction events which are fired after the authentication phase of the flow has begun.
GET/task/:taskId/status
https://sandbox-api.atomicfi.com/task/:taskId/status

Response

A successful request will return the createdAt date, status, and if a Task failed (Tasks with a status of "failed") a failReason.

createdAtdate
The timestamp when the Task was created, stored in UTC and ISO 8601 format.
statusstring
The status of the task which may be queued, processing, failed, or completed.
failReasonstringOptional
The failure reason associated with a failed task. Will consist of one of the failure values.
Example response 
{
  "createdAt": "2023-01-03T16:40:48.009Z",
  "status": "failed",
  "failReason": "payment-method-not-supported"
}

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/user
https://sandbox-pci.atomicfi.com/user

Get 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

identifierstring
The user's unique identifier, as sent to Atomic during AccessToken creation.

Optional Properties

statusstring
The status of the task, provided as a query string parameter, which may be queued, processing, failed, or completed.
payrollDataAvailablestring
A boolean value, provided as a query string parameter, indicating whether or not the user's payroll data is ready for retrieval via API.
GET/user/:identifier/tasks
https://sandbox-api.atomicfi.com/user/:identifier/tasks

Response

A successful response will return an object with data.tasks equal to an array of task objects with the following properties.

_idstring
The id of the task.
authenticatedboolean
A boolean value indication whether or not the task has successfully authenticated against the payroll system.
createdAtdate
The timestamp when the task was created, stored in UTC and ISO 8601 format.
failReasonstringOptional
The failure reason associated with a failed task. Will consist of one of the failure values.
payrollDataAvailableboolean
A boolean value indicating whether or not the user's payroll data is ready for retrieval via api.
productenum
The product relevant to the executed task. Options are:
    depositverify
statusstring
The status of the task which may be queued, processing, failed, or completed.
Example response 
{
  "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

identifierstring
The user's unique identifier, as sent to Atomic during AccessToken creation.
PUT/user/:identifier/end-monitoring
https://sandbox-api.atomicfi.com/user/:identifier/end-monitoring

Response

A successful response will return a json object with success equal to true.

Example response 
{
  "success": true
}