PayLink Webhook Reference
Webhooks enable your application to receive real-time updates via HTTP/S, allowing you to send timely notifications to end users and automate actions when events such as task status changes occur.
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.
eventType
string- 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. eventTime
string- The date and time of the event creation in ISO 8601 format at UTC+0.
user
object- Object containing
_id
andidentifier
whereidentifier
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. data
object- The payload of the event. This object will change depending on the
eventType
. Corresponding attributes are detailed for each webhook below.
{
"eventType": "sample-event-type",
"eventTime": "2024-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 verification of income or direct deposit switch 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.
Task event object
In addition to the standard event properties, all Task events will also include the following properties, unless noted otherwise:
publicToken
string- Public Access Token used when initializing the Transact SDK.
product
enum- The product relevant to the executed Task. Options are:
present
switch
task
string- The ID of the Task; used for pulling data from the API and debugging purposes.
taskWorkflow
string- The ID of the Task Workflow. A Task Workflow is a logical container in our backend for orchestrating series of Tasks.
authenticationMethod
enum- The method the user used to authenticate into the payroll system. Options for PayLink Tasks are currently limited to:
true-auth
smart-auth
user.connected
boolean- Indicates whether or not the user was present to view a confirmation of the Task's final outcome.
company
object- The service provider or merchant system which this Task operated against. Returned as an object containing
_id
,name
, andbranding
where this data is available. metadata
objectOptional- The
metadata
object; available if provided by your system when the Task was initialized. data
object- Payload object containing
previousStatus
,status
, andauthenticated
, 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.
{
"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:
status
enum- The current state of the Task. Options are
processing
,failed
andcompleted
. Failed and completed are final states indicating either a successful or unsuccessful Task. previousStatus
enum- The state which the Task was in before the current status. Options are
queued
andprocessing
. paymentMethod
ObjectOptional- Object containing details relating to they type of payment method when updating the card or account on file in the Task for
switch
Tasks.Child Properties
Required Properties
type
enum- The type of the payment method passed to the service provider. Options are
card
for credit cards orbank
for ACH accounts. _id
string- Identifier for the specific payment method selected.
title
string- Title of the credit card or ACH account
Optional Properties
expiry
datetimeOptional. Expiration date of the credit card.brand
stringOptional. Brand of the credit card.lastFour
stringOptional. Last four digits of the credit card.accountNumber
stringOptional. Last four digits of the ACH account number.routingNumber
stringOptional. Routing number of the ACH account.accountType
enumOptional. One ofchecking
orsavings
.cardStatus
enumOptional. Options are currently limited to:frozen
. reason
enum- Optional. For Tasks that failed, this is the reason why the Task failed. These are enumerated in the Task Failures section.
{
"eventType": "task-status-updated",
"eventTime": "2024-12-02T18:14:04.849Z",
"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:
authenticated
boolean- Indicates whether or not the Task has successfully authenticated into the target system.
{
"eventType": "task-authentication-status-updated",
"eventTime": "2024-12-02T18:14:04.853Z",
"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:
status
enum- The current state of the Task. Options are
processing
,failed
andcompleted
. Failed and completed are final states indicating either a successful or unsuccessful Task. previousStatus
enum- The state which the Task was in before the current status. Options are
queued
andprocessing
. paymentMethod
ObjectOptional- Object containing details relating to they type of payment method when updating the card or account on file in the Task for
switch
Tasks.Child Properties
Required Properties
type
enum- For PayLink Tasks, the type of the payment method passed to the service provider. Options are
card
for credit cards orbank
for ACH accounts. _id
string- Identifier for the specific payment method selected.
title
string- Title of the credit card or ACH account
Optional Properties
expiry
datetimeOptional. Expiration date of the credit card.brand
stringOptional. Brand of the credit card.lastFour
stringOptional. Last four digits of the credit card.accountNumber
stringOptional. Last four digits of the ACH account number.routingNumber
stringOptional. Routing number of the ACH account.accountType
enumOptional. One ofchecking
orsavings
.cardStatus
enumOptional. Options are currently limited to:frozen
.
{
"eventType": "task-status-patched",
"eventTime": "2024-12-02T18:14:04.867Z",
"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.
{
"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:
device-disconnected
- The device used to start the task is no longer connected.
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.
{
"eventType": "task-status-updated",
"eventTime": "2024-12-02T18:14:04.887Z",
"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",
"lastFour": "1110"
}
}
}