You need an administrator login for Crystal Payroll and access to Settings, Manage and Summary in RosterMates. Steps 1 to 4 are a one-off. After that, each pay run is one export from RosterMates and one click of Data Import in Crystal.
Rather not do it yourself? The RosterMates team will set the whole thing up for you, free, if you give us access to your Crystal account. Book a free setup call.
Crystal Payroll and RosterMates have a direct API connection, so there are no files to download or upload. When your timesheets are approved, RosterMates sends each day's worked hours, leave and allowances straight into Crystal's timesheet import. In the other direction, RosterMates can pull every employee's leave balances back out of Crystal, so your managers see the real numbers when they approve leave.
This guide walks through the one-off setup on both sides, what to do each pay run, and how public holidays work between the two systems.
What goes between RosterMates and Crystal
Everything sent to Crystal comes from approved timesheets and leave for the dates you export.
| From RosterMates | Arrives in Crystal as |
|---|---|
| Approved hours | Worked hours on each day, as Normal hours, or under the position's job pay rate if you turn that on |
| Areas | The Crystal department on each worked row, if you turn that on |
| Approved leave | The matching Crystal leave type: Annual, Sick, Alternative, Bereavement, Family Violence, Parental, Unpaid or ACC Paid Leave. Study, jury and other special leave go as Other Paid Leave |
| Allowances | One row per allowance type per pay period, matched to the Crystal allowance by name, if you turn that on |
| Public holidays | The hours worked. Crystal works out the holiday pay and alternative holidays itself (more below) |
| From Crystal | Arrives in RosterMates as |
|---|---|
| Leave balances | Each employee's annual, sick, alternative holiday and family violence leave balances, when you click Sync Leave Balances |
Step 1: get your Crystal API access
Crystal keeps API access separate from the login you use to run pays, so there's a one-off setup on Crystal's side before you can connect.
- Create a Crystal API login. Sign up at api.crystalsoftware.nz. Crystal emails your login details.
- Give it access to your company. Sign in to the API portal and open Permission → Create. Enter your API login's email as the User Email, choose All Permissions, tick the terms and click Save & Send Email.
- Turn on Staff IDs in Crystal. Go to Company Settings → Payroll Settings → Advanced Settings, tick Enable Employee Staff ID and save.
Stuck on Crystal's side? Call Crystal Payroll support on 09 480 0123.
Step 2: connect RosterMates to Crystal
- Log in to RosterMates, go to Settings → API's and select Crystal Payroll.
- Choose your export options. You can change them any time, here or in the export window.
- Click Connect Crystal Payroll. Crystal's sign-in page opens: enter the Company Code, Username and Password of your API login, not your everyday payroll login.
| Export option | What it does |
|---|---|
| Send positions as job pay rates | Worked hours are typed with the RosterMates position name, so Crystal applies that job's rate. Off: everything goes as Normal hours. Position names must exist as pay items in Crystal. |
| Send areas as departments | Each worked row carries the RosterMates area as the Crystal department. Off: no department is sent. |
| Send allowances | Approved timesheet allowances go as one zero-hour row per allowance type per pay period, on a day the employee has no hours or leave. Off: hours only, and you key allowances into Crystal by hand. |
Step 3: match each employee's Staff ID
RosterMates finds each person in Crystal by their Staff ID.
- In Crystal, go to Employee Settings → Employee Details and find each employee's Staff ID.
- In RosterMates, go to the Manage tab and select the employee in the employee sidebar.
- Open the Employment tab, scroll down to Banking Details and type their Staff ID into Payroll Employee ID, exactly as Crystal shows it, including leading zeros (
0041, not41).
Repeat for everyone you pay through Crystal. Before each export, RosterMates checks every employee against Crystal and lists anyone it can't match, so nobody goes missing quietly.
The RosterMates team will set up the connection and match every employee for you, free, if you give us access to your Crystal account. Book a free setup call.
Step 4: sync leave balances
Once Crystal is connected, a Sync Leave Balances button appears on the Leave page in RosterMates. Click it, check the preview of each employee's balances from Crystal, then click Sync Balances to RosterMate.
RosterMates and Crystal then hold the same annual, sick, alternative holiday and family violence leave balances for all your staff, so managers can make leave decisions in RosterMates without looking up balances in Crystal first. Sync again whenever you want RosterMates to catch up, and always after a public holiday (see below).
Every pay run: export and import
RosterMates is now ready to export to Crystal. Each pay run:
- In RosterMates, approve the pay period's timesheets.
- Go to Summary, set the dates to exactly the pay period you're running in Crystal, click Export, choose Crystal and click Export Timesheets.
- In Crystal, select Process a Pay in the sidebar, then Time & Income under it.
- Check that the current period in the top right corner is the same date range you exported from RosterMates.
- Click Data Import. The hours, leave and allowances pull through.
- Check the pays in Crystal, then process the pay run as usual.
Exporting the same dates again replaces what RosterMates sent last time, so if something needs fixing, correct it in RosterMates, export again and click Data Import again.
Public holidays: Crystal does the work
Crystal's import has no way for RosterMates to say that a day was a public holiday, whether it was a normal working day for the employee (an "otherwise working day"), or whether an alternative holiday is owed. So RosterMates sends the hours worked, and Crystal works out the public holiday pay, Mondayisation and alternative holidays itself, from the work patterns you've set up in Crystal.
That means you don't need to fill in the public holiday table on the RosterMates timesheet for Crystal's sake: Crystal can't receive it anyway.
Keep work patterns up to date in Crystal. They decide who gets paid for the day off and who earns an alternative holiday. Check public holiday pays in Crystal before you process them.
Sync leave balances afterwards. If you skip the public holiday table in RosterMates to save time, RosterMates won't know about alternative holidays Crystal has given out, so its balances drift. After the public holiday pay run, click Sync Leave Balances on the Leave page again and everything lines up.
A few things to note
Salaried staff
If someone is on a salary, set them up as salaried in RosterMates as well: on the Employment tab, set Paid by to Salary and enter their salary. RosterMates then sends only their leave and allowances, because Crystal pays the salary; otherwise their worked hours would go to Crystal too and could be paid on top. Anything else that changes their pay, such as a public holiday they worked, is listed in the export for you to add in Crystal.
Job pay rates
With Send positions as job pay rates on, each worked row uses the RosterMates position name. Crystal looks for a pay item with exactly that name, so set up a matching pay item in Crystal for every position you use, or leave the switch off and everything goes as Normal hours.
Allowances
Crystal matches allowances by name, so the allowance's payroll code in RosterMates (or its name, if it has no code) must match the allowance in Crystal. Crystal takes one entry per allowance type per pay period, and it has to sit on a day with no hours or leave. If every day in the period is taken, RosterMates tells you which allowance to key into Crystal by hand.
If something doesn't come through
| What you see | What to check |
|---|---|
| An employee isn't matched | Their Payroll Employee ID in RosterMates doesn't exactly match their Crystal Staff ID. Check leading zeros |
| Nothing appears after Data Import | The current period in Crystal's Time & Income doesn't match the dates you exported |
| Rows for a position are rejected | The position name isn't a pay item in Crystal. Add it, or turn off Send positions as job pay rates |
| An allowance is missing | Its name doesn't match the allowance in Crystal, or there was no free day in the period for it |
| "Session expired" or a reconnect message | Reconnect in Settings → API's → Crystal Payroll with your API login |
| Public holiday pay looks wrong | The employee's work pattern in Crystal. Crystal decides public holiday pay from it, not from RosterMates |
One more option: pay your team from RosterMates
A lot of this guide exists because two systems have to agree: Staff IDs, pay item names, allowance names, work patterns kept up to date in Crystal, and leave balances synced back after every public holiday. That's the price of sending timesheets from one system to another.
RosterMates also runs payroll. It's IRD-approved, and it pays from the same roster, timesheets, position rates, allowances, leave balances and public holiday table you already keep, so there is nothing to export and nothing to match up. It works out PAYE, KiwiSaver, ESCT and student loan, emails payslips, handles leave payouts and final pays, makes a bank batch file and files your payday returns with IRD.
It is also part of the plan you already have. RosterMates is $8 per employee per month for the whole system: rostering, clock-ins, timesheets, leave and payroll. If you only want payroll, RosterMates payroll on its own is $1.50 per employee per month, with a $15 minimum that covers up to 10 staff. Crystal is one of the cheapest payroll systems in New Zealand, and RosterMates payroll still costs less at every size, whether you pay Crystal monthly or yearly. Here is how they compare, per month (excluding GST):
| Team | Crystal (Payroll Only)Charged per month, in bands of 5 staff | RosterMates (Payroll Only)Charged per month | RosterMates (Everything)Charged per month |
|---|---|---|---|
| 5 | $19.90 a monthor $199 a year ($16.58 a month) | $15.00 a month | $40.00 a month |
| 10 | $29.90 a monthor $299 a year ($24.92 a month) | $15.00 a month | $80.00 a month |
| 20 | $49.90 a monthor $499 a year ($41.58 a month) | $30.00 a month | $160.00 a month |
| 50 | $109.90 a monthor $1,099 a year ($91.58 a month) | $75.00 a month | $400.00 a month |
| 100 | $209.90 a monthor $2,099 a year ($174.92 a month) | $150.00 a month | $800.00 a month |
RosterMates (Everything) also includes rostering, clock-ins, timesheets and leave. Crystal prices are from Crystal's published pricing (crystalpayroll.com/pricing), checked in September 2026: $19.90 a month for up to 5 staff plus $10 for each extra 5, or ten times that paid yearly. Crystal's $50 one-off registration fee and add-ons such as Audit Trail are extra. Against the published prices of Crystal Payroll, Smartly, iPayroll, PayHero, Employment Hero and Xero (checked September and October 2026), RosterMates payroll costs less at every team size and pay frequency they list a price for; iPayroll quotes from 100 staff and Crystal from 500. Thankyou Payroll caps its monthly price, so it can cost less for teams over 265 staff or for 1 to 4 staff paid monthly, and it is free for registered charities. RosterMates pricing is at rostermates.com/nz/pricing.
If you already use RosterMates alongside Crystal, the payroll side is already paid for. Crystal is a good payroll system and the connection above works well. But if you'd like one system instead of two, see how RosterMates payroll works or book a free call to talk about moving across.
