Preview Payroll
There are several key use cases for which we would want a breakdown of a payroll before it is processed. From simply showing employers how much taxes they'll pay, to facilitating earned wage access, previewing payroll is a key process.
In this guide
- How to preview upcoming payroll.
- How to preview hypothetical payroll.
Preview Pending Payroll
With either the Preview Payroll by Check IDs or Preview Payroll by Check Date, Zeal allows us to get a breakdown of upcoming payroll. For this example, we'll look at viewing upcoming payroll by check date:
Start a preview payroll job
Call Preview Payroll by Check Date with the companyID and desired check_date. This will return a job_id.
curl --request POST \
--url https://api.zeal.com/preview/checkDate \
--header 'Authorization: Bearer {{testApiKey}}' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"companyID": "{{companyID}}",
"check_date": "2023-01-18"
}
'
Receive updates from the Job Queue Event
When the job is finished processing, Zeal will send you an update via the Job Queue Event webhook.
Get the results of the job
Include the job_id in a call to Get Preview.
curl --request GET \
--url 'https://api.zeal.com/preview?job_id={{jobID}}' \
--header 'Authorization: Bearer {{testApiKey}}' \
--header 'Accept: application/json'
This will return a JSON object with a payload field detailing the breakdown of the payroll.
{
"status": 200,
"success": true,
"data": {
"job_id": "12351f1-cc224-4654-81120-39cafeacd8551",
"status": "complete",
"code": 200,
"created_at": "2022-05-04T19:29:39.134Z",
"request_body": {
"companyID": "ae12ffj4141040ac8a3cc3132a3b22l62",
"checks": [
"oq16c5ffccd740e28czz39442f315",
"22reabd897e3345a2ttyfa22b1712be52",
"1337448bd4534cc34tfd783ef1ce8391"
],
"test_mode": false
},
"payload": {
"success": true,
"result": {
"checks": [
{
"gross_pay": 20230,
"net_pay": 46544,
"employer_taxes": 8240,
"employee_taxes": 3856,
"employee_deductions": 0,
"employer_deductions": 0,
"taxes": [
{
"name": "Federal Income Tax",
"codename": "FIT",
"amount": 0
},
{
"name": "Social Security",
"codename": "FICA_SocialSecurity_EE",
"amount": 3125
},
{
"name": "Social Security",
"codename": "FICA_SocialSecurity_ER",
"amount": 3125
},
{
"name": "Medicare",
"codename": "FICA_Medicare_EE",
"amount": 731
},
{
"name": "Medicare",
"codename": "FICA_Medicare_ER",
"amount": 731
},
{
"name": "Medicare Additional",
"codename": "FICA_MedicareAdditional_EE",
"amount": 0
},
{
"name": "Federal Unemployment Tax",
"codename": "FUTA",
"amount": 302
},
{
"name": "State Unemployment Tax",
"codename": "SUTA_GA",
"amount": 4082
}
]
}
"total_employer_taxes": 8240,
"total_employee_taxes": 3856,
"total_employee_deductions": 0,
"total_employer_deductions": 0
}
}
}
}
Preview Hypothetical Payroll
There are some scenarios where it's useful to preview the breakdown of an Employee Check without first submitting it to Zeal. For example, you may want to get a view of what the net pay would be for one specific shift in a reporting period. The Preview Check Data endpoint allows us to do just this.
Preview check data
Submit an Employee Check Object to Preview Check Data (similar to how data is submitted to the Create Employee Check endpoint).
curl --request POST \
--url https://api.zeal.com/preview/checkData \
--header 'Authorization: Bearer {{testApiKey}}' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"companyID": "{{companyID}}",
"employeeID": "{{employeeID}}",
"reportingPeriodID": "{{reportingPeriodID}}",
"check_date": "2022-01-14",
"shifts": [
{
"time": "2022-01-05T17:00:00Z",
"hourly: {
"hours": 8,
"wage": 25
}
}
],
}
'
This will return JSON with a payload field detailing the breakdown of the hypothetical payroll.
{
"success": true,
"data": {
"success": true,
"result": {
"checks": [
{
"gross_pay": "200.00",
"net_pay": "183.58",
"employer_taxes": "26.10",
"employee_taxes": "16.42",
"employee_deductions": "0.00",
"employer_deductions": "0.00",
"taxes": [
{
"name": "Federal Income Tax",
"codename": "FIT",
"amount": "0.00"
},
{
"name": "Social Security",
"codename": "FICA_SocialSecurity_EE",
"amount": "12.40"
},
{
"name": "Social Security",
"codename": "FICA_SocialSecurity_ER",
"amount": "12.40"
},
{
"name": "Medicare",
"codename": "FICA_Medicare_EE",
"amount": "2.90"
},
{
"name": "Medicare",
"codename": "FICA_Medicare_ER",
"amount": "2.90"
},
{
"name": "Medicare Additional",
"codename": "FICA_MedicareAdditional_EE",
"amount": "0.00"
},
{
"name": "Federal Unemployment Tax",
"codename": "FUTA",
"amount": "0.00"
},
{
"name": "State Unemployment Tax",
"codename": "SUTA_AK",
"amount": "10.80"
},
{
"name": "State Unemployment Tax",
"codename": "SUI_AK",
"amount": "1.12"
}
]
}
],
"total_employer_taxes": "26.10",
"total_employee_taxes": "16.42",
"total_employee_deductions": "0.00",
"total_employer_deductions": "0.00"
}
}
}
Recap
- There are two ways to preview payroll with Zeal:
- Preview upcoming payroll - data that is in Zeal's system awaiting processing.
- Preview hypothetical payroll - data that is not submitted to Zeal for processing.
- To preview upcoming payroll use the Preview Payroll by Check IDs or Preview Payroll by Check Date endpoints.
- Previewing upcoming payroll is an asynchronous process and returns a
job_id. - Use the Job Queue Event webhook to receive updates on a job's status.
- Use the Get Preview to get the results of a job.
- To preview hypothetical payroll use the Preview Check Data endpoint.
Updated over 1 year ago