Building your integration with KeyPay Cloud Payroll

Building an integration with KeyPay will create a more seamless, end-to-end payroll experience for your customers without actually building your own payroll platform.

Follow our guide below to understand your integration options and get started with integrating with KeyPay. This guide is built primarily for HR and timesheet integrations, but may be used to guide through many other solution integration types. If you feel something is missing from this guide for your particular scenario, please get in touch with your sales contact (if you don’t have one yet, please email the support team with your query.

Choose your authentication method

As a KeyPay integration partner, you can streamline your existing customers’ processes, make your solution more sticky, and provide value-add benefits for prospective customers too.

There are a number of approaches you can take to your integration, depending on your business needs, resources, and setup.

Assess the options to understand the benefits of and requirements for each approach, and what would be best suited to your business, solution, and customers. Once you’ve chosen your best suited method, head to the ‘Quickstart guide’ to get started.

1. Standard integration using OAuth2
OAuth2 is a way to authenticate a new integration partner to enable them to use our API specifically for their solution. This approach is the simplest way to set up an integration with KeyPay.

2. Standard integration with Single Sign On (SSO)
Think of when you use your Google or Facebook details to quickly log in to an app or an eCommerce store: SSO is the same sort of concept but unique to your customers when accessing KeyPay.

3. iFrame integration
The iFrame integration is for when you want to offer top level payroll functionality directly within your product, but you don’t want to build your own payroll offering. iFrame will help you achieve a seamless experience for your customers, resulting in a stickier customer base.

1. Standard integration using OAuth2

OAuth2 is a way to authenticate a new integration partner to enable them to use our API specifically for their solution. This approach is the simplest way to set up an integration with KeyPay.

If you choose the OAuth2 integration option, your customers would require their own separate account for KeyPay. Your solution and KeyPay would be independent from each other, except for the specific integration components that you would choose to make available. Integration components would be specific sets of data that you want to automatically send or retrieve via the KeyPay API, such as timesheet or employee data.

Why would I choose OAuth2 as an integration approach?
Here are some examples of why you would choose the OAuth2 integration:

• You’re an HR solution whose clients already have an account with KeyPay looking to send employee data over to payroll. This integration would allow your existing customers to send data over to KeyPay, always keeping it up to date, and without the need to import/export between systems.
• You want the above and you would prefer not to provide payroll support to your customers. Via this integration option, users would be KeyPay customers and therefore all payroll support would be managed via KeyPay.

Considerations: although this is the quickest option, your clients will need to set up their own KeyPay account, and sign up for a KeyPay subscription independently from your product.

2. Standard integration with Single Sign On (SSO)

Think of when you use your Google or Facebook details to quickly log in to an app or an eCommerce store: SSO is the same sort of concept but unique to your customers when accessing KeyPay.

The SSO option has a similar outcome to OAuth2, but with a much simpler user onboarding journey for your customers.

By using SSO, a user profile is created for your customer using the data from your system, assigning each customer a unique ‘token’. These tokens are recognised by KeyPay, and act as authentication, allowing your customers to log into KeyPay using the same login details they use for your system. This means there is no need for the customer to create a separate KeyPay account, and they are authorised to log into KeyPay directly from your platform.

Why would I choose SSO?

Think of SSO as your own branded payroll. The KeyPay name disappears from the system and is replaced with your chosen brand and custom URL. You control the billing. You control the support. KeyPay provides the tech.  

Here are some examples of why you would choose SSO:

• You want to quickly create a simplified onboarding experience for your users between your product and payroll. You’d provide the seamless payroll experience for your customers that you would via the OAuth2 integration, but without your customers having to take the extra step to set up a new account.
• You want to provide a reliable, compliant and easy-to-use payroll system for your customers with your brand. With the SSO option, you will have your own branded payroll and can rename the solution as your own.
  

Considerations: With SSO, you would become a reseller partner, with the most common process being that your customers would be billed by you for payroll. As a reseller partner, KeyPay would invoice you the relevant reseller pricing (PDF) and you can choose to bundle payroll with your existing offering, or offer separately, charging what you see fit; the sky’s the limit. As a reseller partner, you would manage payroll support.

3. iFrame integration

The iFrame integration is for when you want to offer top level payroll functionality directly within your product, but you don’t want to build your own payroll offering. iFrame will help you achieve a seamless experience for your customers, resulting in a stickier customer base.

The user setup for an iFrame integration is the same as SSO, but with the key difference being that you are able to embed (or iFrame) the KeyPay interface into your own solution. Although this method requires a little extra work on top of the authentication, the process is still fairly straightforward with the most streamlined outcome for your customer experience.

Why would I choose iFrame integration?

The iFrame option provides the most seamless experience for your users, and positions you as a truly all-in-one offering with your branded payroll solution embedded in your platform. Like the SSO option, you would become a reseller partner and can choose to bill your customers whatever you would like for this value-adding, comprehensive payroll solution.
This gives your app developers a greater level of control on how much ‘payroll infrastructure’ is exposed to your customers.

For example, with an HR integration you don’t want users updating payroll information in the payroll system and then having to sync that to the HR system; you’d prefer to push that information to payroll from HR. iFrame allows your customers to do this automatically, without your customers having to ever leave your platform. iFrame offers payroll functionality to your customers that is embedded in and connected with your app.

Quickstart guide

You’ve chosen your authentication method, and now it’s time to get started on your integration. If you’re not a developer and you’ve reached this section, it’s probably time to get your technical team involved.

1. OAuth2 authentication
2. SSO
3. iFrame

OAuth2 authentication

See here to get started on the standard integration via OAuth2.

SSO

At a high level, an SSO integration would require the following:

• You must set up a branded payroll account within KeyPay to generate an SSO user. To do this, please contact sales@yourpayroll.com.au, providing the information in this Integration Partner Checklist (PDF).
• Create an SSO only user: these users just need an email address and means we don’t store any passwords - they can’t login to KeyPay directly.
• When you create this user, a unique token is created for that user and you’ll be able to use that token to generate SSO tokens.
• Once you’ve created your SSO user, you simply need to initiate an SSO request. Each time you initiate an SSO request, you’ll generate a one time SSO token and then use that token to log in on behalf of the user into a browser session.

iFrame

For the iFrame integration, you would need to follow the steps for the SSO integration first. Then, see here for further guidance on setting up the iFrame.

Building your integration

Once the authentication is set up, here are the key steps to getting your integration up and running. The below outlines key steps for an HR system. If you are building an integration for your timesheet system, head to step 3.

1. Sync your employee data
2. Choose your next integration options
3. Timesheet integration

1. Sync your employee data

This is the most common set of data that is sent from HR to payroll. When sending this data you should consider:

• Do you store all the information in your system required for payroll? (i.e. tax details, salary information, leave history).
• If you don’t store all the information, do you want to add these fields into the system, or are you going to send through a partial employee record?
• How are you going to handle the initial sync of employee data into the payroll system? How are you going to send the employee data on an ongoing basis?

Considerations

• Best practice when syncing employee data is to have the HR system as the source of truth. It’s important to let your users know that information synced to payroll from the HR system will override the information in the payroll system.
• The KeyPay employee records have an “ExternalId” on the records which you can use to populate with your system Id - this ExternalId can be used throughout the API to reference an employee and match them between systems.
• There are lots of employee data points to choose from, depending on your build, all available in our API reference.

2. Choose your next integration options

Once you’ve built your employee sync, you’ve successfully built a basic integration (or a MVP for an integration) between your HR system and KeyPay. From here, there are a couple of common integration options that are supported:

• Import employee pay slips into your HR system’s employee portal. Employee pay slips are available via the API and are updated in real time. You can either import the raw pay slip information and display in a custom pay slip format, or provide a link to the pay slip PDF.
• Update employee leave balances within your HR application. After a pay run is processed, the employee’s ‘live’ leave balance is available via the API and can be used to provide real time leave balances to employees.

3. Timesheet integration

If you are a timesheet solution, or an HR solution that would like to integrate timesheets, you can sync timesheet information using the bulk timesheet API, to be processed in the pay run.

1. Some things to consider when sending timesheet data are:

• Timesheet data in KeyPay can be stored with either ‘start / stop’ times, or ‘units’. If you’re going to use award interpretation, you will need to go with start and stop times.
• Timesheet data can be very simple, but you can also provide enhanced data for timesheets such as locations, pay categories and work types. If you’re going to send this information, you need to ensure it has been set up in KeyPay prior to the timesheet import. There are API endpoints for all these data types.
• Timesheets can only be paid when they are ‘approved’. If you have an approval process in your system, you should send the timesheets through to KeyPay as approved.
• When sending timesheets, you can provide a rate of pay for that timesheet if the need arises. If you do this, the rate of pay will override the rate that is stored against the employee and will be multiplied by the units in the pay run.

2. Once you’ve built your MVP timesheet integration, you might consider some of the following advanced timesheet integrations:

• Our shift costing API allows you to retrieve the cost of each timesheet which can be used to provide costing information within your system.
• In addition to time worked, you can also record leave based timesheets which can be processed directly into the pay run. The LeaveCategoryId would need to be provided within a timesheet when submitting timesheets.