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.

Cloud Events

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.

Header	Value
`ce-specversion`	`1.0`
`ce-source`	`com.atomicfi`
`ce-type`	`com.atomicfi.[event-type]`
`ce-time`	`2022-04-13T21:36:42.985Z`
`ce-id`	`257426ab237ac6786a23d52`

Event object

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"
  }
}

Tasks

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.

Task event object

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"
    }
  }
}

Task status updated

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

Required 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

Optional Properties

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-04-17T15:25:01.946Z",
  "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"
    }
  }
}

Task authentication status updated

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-04-17T15:25:01.952Z",
  "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
  }
}

Task status patched

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

Required 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

Optional Properties

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-04-17T15:25:01.957Z",
  "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"
    }
  }
}

Task outputs

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.

Verify

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"
        }
      ]
    }
  }
}

Task failures

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-04-17T15:25:01.984Z",
  "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"
    }
  }
}