Launching payroll with Salsa Express
This guide gives a high-level overview of how to launch a payroll product using Salsa Express. For a more detailed, step-by-step tutorial, please visit our Build a Payroll App with Salsa Express page.
The Salsa Express Integration is the fastest path to embedding a robust, compliant, and beautifully designed payroll product into your platform. With just one engineer and four weeks, you can launch a fully featured payroll experience tailored to your brand using Salsa’s embeddable components, flexible APIs, and real-time webhooks.
🚀 3 steps to go from zero to payroll
- Embed our components within your application
- Integrate with Paystream API to import data
- Listen to recommended webhook events
Key Benefits
- Speed: Go live in 4 weeks with one engineer
- Control: Keep employer and compensation data within your platform
- Experience: Delight users with native-feeling, embeddable UIs
- Compliance: Salsa handles all payroll, tax, and filing complexity
Salsa's Paystream APIs allow you import the data you already have, while our embeddable components allow you to offer world-class payroll workflows with high customization, from styling to structure. You can easily adapt them to match your brand’s look and feel, and selectively enable or disable features to fit your exact use case. Plus, our webhook notifications will let you know when important events occur so you can deliver customer notifications and payroll documents using your own notifications.
Integration data flow overview
1. Embed our components within your application
In order to embed our components, you just have to follow 3 simple steps:
Obtain an API Token
To receive an API token for our sandbox environment, you just need to get in touch with us, and we would be shortly providing you with one.
- Salsa requires an OAuth 2.0 Bearer Token in the
Authorization
header of all requests made to our APIs. More info on the API Token here. - A User Token allows you to temporarily provision access for a user, with an access role that specifies their level of access to your data. You can create a User API Token through our Salsa’s Credentials API. The generated token has a configurable expiration time.xºº
Import our Salsa.js library
Loading and initializing the Salsa.js library is reduced to the following code. In order to customize the components to your own branding, you'll just need a Client Key that we will provide you with.
import { useScript } from './hooks/useScript';
useScript('https://js.salsa.dev/v0');
const [salsa, setSalsa] = useState();
if(window.Salsa && !salsa) {
setSalsa(window.Salsa('my-public-client-key', {env: 'sandbox'}));
}
// Load Salsa.js into your application
<script type="text/javascript" src="https://js.salsa.dev/v0" />
// Create an instance of Salsa.js using your Client Key and specifying the environment
const salsa = window.Salsa('my-public-client-key', {env: 'sandbox'});
Leverage Salsa.js to embed our components
You can get kickstarted into payroll by only implementing the following 4 embeddable components, and later on start expanding your payroll solution by implementing more of them:
- Employer Onboarding, where all the setup required for payroll is gathered in a single experience
- Employer Profile, to view and edit the employer’s setup information
- Employer Dashboard, the admin panel for the employers to run payroll
- Worker Profile, to manage the worker’s setup information
- Worker Payments List, provides a worker with a list of their payments
In order to implement our embedded components, you just have to:
Create a container for our embedded element
<div id='salsa-container' />
Create the element you wish to embed and mounting it in the container
const salsaElement = salsa.elements.create('demo');
salsa.elements.mount(salsaElement, '#salsa-container');
ℹ️ We also offer the Employer Onboarding and the Worker Onboarding as hosted experiences. An invite url can be retrieved through our APIs and sent over to the employer and/or workers for them to access those.
2. Integrate with Paystream API to import data
Paystream is our recommended API to import any data from your platform into Salsa. Paystream has different endpoints that allow you to import employers, workers or pay entries.
Importing Employers
Once an employer signs up for payroll in your platform, you can import the employer data into Salsa using Paystream - Import Employers endpoint
curl --location 'https://api.salsa.dev/api/rest/v1/paystream/employers' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <auth_token>' \
--data '{
"data": [
{
"type": "PaystreamEmployerUpsertInput",
"externalId": "myplatform_123",
"businessInfo": {
"businessName": "Beauty Hair Salon"
}
}
]
}'
Importing Workers
If your platform has data on the workers of a given employer, you can import them using our batch import endpoint Paystream - Import Workers
curl --location 'https://api.salsa.dev/api/rest/v1/paystream/workers' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <auth_token>' \
--data '{
"data": [
{
"type": "PaystreamWorkerUpsertInput",
"employerId": "<example_employer_id>",
"firstName": "John",
"lastName": "Doe"
},
{
"type": "PaystreamWorkerUpsertInput",
"employerId": "<example_employer_id>",
"firstName": "Mary",
"lastName": "Smith"
}
]
}'
Importing pay entries
If your platform has data regarding the worker compensation (e.g. hours worked or salary rate) you can send this data to auto-populate a payroll and save hours of manual input from your customer. In order to import compensation data from your platform into Salsa, you can use Paystream - Import payroll elements
curl --location 'https://api.salsa.dev/api/rest/v1/paystream' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <auth_token>' \
--data '{
"data": [
{
"type": "PaystreamPayEntryUpsertInput",
"workerId": "<example_worker_id_1>",
"payReferenceId": "ref:pay:saasexample:us:salary",
"startDate": "2025-01-01",
"endDate": "2025-01-31",
"amount": "3000.00"
},
{
"type": "PaystreamPayEntryUpsertInput",
"workerId": "<example_worker_id_2>",
"payReferenceId": "ref:pay:saasexample:us:hourly",
"startDate": "2025-01-03",
"endDate": "2025-01-03",
"hours": "8",
"rate": "25",
}
]
}'
3. Listen to recommended webhook events
For a more detailed, step-by-step tutorial, please visit our Webhooks guide. For the full list of events check the Callback
section on Create webhook endpoint page
To start running your payroll application we have a set of webhook events that can help in your operations side or when to sync up data with Salsa.
We recommend to start listening with the following events:
PayrollRun.awaitingInput
: triggers when compensation data is required for a payroll run. When receiving this event you must send all of the worker pay entry data you have for the listed workers within the interval provided through Paystream. Note that if you already have a well defined flow in your product on when to send pay entry data, this event is not required.Worker.onboardingStatus
: triggers whenever a worker is either invited to onboard, or has started/completed the onboarding.Notification.employerPaydayReminder
: triggers 2 days before the employer has to confirm the next scheduled payroll run.Notification.employerPayrollRunConfirmation
: triggers when an Employer confirms a payroll run.Notification.workerPayday
: triggers on the same day the worker is being paid. The event will be sent either at 1pm UTC or 11pm UTC of that day.
Further details
Implementation Timeline 🛠️
Phase | Task | Duration |
---|---|---|
Basic Infrastructure | Configure Auth token endpoint in your backend system | 4 hours |
User token generation | 2 days | |
Configure webhook endpoints and add a basic handler | 2 days | |
Sync employer data | Integrate Salsa.js | 2 hours |
Integrate with import employers Paystream API endpoint | 2 days | |
Embed Employer Profile | 4 hours | |
Employer Onboarding workflow | 2 days | |
Sync worker data | Integrate with import workers Paystream API endpoint | 3 days |
Embed Worker Profile | 4 hours | |
Worker onboarding workflow | 2 days | |
Enable payroll run experience | Integrate with import pay entries Paystream API | 3 days |
Embed Employer Dashboard | 6 hours | |
Embed Worker payments list | 4 hours | |
Total | Go live! | 4 weeks |
Additional Work (Non-Developer)
Some setup work requires product and/or design collaboration:
- Defining Pay Structures (usually driven by product) such as hourly vs salaried, payment frequencies, etc
- Branding Customization, defining colors, fonts, etc.
Updated 2 days ago