Embedding payroll lets you build a smooth, tailored experience right into your platform. For example, an HR software-as-a-service (SaaS) company that handles onboarding, contracts, and employee records can add payroll as a service to better serve its users. This reduces churn, improves customer satisfaction, and increases average contract value (ACV).
Building a payroll system from scratch is possible, but it’s unnecessary, it’s painful, and it comes with challenges like compliance, security, and tax calculations. It also requires access to specialists in finance and employment law.
A better approach is to use an established embedded payroll platform like Gusto Embedded. It offers a robust API, SDK, and Flows (a customizable iframe-like interface) that let you integrate payroll into your app without building from scratch.
In this article, you’ll learn five key steps to embed payroll functionality successfully into your application. You’ll learn how to lay out your requirements and goals, design an experience, integrate it, test it, and finally, deploy it for real-world use.
Step 1: Plan Your Payroll Integration
Payroll is tightly regulated, highly sensitive, and deeply integrated into how businesses operate. Integrating payroll functionality into your SaaS platform requires careful planning, as mistakes can be costly.
Before writing any code, you need to define your critical requirements, understand the workflows, and determine how the embedded payroll fits into your product’s overall architecture.
Define Your Payroll Scope and Requirements
Start by being specific with the scope of your new payroll solution. Outline key questions, such as the following:
- Will you support contractors, full-time employees, or both?
- Do you plan to handle the flow of funds, or leave that up to your embedded payroll partner?
- Will you support benefits disbursement?
- How often will payroll run (weekly, biweekly, monthly)?
- Will your users need support for multistate or international payroll?
- How will you handle payroll-related notifications and errors? Consider whether you will ingest webhooks directly or rely on the embedded partner’s notification system to keep users informed in real time.
Answering these questions helps shape the design of the architecture for your embedded payroll system.
Understand the Core Payroll Components
Most payroll systems have a few essential building blocks. These include employee records containing compensation info, job titles, addresses, pay rates, and job level. You also need to consider time tracking (eg expected hours, maximum hours allowed, and overtime compensation), which can come from your platform or other external integrations.
Don’t forget about tax deductions and calculations, which are typically handled automatically by embedded payroll providers like Gusto. Compliance matters, like filing federal and state taxes as well as issuing W-2s and 1099s, are also abstracted away by some providers, but developers still need to ensure that the user interface and data collection processes flow seamlessly.
Identify the Right Integration Approach
Embedded payroll providers often offer tools that let you build your product while leveraging their backend systems. You need to decide where payroll fits within your product. Will it live in a stand-alone section of your app, or will it be visible from the dashboard or part of a guided onboarding flow?
When embedding payroll into your application, you will typically choose from three integration paths: embedding UI components (via iFrames or similar), SDKs, or APIs. Each offers a different balance of speed, control, and customization. Keep in mind, these approaches aren’t mutually exclusive; developers can use one or more of these options based on their product goals.
Here’s a rough comparison to help guide your decision:
| Feature | iframes (Flows) | SDK | API |
|---|---|---|---|
| Dev effort | Lowest – embed prebuilt interfaces | Medium – install and configure the SDK | Highest – build custom frontend and integrate each endpoint |
| Time to launch | Fastest – minimal setup, quickest path to production | Moderate – requires some development | Longest – full control, but more work to implement |
| UX customization | Limited – matches partner styling but not deeply customizable | Moderate – can adjust styling and interactions | Full – complete control over frontend experience |
| Data interconnectivity | Limited – data interactions via pre-set flows | Moderate – access data via SDK abstraction | Full – raw access to all available data endpoints |
| Best for | Teams wanting fastest integration and no custom UI | Teams wanting balance of speed and flexibility | Teams needing full control and deep product integration |
| Example use case | Quick launch of payroll inside an existing HR product | Mid-size SaaS app integrating payroll in a semi-custom flow | Enterprise-grade platform deeply embedding payroll into their core product |
Define User Roles and Permissions
Plan your user roles and access levels early as this impacts authentication and route management later in development. This step is important for both security and regulatory compliance. Payroll access should be limited to essential personnel.
Define who in the user base has permission to modify payroll settings, add or remove employees’ access, view employee compensation, and approve, run, and view the payroll. Make sure you plan out roles like the following:
- Administrators can run payroll, configure tax settings, and manage the entire payroll setup.
- Managers can approve timesheets, overtime hours, and paid time-off requests.
- Employees have view-only access to their pay stubs and can update personal details, like addresses and bank information.
Step 2: Design the User Experience
With some foundational planning in place, the next task is designing how the payroll system functions and feels to your users. The design of your payroll interface must meet the needs of a payroll administrator, managers, and employees.
Map the Payroll User Journey within Your Application
Designing a great payroll experience requires you to think through how different users interact with the system. Each persona, administrator, manager, and employee has distinct needs, expectations, and workflows. Make sure that you check the needs of these personas in your company. Your UX should reflect those differences clearly.
Cross-User Device Access
Consider how these users will access the system. Do you need to build a responsive, mobile-friendly employee portal? Are administrators using tablets or desktops? Check your platform analytics to determine device trends. A mobile-optimized experience is especially important for employees who may be clocking in or requesting time off from their phones.
Consider Branding
Embedded payroll works best when it appears integral to your application. Avoid redirecting users to a separate third-party tool; instead, integrate it into the existing system design your users are accustomed to.
For instance, if you plan to use a prebuilt UI component from Gusto Embedded, consider using it as an iframe within your existing page. You can make the app look and feel consistent across specific contexts and all offerings by incorporating all your existing color themes and branding.
Keep in mind that both payroll administrators and employees will interact with your interface. Employees may need to log in to self-onboard, update employment details, or access documents like W-2s or 1099s. Ensuring a seamless branded experience for both roles strengthens trust and reinforces the perception that payroll is a native part of your product.
Handle Errors with Clarity
Users of your payroll solution need helpful feedback when things go wrong, whether it’s a bad input, server timeout, invalid URL, or failed submission. If you’re using an embedded solution like Flows, this is handled for you. Otherwise, you need to make sure that you expose any errors in a user-friendly language. This builds trust that your system knows what it’s doing.
On the backend, ensure proper logging and error handling are implemented where appropriate for better observability of the application.
Balance Seamless UX with Compliance Requirements
While the goal is to make the user experience effortless, you can’t ignore the necessary guardrails around legal compliance. Payroll is already tightly bound to legal obligations like proper worker classification, tax filings, and withholdings.
Your UX needs to guide users without overwhelming them. Try to strike a balance by autovalidating inputs in real time and surfacing errors. You can also progressively disclose complex fields when needed (eg showing tax prompts only after an employee state has been selected). This approach ensures your app remains compliant without feeling like a tedious checklist of government-style forms.
With Gusto Embedded, many of these checks are built in. You just need to reflect them in your UI. If you’re using the API, you can also import some existing data you already have on your platform to speed up the onboarding process.
Step 3: Manage API Integration and Development
Once your user experience is mapped out, it’s time to integrate payroll capabilities with the Gusto Embedded API.
Sign Up and Create a Developer App
Start by signing up for a developer account at Gusto Embedded. While creating your account, make sure you select Yes as an answer to the question, Are you building embedded payroll?
After registering, you gain access to a sandbox environment for testing the API. You’ll be prompted to create the following:
- Organization: Use your company name.
- Application: Use your app’s name.
Once your app is created, you can access your development credentials. To view them, go to the Applications section in the developer portal and select your newly created application. Select Details. You should then see your Client ID and Client Secret:
Generate a System Access Token
Once you have your credentials, use them to generate a system-level access token with the POST /oauth/token endpoint. This token enables high-level operations like creating companies or managing webhooks:
curl --request POST \
--url https://api.gusto-demo.com/oauth/token \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"grant_type": "system_access"
}'
Your response should look something like this:
{
"access_token": "yFk_3rtWv5YmwleO8bUF6q0xqd_KayR2kkEj3kSW_E",
"token_type": "bearer",
"created_at": 1747070279,
"expires_in": 7200
}
This response comes with the token and an expiration time (usually two hours). Save your access_token as you need it in the next section.
Create a Company
Once you have your system access token, you can create a new company via the POST v1/partner_managed_companies endpoint:
curl --request POST \
--url https://api.gusto-demo.com/v1/partner_managed_companies \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'\
--header 'Authorization: Bearer {SYSTEM_ACCESS_TOKEN}'\
--data '{
"user": {
"last_name": "Mooney",
"first_name": "James",
"email": "jmooney@mooneybooks.com"
},
"company": {
"name": "Mooney's Bookstore"
}
}'
The user object defines the payroll administrator for the new company, and the company object represents the company’s name.
Your response looks like this:
{
"company_uuid": "3d87f834-567b-46b4-8e67-5bcbb5891b30",
"access_token": "COMPANY_ACCESS_TOKEN",
"refresh_token": "REFRESH_TOKEN",
"expires_in": 7200
}
Save the company_uuid and access_token. The access_token is used for API requests related to this specific company:
Refresh the company access token by calling the /oauth/token endpoint:
curl --request POST \
--url https://api.gusto-demo.com/oauth/token \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"refresh_token": "REFRESH_TOKEN",
"grant_type": "refresh_token"
}'
Your response looks like this:
{
"access_token": "NEW_ACCESS_TOKEN",
"token_type":"Bearer",
"expires_in":7200,
"refresh_token":"NEW_REFRESH_TOKEN",
"created_at":1747133853
}
To run payroll, your customer (the employer using your platform) must undergo onboarding, which includes setting up company locations, tax details, bank details, pay schedules, and signing documents. You can either complete the onboarding via the API or through an onboarding flow, which is a prebuilt onboarding UI where the administrator can fill in the onboarding information.
To create a company onboarding flow, make the following request with the company_uuid:
curl --request POST \
--url https://api.gusto-demo.com/v1/companies/:company_uuid/flows \
--header 'X-Gusto-API-Version: 2024-04-01' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <YOUR_COMPANY_ACCESS_TOKEN>' \
--data '{
"flow_type": "company_onboarding"
}'
Your response looks like this:
{
"url": "https://flows.gusto-demo.com/flows/j_8hImNKE1-dilrAZa7DDu9JvGsNykB5jYlajuM2iLk"
}
This link directs the administrator to the onboarding UI:
Create an Employee
Employees are the whole point of payroll. Once company onboarding is complete, you can start adding employees with the company access_token. Use the POST/v1/companies/{company_id}/employees` endpoint:
curl --request POST \
--url https://api.gusto-demo.com/v1/companies/{company_uuid}/employees \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {COMPANY_ACCESS_TOKEN}' \
--header 'Content-Type: application/json' \
--data '{
"first_name": "Jane",
"last_name": "Doe",
"email": "jane.doe@example.com",
"date_of_birth": "1990-01-01",
"ssn": "123-45-6789",
"self_onboarding": true
}'
Your response should look like this:
{
"uuid": "8a3e87ed-9374-4294-b973-151fbda49415",
"first_name": "Jane",
"middle_initial": null,
"last_name": "Doe",
"email": "jane.doe@example.com",
"company_uuid": "5afc83f5-6d83-4a1a-814e-7b7a04916b98",
"manager_uuid": null,
"version": "e6c19131b0ab504a5458e426802a8b51",
"current_employment_status": null,
"onboarding_status": "self_onboarding_pending_invite",
"preferred_first_name": null,
"department_uuid": null,
"employee_code": "9871fa",
"payment_method": "Check",
"department": null,
"terminated": false,
"two_percent_shareholder": null,
"onboarded": false,
"historical": false,
"has_ssn": true,
"onboarding_documents_config": {
"uuid": null,
"i9_document": false
},
"jobs": [],
"eligible_paid_time_off": [],
"terminations": [],
"garnishments": [],
"date_of_birth": "1990-01-01",
"ssn": "",
"phone": null,
"work_email": null
}
The employee has now been created in the system under the company whose company_access_token was used. The uuid in the response represents the employee’s UUID, which can be used to assign a job and compensation to the employee.
Once the employee has been created, they need to be onboarded. Just like you created a company onboarding flow earlier, you can now create a flow to onboard employees. This example shows how to use the employee_self_management flow type, which allows employees to enter their own information through a secure, embeddable UI. To do that, call the POST v1/companies/:company_uuid/flows endpoint:
curl --request POST \
--url https://api.gusto-demo.com/v1/companies/:company_uuid/flows \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_COMPANY_ACCESS_TOKEN'
--data '{
"flow_type": "employee_self_management",
"entity_uuid": "<YOUR_EMPLOYEE_UUID>",
"entity_type": "Employee"
}'
The request returns a link that an employee can follow to enter their personal information:
{
"url": "https://flows.gusto-demo.com/flows/DSueZAt0QqqPeZFUgNheoLQavqSa2tDGsDjpYhcxXiU"
}
This can be put in an iframe within your existing user interface:
Gusto Embedded supports multiple onboarding flows. This example uses the employee_self_management flow type to delegate onboarding to the employee. Alternatively, you could use the add_employees flow to onboard employees programmatically. The right choice depends on how much control you want to give employees versus handling onboarding on their behalf.
Assign Compensation
After creating the employee, the next step is to assign a compensation package using the POST v1/employees/{employee_id}/jobs endpoint:
curl --request POST \
--url https://api.gusto-demo.com/v1/employees/{employee_uuid}/jobs \
--header 'Authorization: Bearer COMPANY_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"title": "Software Engineer",
"primary": true,
"compensations": [
{
"payment_unit": "Hour",
"rate": "25.00",
"flsa_status": "non_exempt",
"effective_date": "2023-01-01"
}
]
}'
This request creates a job and sets a compensation of $25 USD per hour for the employee associated with the given uuid. A sample response looks like this:
{
"uuid": "f59cee4e-cc16-4d9b-96e7-b4e560ce9c8b",
"version": "d527a7bb424b6b02724aa3766ce4b37b",
"employee_uuid": "8a3e87ed-9374-4294-b973-151fbda49415",
"current_compensation_uuid": "04b58344-ebd2-4192-80eb-f095d218bbd1",
"payment_unit": "Hour",
"primary": true,
"two_percent_shareholder": false,
"state_wc_covered": null,
"state_wc_class_code": null,
"title": "Software Engineer",
"compensations": [
{
"uuid": "04b58344-ebd2-4192-80eb-f095d218bbd1",
"employee_uuid": "8a3e87ed-9374-4294-b973-151fbda49415",
"version": "6fc2b427fb336b6bc8a442ee3e3c9e62",
"payment_unit": "Hour",
"flsa_status": "Nonexempt",
"adjust_for_minimum_wage": false,
"minimum_wages": [],
"job_uuid": "f59cee4e-cc16-4d9b-96e7-b4e560ce9c8b",
"effective_date": "2025-05-25",
"rate": "0.00"
}
],
"rate": "0.00",
"hire_date": "2025-05-25"
}
Create a Pay Schedule
In this step, you need to configure a pay schedule, which defines the recurring payroll period for employees. Use the POST v1/companies/{company_uuid}/flows endpoint to create a flow for managing payroll schedules:
curl --request POST \
--url https://api.gusto-demo.com/v1/companies/{{company_uuid}}/flows \
--header 'Authorization: Bearer {{company_access_token}}' \
--header 'Content-Type: application/json' \
--data '{
"flow_type": "manage_payroll_schedule"
}'
Your response looks like this:
{
"url": "https://flows.gusto-demo.com/flows/5un3f0nHsA6Jicd1pi0d8MirkIm0HZcYwH8brM_oBSo"
}
The URL in the response is a flow link where a company admin can configure the payroll schedule, setting the pay periods and check dates:
Calculate Payroll
If you want to preview taxes, benefits, bonuses, garnishments, and other deductions before submitting payroll, admins can review this summary to ensure everything is accurate.
To fetch the upcoming payroll ID, use the following GET /v1/companies/{company_id}/payrolls endpoint in a request:
curl --request GET \
--url https://api.gusto-demo.com/v1/companies/{{company_id}}/payrolls?processing_statuses=unprocessed&payroll_types=regular%2Coff_cycle&start_date=2025-06-01&end_date=2025-06-30 \
--header 'X-Gusto-API-Version: 2024-04-01' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {{company_access_token}}' \
Your response looks like this:
{
"uuid": "198a9a7b-4435-4e19-936f-a8d090ef98e3",
"payroll_uuid": "198a9a7b-4435-4e19-936f-a8d090ef98e3",
"company_uuid": "d8361f93-ab88-4c26-b7ac-e57a01e4ca9f",
"off_cycle": false,
"auto_pilot": false,
"processed": false,
"processed_date": null,
"calculated_at": null,
"pay_period": {
"start_date": "2025-06-01",
"end_date": "2025-06-30",
"pay_schedule_uuid": "87d93496-2d21-400c-9754-8bef3d0e0eb4"
},
"check_date": "2025-06-30",
"external": false,
"payroll_deadline": "2025-06-24T23:00:00Z",
"created_at": "2025-05-19T12:24:53Z"
}
Then, use the payroll_uuid from the previous step to calculate the payroll in a PUT request:
curl --request PUT \
--url https://api.gusto-demo.com/v1/companies/{{company_uuid}}/payrolls/{{payroll_id}}/calculate \
--header 'authorization: Bearer <COMPANY_ACCESS_TOKEN>' \
--header 'accept: application/json'
Submit Payroll
Once everything looks correct in the payroll calculation stage, it’s time to submit the payroll in a PUT v1/companies/{company_uuid}/payrolls/{payroll_uuid}/submit request. Without this step, the payroll can’t be finalized:
curl --request PUT \
--url https://api.gusto-demo.com/v1/companies/{company_uuid}/payrolls/{payroll_uuid}/submit \
--header 'authorization: Bearer COMPANY_API_TOKEN'
Upon success, the payroll is marked as processed, and Gusto initiates payments and tax filings as needed.
Step 4: Perform Testing and Use Case QA
Once you’ve integrated the payroll, the next step is rigorous functional and compliance testing. Negligence in payroll processing can have serious legal and financial ramifications, so you must double-check every aspect of the workflow.
Test in a Sandbox Environment
Simulate various payroll runs using test data. Try creating new companies, onboarding new employees, and calculating pay based on hours and rates, bonuses, and pay raises. Don’t forget to test processing direct deposits.
Gusto Embedded provides a robust sandbox that mirrors production behavior.
Implement Tax and Compliance Validation Processes
One of the most complex aspects of payroll is handling taxes across different states, employment types, and schedules. Use test cases to confirm accurate calculations for local, state, and federal taxes, including for late payroll submissions.
After running test scenarios, review the output Gusto provides for tax filings and payment distributions. Check that the data aligns with local regulations and your business rules. This ensures technical reliability and protects your users from fines and liability.
With a trusted embedded provider like Gusto, much of the heavy lifting of compliance is handled for you, but you still must confirm that your implementation is sound.
Anticipate Edge Cases
Testing edge cases prevents surprises. Your testing should cover cases like payroll submission errors, mid-period terminations, prorated payments, severance pay, and changes in employee tax status.
Step 5: Carry Out Deployment and Ongoing Management
Successfully embedding payroll isn’t just about getting it working; you need to keep it working securely, reliably, and fully compliant as your product evolves. Once your testing is complete, you need to deploy your payroll system to production and establish an ongoing process for maintenance.
Secure Deployment Strategies
Start by reviewing your authentication and data handling practices. Payroll usually involves sensitive personally identifiable information (PII) and financial data, so production deployments should use strict access control, secure encryption, and storage.
Gusto Embedded leverages the Gusto secure and scalable infrastructure, backed by over a decade of experience in payroll processing and compliance.
Monitor API Versioning
As your application grows, the Gusto Embedded versioning strategy ensures that new version upgrades don’t break existing ones. Be sure to stay up-to-date with changes in the API, subscribe to changelogs, and update notifications so that you know when new features and improvements are released.
Provide Payroll Visibility
Consider building a payroll admin dashboard for tracking and reporting payroll summaries, payroll histories, errors, and upcoming payroll run reminders. This helps give transparency to payroll runs, payment statuses, and tax filings. Even though Gusto handles the backend infrastructure, your users still need to feel in control of payroll on your platform. Use the data that the Gusto API returns to create engaging UI elements.
Support Your Users
Payroll is time-sensitive. Late payments or payment errors can lead to low morale and legal issues. Make sure your support team is highly available and ready to respond to questions about delays and errors.
Since Gusto manages core compliance and processing, you see fewer support tickets for things like tax filings or direct deposits. However, it’s still important to prepare for frontline user questions and set up triage workflows to handle them effectively.
Be Ready to Scale
As your user base grows, so does the complexity of your payroll. That includes multiple company profiles, new payment types, new states, and maybe even international support.
A well-managed payroll integration requires ongoing support, monitoring, and observability. As you expand to support more complex needs like multiple EINs, state-specific tax rules, or contractor classifications, make sure your integration scales accordingly.
Conclusion
Embedding payroll isn’t easy, but Gusto Embedded can help. The payoff: higher user retention, satisfaction, and revenue growth.
In this article, you learned five steps to help you in your integration journey. Each step comes with challenges, like navigating tax laws and balancing legal requirements. With Gusto doing the heavy lifting for tax filings, direct deposits, and compliance, your team can focus on building a great product.
If you are ready to bring full-service payroll into your product, get started with Gusto Embedded today.
