Help Center

Everything sent to Crystal comes from approved timesheets and leave for the dates you export.

• Approved hours go as worked hours on each day: Normal hours, or under the position's job pay rate if you turn that on.
• Areas go as the Crystal department on each worked row, if you turn that on.
• Approved leave goes as 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 go as one row per allowance type per pay period, matched to the Crystal allowance by name, if you turn that on.
• Public holidays: only the hours worked go. Crystal works out the holiday pay and alternative holidays itself.
• Leave balances come back from Crystal (annual, sick, alternative holiday and family violence) when you click Sync Leave Balances.

Crystal keeps API access separate from the login you use to run pays, so there's a one-off setup on Crystal's side first.

1. Create a Crystal API login. Sign up at api.crystalsoftware.nz. Crystal emails your login details.
2. 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.
3. 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.

1. In RosterMates, go to Settings → API's and select Crystal Payroll.
2. Choose your export options. You can change them any time, here or in the export window.
3. 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 Options

• 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, placed on a day the employee has no hours or leave. Off: hours only, and you key allowances into Crystal by hand.

1. In Crystal, go to Employee Settings → Employee Details and find each employee's Staff ID.
2. In RosterMates, go to the Manage tab and select the employee in the employee sidebar.
3. 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, not 41).

Repeat for everyone you pay through Crystal. Before each export, RosterMates checks every employee against Crystal and lists anyone it can't match.

Once Crystal is connected, a Sync Leave Balances button appears on the Leave page. 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, so managers can decide on leave in RosterMates without looking up balances in Crystal. Sync again whenever you want RosterMates to catch up, and always after a public holiday.

1. In RosterMates, approve the pay period's timesheets.
2. Go to Summary, set the dates to exactly the pay period you're running in Crystal, click Export, choose Crystal and click Export Timesheets.
3. In Crystal, select Process a Pay in the sidebar, then Time & Income under it.
4. Check that the current period in the top right corner is the same date range you exported from RosterMates.
5. Click Data Import. The hours, leave and allowances pull through.
6. Check the pays in Crystal, then process the pay run as usual.

Exporting the same dates again replaces what RosterMates sent last time, so you can fix something in RosterMates, export again and click Data Import again.

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, or whether an alternative holiday is owed. So RosterMates sends the hours worked, and Crystal works out public holiday pay, Mondayisation and alternative holidays from the work patterns 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. Two things to do around a public holiday:

• 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, RosterMates won't know about alternative holidays Crystal has given out. After the public holiday pay run, click Sync Leave Balances on the Leave page again.

Salaried Staff

Set salaried staff 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, and Crystal looks for a pay item with exactly that name. Set up a matching pay item in Crystal for every position you use, or leave the switch off.

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, 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.

• An employee isn't matched: their Payroll Employee ID 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: check the employee's work pattern in Crystal. Crystal decides public holiday pay from it, not from RosterMates.

Still stuck? Book a free setup call and we'll sort it out with you.