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

1. Embed our components within your application
2. Integrate with Paystream API to import data
3. 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.

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 🛠️

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.