Xero Payroll

Owned by Nelson Leong, created
Last updated: Nov 17, 2024 by Maria Harreguy
5 min read

Content

Connecting

1.  New Connection to Xero with Payroll

2.  Changing Existing Connection to Xero

Data Mapping between Workbench and Xero

1.  Xero Payroll Calendar

2.  Week Ending Dates

3.  Employees

4.  Payroll Codes

Batching and Exporting

 

Connecting

1.  New Connection to Xero with Payroll

Connecting to Xero Payroll from Workbench requires an additional permission which is indicated on the Xero Integration screen.

For details on connection setup refer Getting Started with Xero Integration.


2.  Changing Existing Connection to Xero

If Payroll is being added to an existing Xero integration, it is recommended that the existing Workbench Connected App be removed from Xero.

and the connection with Xero will be re-established with the Payroll option set.

When logging into Xero, be sure the Xero login also has access to Xero Payroll.


 

Data Mapping between Workbench and Xero

1.  Xero Payroll Calendar

Workbench supports weekly or fortnightly Xero calendars, not monthly. Make sure all users have a weekly or fortnightly calendar on their employee setup. Otherwise you may receive an error when exporting.

Then each Payroll batch, must include one week in it or two if it is fortnightly.



Workbench searches by default for a Payroll Calendar with the default names that come with the Xero database: Fortnightly Calendar for a Fortnighly pay period and Weekly Calendar for a weekly pay period.

If any custom Pay Calendar is created with different Calendar Name, this Calendar Name must be set on Workbench Working Week table, on the CalendarName column using Scaffold access. Otherwise an error will be returned by Xero: Payroll Calendar 'Fortnightly Calendar' is not found in Xero or Start Date is not defined.

 

2.  Week Ending Dates

The Next Pay Period in Xero must match the week-ending dates for timesheets in Workbench. The start date of a Xero calendar is the start of the first week/fortnight that hasn’t had a pay run.

  • Matching Week Ending Dates: The timesheet week-ending dates in Workbench need to align with Xero’s Next Pay Period week-ending dates, as defined in each Pay Calendar. This alignment is essential for the successful export of timesheets.

  • Troubleshooting Mismatched Dates:

    • If the Next Pay Period in Xero is in the past, make sure to select the right period in the Xero Calendar.

    • If the Next Pay Period is in the future, this may be due to an existing Pay Run in Xero for the week or fortnight you are attempting to export from Workbench.

      • Solution: To adjust the Next Pay Period, check for any Pay Runs in Xero for that period and delete them if necessary. Deleting a Pay Run will cause Xero to automatically shift the Next Pay Period back to the correct week or fortnight. If the Workbench timesheet date is earlier than the Xero calendar start date, then it means that the pay run for the fortnight that the timesheet belongs to has already been completed, so the export fails. In Xero, revert that pay run and do the export again.

      • Alternative Solution: You can create a new Pay Calendar in Xero with the correct dates and assign it to the relevant employees. To avoid confusion, make sure you do not have multiple calendars with the same name, as Workbench may select the incorrect one. To differentiate, consider renaming the old calendar by appending "OLD" to its name.

Note: Xero displays the Next Pay Period as the start and end dates of the period, while Workbench always refers to the week-ending date (the last day of the period).

Example: For the fortnight from 16 December to 29 December:

  • Week 1: 16–22 Dec - Workbench uses WE 22 Dec, while Xero uses 16 Dec.

  • Week 2: 23–29 Dec - Workbench uses WE 29 Dec, while Xero uses 29 Dec.



 

 

3. Employees

As Xero doesn't use an Employee Number, matching of employees between Xero and Workbench is done on the employee's name. 

The Full Name of the employee in Workbench must match the name of the person in Xero.

But because the payroll export is also used with other financial systems, it is necessary for the Employee Number to be populated on employees in Workbench.


4.  Payroll Codes

The Payroll Code in Workbench matches the Earnings in Xero.

In Workbench the Payroll Code is specified on the Time Code, or Activity.

Xero Payroll integration only supports Earning codes and Leave codes

Note: does not support Deductions, Reimbursements types.




Make sure to set the Include in Payroll flag on all activities to be included in the payroll export. Leave Activities and Time Activities can be set with the "Include in Payroll" flag.



  • Pay Items - Earnings:

In Xero the Earnings Rates names are specified in Payroll Settings. 

IMPORTANT Rate Type must be 'Rate per Unit' and Type of Units must be Hours, as Xero only shows to Workbench earning rates with Unit = hours as valid/available earning rates. Otherwise you will get an error when exporting: "Earnings Rate 297b207f-6396-4db1-82c1-79349cdcb2e7 does not exist."

IMPORTANT Make sure there are no duplicate Earnings with the exact same name in the Inactive Earnings section, as this will cause the export to fail. See Xero FAQ section for more details.

                

  • Pay Items - Leave:

In Xero the Leave Name must match the Workbench Payroll Code and must have Units  = Hours.

 

Batching and Exporting

After timesheets have been batched into a Payroll batch, the Payroll Batch Report can be previewed from the Batch Control screen.

Then the batch can be closed and exported in the same way as other Xero exports.

If there are no validation errors:

  • approved timesheets will be created in Xero for the transactions with Earning rates.

  • approved Leave Requests will be created for those transactions using Leave Pay items as Workbench Payroll Codes.

    • One leave request per day.

      



Next Steps:

FAQs:

Filter by label

There are no items with the selected labels at this time.

Process Flow: