Atomic logo
Webhooks

PayLink Webhook Reference

paylink Webhooks are a useful way to receive real-time updates via HTTP and send timely notifications to your user as a transaction progresses. On this page you'll find details about the contents of our webhook event requests. For in-depth guides on how to set up, test, and secure webhooks, check out the Webhooks Guides.

All Atomic webhook events conform to the CloudEvents.io protocol using the binary content mode. This table shows the CloudEvents headers along with sample values to illustrate what is sent with each event.

HeaderValue
ce-specversion1.0
ce-sourcecom.atomicfi
ce-typecom.atomicfi.[event-type]
ce-time2022-04-13T21:36:42.985Z
ce-id257426ab237ac6786a23d52

Webhook events will include a set of standard properties in the request body, as described below. All keys in the event object are required in all webhooks.

eventTypestring
This indicates what type of event is being sent. The eventType attribute is the primary field for routing webhooks as they are received by your webhook endpoint. All available options are detailed on this page.
eventTimestring
The date and time of the event creation in ISO 8601 format at UTC+0.
userobject
Object containing _id and identifier where identifier is the identifier for this user in your system (used when creating the AccessToken) and the _id is an Atomic assigned id for the user.
dataobject
The payload of the event. This object will change depending on the eventType. Corresponding attributes are detailed for each webhook below.
Sample Request Body
{
  "eventType": "sample-event-type",
  "eventTime": "2020-01-28T22:04:18.778Z",
  "user": {
    "_id": "5c17c632e1d8ca3b08b2586f",
    "identifier": "YOUR_UNIQUE_IDENTIFIER"
  },
  "data": {
    "hello": "world"
  }
}

Any discrete operation passed through the Atomic system, such as a verification of income, direct deposit switch, or modification of a payment method will instantiate what is referred to as a Task in our system.

When a Task resolves, you will receive the task-status-updated webhook. If the Task was successful, the status attribute will be set to completed. If there was an issue with the Task processing, status will be failed along with a reason attribute containing the reason for the failure. The failure reasons are enumerated below.

If you will be using our API to retrieve data such as W-2's or employment status, please refer to the payroll data fetched webhook for real time notification of when that data is available to be pulled via the API.

In addition to the standard event properties, all Task events will also include the following properties, unless noted otherwise:

publicTokenstring
Public Access Token used when initializing the Transact SDK.
productenum
The product relevant to the executed Task. Options are:
    switch
taskstring
The ID of the Task; used for pulling data from the API and debugging purposes.
taskWorkflowstring
The ID of the Task Workflow. A Task Workflow is a logical container in our backend for orchestrating series of Tasks.
authenticationMethodenum
The method the user used to authenticate into the payroll system. Options for PayLink Tasks are currently limited to:
    true-auth
user.connectedboolean
Indicates whether or not the user was present to view a confirmation of the task's final outcome.
companyobjectOptional
The service provider which this Task operated against. Returned as an object containing _id, name, and branding where this data is available.
metadataobjectOptional
The metadata object; availaible if provided by your system when the Task was initialized.
dataobject
Payload object containing previousStatus, status, and authenticated, along with values which are dependent on the outcome of the Task. These are documented in full detail below in the Task status updated section.
Sample
{
  "eventType": "task-status-updated",
  "eventTime": "2020-01-28T22:04:18.778Z",
  "publicToken": "PUBLIC_TOKEN",
  "product": "switch",
  "user": {
    "_id": "5d8d3fecbf637ef3b11a877a",
    "identifier": "YOUR_INTERNAL_IDENTIFIER",
    "connected": true
  },
  "company": {
    "_id": "5d9a3fecbf637ef3b11ab442",
    "name": "Netflix",
    "branding": {
      "logo": {
        "url": "https://atomicfi-public-production.s3.amazonaws.com/979115f4-34a0-44f5-901e-753a33337444_atomic-logo-dark.png"
      }
    }
  },
  "metadata": {
    "orderId": "123"
  },
  "task": "5e30afde097146a8fc3d5cec",
  "taskWorkflow": "5e30afde097146a8fc3d5ceb",
  "data": {
    "previousStatus": "processing",
    "status": "completed",
    "authenticated": true,
    "paymentMethod": {
      "type": "card",
      "_id": "65c2a9f4a47295ba7a9831ae",
      "title": "Sample Credit Card",
      "expiry": "2029-03-31T23:59:59.999Z",
      "brand": "mastercard",
      "lastFour": "1110"
    }
  }
}

When a task-status-updated event is emitted, this indicates that the state of the Task has changed. For example, the Task has gone from processing to failed or completed. If the status is a final status, either failed or completed, no further updates will occur, although in very rare circumstances a task status patched event may be emitted.

If you need to grab payroll data once a Task has finished processing, you will need to listen for the payroll-data-fetched webhook . This webhook will notify you once the data is available to be retrieved through the Atomic API. The task-status-updated webhook may be sent out before the data has finished sync'ing to the Atomic system.

All task-status-updated webhooks will contain the properties listed in both the Event Object and Task Event Object sections. As well as the following properties, where applicable:

statusenum
The current state of the Task. Options are processing, failed and completed. Failed and completed are final states indicating either a successful or unsuccessful Task.
previousStatusenum
The state which the Task was in before the current status. Options are queued and processing.
paymentMethodObject
Object containing details relating to they type of payment method when updating the card or account on file in the Task.
Child Properties
typeenum
For PayLink Tasks, the type of the payment method passed to the service provider. Options are card for credit cards or bank for ACH accounts.
_idstring
Identifier for the specific payment method selected.
titlestring
Title of the credit card or ACH account
expirydatetime
Optional. Expiration date of the credit card.
brandstring
Optional. Brand of the credit card.
lastFourstring
Optional. Last four digits of the credit card.
accountNumberstring
Optional. Last four digits of the ACH account number.
routingNumberstring
Optional. Routing number of the ACH account.
accountTypeenum
Optional. One of checking or savings.
reasonenum
Optional. For Tasks that failed, this is the reason why the Task failed. These are enumerated in the Task Failures section.
Sample task-status-updated event
{
  "eventType": "task-status-updated",
  "eventTime": "2024-05-16T19:59:54.056Z",
  "user": {
    "_id": "602c4d53dc89c40008db562a",
    "identifier": "YOUR_UNIQUE_IDENTIFIER",
    "connected": true
  },
  "publicToken": "09601c31-1b54-4855-12ec-81810de154bd",
  "authenticationMethod": "true-auth",
  "company": {
    "_id": "5d77f9e1070856f3828945c5",
    "name": "Mocky",
    "branding": {
      "logo": {
        "url": "https://cdn.atomicfi.com/mocky-logo.svg"
      }
    }
  },
  "task": "602414d84f9a1980cf5eafcc",
  "taskWorkflow": "5e30afde097146a8fc3d5ceb",
  "product": "switch",
  "data": {
    "authenticated": true,
    "previousStatus": "processing",
    "status": "completed",
    "paymentMethod": {
      "type": "card",
      "_id": "65c2a9f4a47295ba7a9831ae",
      "title": "Sample Credit Card",
      "expiry": "2029-03-31T23:59:59.999Z",
      "brand": "mastercard",
      "lastFour": "1110"
    }
  }
}

When eventType is task-authentication-status-updated, the authentication status of a Task was changed. Possible authenticated statuses include:

authenticatedboolean
Indicates whether or not the Task has successfully authenticated into the target system.
Sample task-authentication-status-updated event
{
  "eventType": "task-authentication-status-updated",
  "eventTime": "2024-05-16T19:59:54.062Z",
  "user": {
    "_id": "602c4d53dc89c40008db562a",
    "identifier": "YOUR_UNIQUE_IDENTIFIER",
    "connected": true
  },
  "publicToken": "09601c31-1b54-4855-12ec-81810de154bd",
  "authenticationMethod": "true-auth",
  "company": {
    "_id": "5d77f9e1070856f3828945c5",
    "name": "Mocky",
    "branding": {
      "logo": {
        "url": "https://cdn.atomicfi.com/mocky-logo.svg"
      }
    }
  },
  "task": "602414d84f9a1980cf5eafcc",
  "taskWorkflow": "5e30afde097146a8fc3d5ceb",
  "product": "switch",
  "data": {
    "authenticated": true
  }
}

When eventType is task-status-patched, the final status of a Task was updated. Cases where this may occur are rare and are generally associated with an audit or bug fix within our system. Possible statuses include:

statusenum
The current state of the Task. Options are processing, failed and completed. Failed and completed are final states indicating either a successful or unsuccessful Task.
previousStatusenum
The state which the Task was in before the current status. Options are queued and processing.
paymentMethodObject
Object containing details relating to they type of payment method when updating the card or account on file in the Task.
Child Properties
typeenum
For PayLink Tasks, the type of the payment method passed to the service provider. Options are card for credit cards or bank for ACH accounts.
_idstring
Identifier for the specific payment method selected.
titlestring
Title of the credit card or ACH account
expirydatetime
Optional. Expiration date of the credit card.
brandstring
Optional. Brand of the credit card.
lastFourAccountNumberstring
Optional. Last four digits of the credit card.
accountNumberstring
Optional. Last four digits of the ACH account number.
routingNumberstring
Optional. Routing number of the ACH account.
accountTypeenum
Optional. One of checking or savings.
Sample task-status-patched event
{
  "eventType": "task-status-patched",
  "eventTime": "2024-05-16T19:59:54.068Z",
  "user": {
    "_id": "602c4d53dc89c40008db562a",
    "identifier": "YOUR_UNIQUE_IDENTIFIER",
    "connected": true
  },
  "publicToken": "09601c31-1b54-4855-12ec-81810de154bd",
  "authenticationMethod": "true-auth",
  "company": {
    "_id": "5d77f9e1070856f3828945c5",
    "name": "Mocky",
    "branding": {
      "logo": {
        "url": "https://cdn.atomicfi.com/mocky-logo.svg"
      }
    }
  },
  "task": "602414d84f9a1980cf5eafcc",
  "taskWorkflow": "5e30afde097146a8fc3d5ceb",
  "product": "switch",
  "data": {
    "authenticated": true,
    "previousStatus": "failed",
    "status": "completed",
    "paymentMethod": {
      "type": "card",
      "_id": "65c2a9f4a47295ba7a9831ae",
      "title": "Sample Credit Card",
      "expiry": "2029-03-31T23:59:59.999Z",
      "brand": "mastercard",
      "lastFour": "1110"
    }
  }
}

Employment data is contained within an data.outputs object. The data delivered to you will depend on the Task's product and other considerations listed below. For your convenience, this data may include both raw and derived fields.

If you are using verify, you'll receive data as described in our Employment Data Reference. The data retrieved will depend on your data scoping configuration and what we are able to access within the payroll system.

Sample response for verify
{
  "eventType": "task-status-updated",
  "eventTime": "2021-05-24T18:27:09.610Z",
  "user": {
    "_id": "602c4d53dc89c40008db562a",
    "identifier": "YOUR_UNIQUE_IDENTIFIER"
  },
  "publicToken": "09601c31-1b54-4855-12ec-81810de154bd",
  "company": {
    "_id": "5d77f9e1070856f3828945c5",
    "name": "Mocky",
    "branding": {
      "logo": {
        "_id": "5eb62781b4b83f0008f639cc",
        "url": "https://cdn.atomicfi.com/mocky-logo.svg"
      }
    }
  },
  "task": "602414d84f9a1980cf5eafcc",
  "taskWorkflow": "5e30afde097146a8fc3d5ceb",
  "product": "verify",
  "data": {
    "previousStatus": "processing",
    "status": "completed",
    "authenticated": true,
    "outputs": {
      "income": 45000,
      "incomeType": "yearly",
      "annualIncome": 45000,
      "hourlyIncome": 21.63,
      "netHourlyRate": 18.44,
      "employeeType": "fulltime",
      "employmentStatus": "active",
      "jobTitle": "Product Manager",
      "startDate": "2017-04-19T12:00:00.000Z",
      "minimumMonthsOfEmployment": 58,
      "weeklyHours": 40,
      "payCycle": "semimonthly",
      "nextExpectedPayDate": "2020-06-30T12:00:00.000Z",
      "currentPayPeriodStart": "2020-06-13T12:00:00.000Z",
      "currentPayPeriodEnd": "2020-06-27T12:00:00.000Z",
      "unpaidHoursInPayPeriod": 24,
      "firstName": "Jane",
      "lastName": "Appleseed",
      "dateOfBirth": "1984-04-12T19:00:00.000Z",
      "email": "jappleseed@example.org",
      "phone": "8015551111",
      "ssn": "111223333",
      "address": "123 Street St.",
      "city": "Provo",
      "state": "UT",
      "postalCode": "84606",
      "statements": [
        {
          "date": "2020-06-15T12:00:00.000Z",
          "payPeriodStartDate": "2020-05-27T12:00:00.000Z",
          "payPeriodEndDate": "2020-06-12T12:00:00.000Z",
          "grossAmount": 1875,
          "ytdGrossAmount": 10000,
          "netAmount": 1620,
          "ytdNetAmount": 8000,
          "hours": 96,
          "deductions": [
            {
              "category": "taxes",
              "label": "Federal Income Tax",
              "rawLabel": "Federal Income Tax",
              "amount": 200,
              "ytdAmount": 2000
            },
            {
              "category": "taxes",
              "label": "State Income Tax",
              "rawLabel": "Utah State Tax",
              "amount": 50,
              "ytdAmount": 500
            },
            {
              "category": "other",
              "label": "Abc corp dd",
              "rawLabel": "Abc corp dd",
              "amount": 5,
              "ytdAmount": 50
            }
          ],
          "earnings": [
            {
              "category": "benefit",
              "rawLabel": "Social Security (Disability)",
              "amount": 1000
            },
            {
              "category": "bonus",
              "rawLabel": "Quarterly Bonus",
              "amount": 2000,
              "ytdAmount": 6000
            },
            {
              "category": "overtime",
              "rawLabel": "Overtime Pay",
              "amount": 100,
              "ytdAmount": 1000,
              "hours": 10,
              "rate": 15
            },
            {
              "category": "reimbursement",
              "rawLabel": "Gas Card",
              "amount": 25.47,
              "ytdAmount": 85.74
            }
          ],
          "paystub": {
            "_id": "60abeff50836730008616fad",
            "url": "[ATOMIC-GENERATED-PRESIGNED-S3-URL]"
          }
        },
        {
          "date": "2020-05-31T12:00:00.000Z",
          "payPeriodStartDate": "2020-05-11T12:00:00.000Z",
          "payPeriodEndDate": "2020-05-26T12:00:00.000Z",
          "grossAmount": 1875,
          "hours": 88,
          "deductions": [
            {
              "category": "taxes",
              "label": "Federal Income Tax",
              "rawLabel": "Federal Income Tax",
              "amount": 200
            },
            {
              "category": "taxes",
              "label": "State Income Tax",
              "rawLabel": "Utah State Tax",
              "amount": 50
            },
            {
              "category": "other",
              "label": "Abc corp dd",
              "rawLabel": "Abc corp dd",
              "amount": 5
            }
          ],
          "paystub": {
            "_id": "60abeff50836730008616fae",
            "url": "[ATOMIC-GENERATED-PRESIGNED-S3-URL]"
          }
        }
      ],
      "accounts": [
        {
          "routingNumber": "123123123",
          "accountNumber": "1122330000",
          "type": "checking",
          "bankName": "Molecular Bank",
          "distributionType": "percent",
          "distributionAmount": 80
        },
        {
          "routingNumber": "456456456",
          "accountNumber": "XXXX1111",
          "type": "savings",
          "bankName": "Molecular Bank",
          "distributionType": "percent",
          "distributionAmount": 20
        }
      ],
      "w2s": [
        {
          "year": "2020-01-01T00:00:00.000Z",
          "totalWages": 50000,
          "form": {
            "_id": "60abeff60836730008616faf",
            "url": "[ATOMIC-GENERATED-PRESIGNED-S3-URL]"
          },
          "parsedData": {
            "taxYear": 2022,
            "employeeTin": "XXX-XX-1234",
            "employerTin": "12-3456789",
            "employerNameAddress": {
              "name1": "Tax Form Issuer, Inc",
              "line1": "12021 Sunset Valley Dr",
              "line2": "Suite 230",
              "city": "Preston",
              "state": "VA",
              "postalCode": "20191"
            },
            "controlNumber": "012547 WY/OA7",
            "employeeName": {
              "first": "Kris",
              "last": "Public"
            },
            "employeeAddress": {
              "line1": "1 Main St",
              "line2": "Apartment 123",
              "city": "Melrose",
              "state": "NY",
              "postalCode": "12121"
            },
            "wages": 44416.74,
            "federalTaxWithheld": 6907.16,
            "socialSecurityWages": 47162.92,
            "socialSecurityTaxWithheld": 2924.1,
            "medicareWages": 47162.92,
            "medicareTaxWithheld": 683.86,
            "socialSecurityTips": 134.25,
            "allocatedTips": 149.75,
            "dependentCareBenefit": 543.25,
            "nonQualifiedPlan": 354.23,
            "codes": [
              {
                "code": "C",
                "amount": 301.5
              },
              {
                "code": "D",
                "amount": 2746.18
              },
              {
                "code": "DD",
                "amount": 4781.88
              }
            ],
            "statutory": false,
            "retirementPlan": true,
            "thirdPartySickPay": false,
            "other": [
              {
                "description": "Housing",
                "amount": 6500
              },
              {
                "code": "Union Dues",
                "amount": 1500
              }
            ],
            "stateTaxWithholding": [
              {
                "stateTaxWithheld": 1726.78,
                "state": "OH",
                "stateTaxId": "OH 036-133505158F-01",
                "stateIncome": 44416.74
              }
            ],
            "localTaxWithholding": [
              {
                "localTaxWithheld": 427.62,
                "localityName": "Kirtland",
                "state": "OH",
                "localIncome": 44416.74
              }
            ]
          }
        }
      ],
      "timesheets": [
        {
          "type": "unpaid",
          "duration": 420,
          "date": "2020-05-31T12:00:00.000Z"
        }
      ]
    }
  }
}

Tasks may fail for many different reasons. If a Task fails, we will include a reason property with the event's data object. Possible values include:

subscription-inactive
The subscription selected is currently inactive.
subscription-managed-by-partner-provider
The subscription selected is managed by a partner provider. The payment method will need to be updated via the partner provider's portal.
payment-method-locked
The payment method selected is currently locked in the service provider's system. The user will need to try again after the lockout has ended.
payment-method-not-supported
The payment method selected is not available to be used in for the select service provider. Another payment method will need to be used.
payment-switch-unsuccessful
The payment switch was unsuccessful. We are uncertain as to the nature of the failure reason, but are unable to switch this user's payment method with this service provider at this time.
Example Task Failure Event
{
  "eventType": "task-status-updated",
  "eventTime": "2024-05-16T19:59:54.098Z",
  "user": {
    "_id": "602c4d53dc89c40008db562a",
    "identifier": "YOUR_UNIQUE_IDENTIFIER",
    "connected": true
  },
  "publicToken": "09601c31-1b54-4855-12ec-81810de154bd",
  "authenticationMethod": "true-auth",
  "company": {
    "_id": "5d77f9e1070856f3828945c5",
    "name": "Mocky",
    "branding": {
      "logo": {
        "url": "https://cdn.atomicfi.com/mocky-logo.svg"
      }
    }
  },
  "task": "602414d84f9a1980cf5eafcc",
  "taskWorkflow": "5e30afde097146a8fc3d5ceb",
  "product": "switch",
  "data": {
    "authenticated": true,
    "previousStatus": "processing",
    "status": "failed",
    "reason": "subscription-inactive",
    "paymentMethod": {
      "type": "card",
      "_id": "65c2a9f4a47295ba7a9831ae",
      "title": "Sample Credit Card",
      "expiry": "2029-03-31T23:59:59.999Z",
      "brand": "mastercard",
      "lastFourAccountNumber": "1110"
    }
  }
}