Xero integration overview

PICMI offers two versions of its Xero integration for payroll: one tailored for New Zealand (NZ) and the other for Australia (AU). To ensure the integration works correctly, your organisation in Xero must match the corresponding region—NZ or AU—based on where your business operates. This is because Xero's payroll systems have region-specific requirements, such as IRD numbers and KiwiSaver details for NZ or Tax File Numbers and superannuation details for AU.

• Payroll NZ
• Payroll AU

note

If your Xero organisation is not set to the correct region, the integration will not function properly.

PICMI currently supports only ONE connected app on an account at a time. Please contact us if you require more than one.

Payroll NZ: Integration configuration

Configuration	Description	Values
Employer subsidy contribution tax rate	Tax rate applied to employer subsidies	NZ tax rates
Employer subsidy	Amount of the employer subsidy	10.5% (MB) for income up to $14,000, 17.5% (M) for $14,001–$48,000, 30% (MH) for $48,001–$70,000, 33% (MT) for $70,001–$180,000, and 39% (MA) for income over $180,000.
Payment method	Method of payment for employees	Bank, Cash, Cheque
Engagement type	Type of engagement with the employee	Permanent, Fixed Term, Casual
Payment frequency	Frequency of payments to employees	Weekly, Fortnightly, Monthly
Earnings rate	Default earnings rate to be applied	EarningsRate from Xero
Pay run calendar	Calendar schedule for pay runs	PayRunCalendar from Xero
Holiday calendar	Calendar used for managing holidays	HolidayCalendar from Xero
Statement particulars	Particulars for bank statements
Statement code	Code for bank statements
Statement reference	Reference for bank statements
Days per week	Number of working days per week for the employee
Hours per day	Number of working hours per day for the employee
Address post code	Default post code used if not provided
Address region	Default region used if not provided

Payroll NZ: PICMI-Xero integration fields

Field Name	Description	Validation/Constraint/Default Value	Source
Employee ID	Unique identifier for the employee	-1 if updating, otherwise uses employee ID	Integration Configuration
First Name	First name of the employee	Maximum 35 characters Mandatory	Personal Information
Last Name	Last name of the employee	Maximum 35 characters Mandatory	Personal Information
Date Of Birth	Employee's date of birth	Must follow the format YYYY-MM-DD Mandatory	Job
Gender	Gender of the employee	Options: M/F	Personal Information
Email	Employee's email address	Mandatory if the account type is not 'Staff' More in troubleshooting sub-alias emails for existing archived users	Job
Phone Number	Employee's phone number	Maximum 15 digits with single spaces, no plus sign (+)	Personal Information
Address	Employee’s home address, including street, city, suburb, and postcode	Mandatory	Personal Information
Engagement Type	Type of engagement for the employee	Permanent, Fixed Term, Casual (Required for employees of organisations created after 5th August 2024)	Integration Configuration
Job Title	Job title of the employee		Job
IRD Number	The employee's IRD (Inland Revenue Department) number		Personal Information
Tax Code	Employee's tax code	Options: M, M SL, ME, ME SL, etc Refer to NZ tax codes	Personal Information
Special Tax Rate Percentage	Special tax rate percentage		Personal Information
Has Special Student Loan Rate	Whether the employee has a special student loan rate		Personal Information
Special Student Loan Rate Percentage	The percentage for the special student loan rate		Personal Information
Is Eligible For KiwiSaver	Employee’s eligibility for KiwiSaver		Job
ESCT Rate Percentage	Employer superannuation contribution tax rate		Job
KiwiSaver Employee Contribution Rate Percentage	Employee’s KiwiSaver contribution percentage	Options: 0%, 3%, 4%, 6%, 8%, 10%	Personal Information
KiwiSaver Employer Contribution Rate Percentage	Employer’s KiwiSaver contribution percentage	Options: 3%, 4%, 5%, 6%, 7%, 8%, 9%, 10%	Integration Configuration
KiwiSaver Opt Out Date	The date the employee opted out of KiwiSaver		Job
KiwiSaver Contribution Holiday End Date	End date of the employee’s KiwiSaver contribution holiday		Job
Has Student Loan Balance	Whether the employee has a remaining student loan balance		Personal Information
Student Loan Balance	The remaining balance of the employee’s student loan as per the letter from IR		Personal Information
Student Loan As At	Date of the letter indicating the student loan balance		Personal Information
Payment Method	Method by which the employee is paid (eg, Cheque, Electronically, Manual)	Options: Cheque, Electronically, Manual	Integration Configuration
Account Name	Name of the employee’s bank account	Maximum 32 characters Mandatory	Personal Information
Account Number	Employee’s bank account number	Digits only, maximum 8 digits Mandatory	Personal Information
Sort Code	Employee’s bank account sort code	Must be exactly 6 digits Mandatory	Personal Information
Start Date	Employment start date	Must follow the format YYYY-MM-DD	Job
End Date	Employment end date	Must follow the format YYYY-MM-DD (defaults to 7 days after if Fixed Term and empty)	Job

Payroll AU: Integration configuration

Configuration	Description	Values
Statement text	The text that will appear on your employee's bank statement when they receive payment
Employment type	Type of employment with the employee	Employee, Contractor
Employment basis	Basis of engagement with the employee for tax purposes	Full-time, part-time, casual, labour hire, non-employee
Address region	Default region used if not provided	ACT, NSW, NT, QLD, SA, TAS, VIC, WA
Earnings Rate	Xero unique identifier for earnings rate	Optional
Pay Run Calendar	Xero unique identifier for payroll calendar for the employee	Optional
Super Fund	Xero identifier for super fund; requires EmployeeNumber	Optional
External Id Generator	Recommended to use the 15 digit generator on the integration (for Super Fund)	Optional

Payroll AU: PICMI-Xero integration fields

Field Name	Description	Validation/Constraint/Default Value	Source
Surname	Last name of the employee	Mandatory	Personal Information
First Name	First name of the employee	Mandatory	Personal Information
Date Of Birth	Employee's date of birth	Optional, preferred format: dd/MM/yyyy	Personal Information
Email	Employee's email address	Must be a valid email format	Personal Information
Phone Number	Employee's phone number	Maximum 13 digits, no dashes or spaces, no '+'	Personal Information
Address	Employee’s home address, including street, city, and postcode	Mandatory	Personal Information
Gender	Gender of the employee	Options: Male/Female/Non-Binary/Not Stated	Personal Information
Job Title	Employee’s job title	Optional	Job
Employment Type	Type of employment for the employee	Optional, Fulltime, Parttime, Casual, Labourhire, etc.	Job
Start Date	Employment start date	Optional, preferred format: YYYY-MM-DD	Job
Bank Account Name	The name of the bank account	Optional, 32 characters maximum	Personal Information
Bank Account BSB	The BSB number of the account	Optional	Personal Information
Bank Account Number	The account number	Optional	Personal Information
Tax Declaration	Employee’s tax declaration	Optional	Personal Information
Earnings Rate	Xero unique identifier for earnings rate	Optional	Configuration
Pay Run Calendar	Xero unique identifier for payroll calendar for employee	Optional	Configuration
Super Fund	Xero identifier for super fund, requires EmployeeNumber	Optional	Configuration

Payroll AU: mapping targets and default sources

The table below explains the main mapping targets used by the Xero Payroll AU integration.

• Mapping target is the field PICMI sends to Xero.
• Xero field is the label used in this guide.
• Mapping source (default) shows the field or workflow question PICMI will try to use automatically when a default mapping exists.
• If the default source says Manual mapping, you should choose the source field yourself.

note

This table reflects the defaults proven in code and tests for the Xero Payroll AU integration. Some fields support automatic matching, but the exact question or source field may depend on your workflow setup. If a field does not map as expected, review the mapping manually.

Mapping target	Xero field	Mapping source (default)
FirstNames	First Name	Worker GivenName
Surname	Surname	Worker FamilyName
Birthdate	Date Of Birth	Workflow question: What is your date of birth?
Email	Email	Worker Email
Phone	Phone Number	Worker Phone
Gender	Gender	Automatic default mapping supported; workflow question What is your gender?; falls back to Not Stated
AddressPostal	Address	Workflow question: What is your postal address?
Title	Job Title	Automatic default mapping supported; falls back to the Job Title when building the Xero employee
StartDate	Start Date	Job StartDate
Remuneration	Remuneration / Pay Rate	Automatic default mapping supported; falls back to the Job Remuneration when available
Bank	Bank Account BSB	Workflow question: BSB number
BankAccount	Bank Account Number	Workflow question: Account number
BankAccountName	Bank Account Name	Workflow question: Your account name
TaxNumber	Tax Declaration / TFN	Workflow question: If yes, enter your TFN
TaxType	Tax Declaration / TFN Type	Workflow question: Do you have a TFN?
TaxResidency	Tax Declaration / Tax Residency	Workflow question: What is your tax residency status?
TaxFree	Tax Declaration / Tax-free threshold	Workflow question: Do you want to claim the tax-free threshold from this payer?
TaxRepayment	Tax Declaration / Study or training loan repayments	Workflow question: Do you have a study or training loan that requires repayments?
SuperContributions	Super Fund selection	Workflow question: Which super fund should we pay your superannuation contributions into?
SuperName	Super Fund name	Workflow question: What is the name of the super fund? (Required for existing or private self-managed funds)
SuperAccount	Super member or account number	Workflow question: What is the member or account number for your Existing Super Fund?
EmployeeId		Manual mapping
Nationality		Manual mapping
VisaStart		Manual mapping

Special Tax File Numbers (TFNs) in Australia

In some situations, special or placeholder TFNs are used when an individual doesn't yet have a regular TFN or qualifies for an exemption. These are commonly used in payroll, superannuation, and ATO reporting.

TFN Code	Description
000 000 000	No TFN provided; not eligible for exemption. Tax must be withheld at max rate.
111 111 111	TFN application is in progress; valid for 28 days only.
333 333 333	Individual is under 18 and earns less than the tax-free threshold.
444 444 444	Individual receives certain government pensions or benefits and is exempt.

Xero does not necessarily accept these values and applications will need to be reissued.

Authorisation

To connect PICMI with Xero, we use OAuth (a simple one-click authorisation). Just make sure you sign in to both Xero and PICMI in your browser to link the two systems.

Read more about OAuth in our integrations guide

Key things to know about Xero's authorisation rules:

• When you first connect PICMI to Xero, Xero gives us a one-time code. This code expires after 5 minutes, so it must be used quickly.
• That one-time code lets PICMI securely request:
  • An access token – this allows us to talk to Xero on your behalf.
  • A refresh token – this allows us to keep that connection going over time.
• The access token only lasts 30 minutes, but don’t worry – PICMI refreshes it automatically in the background.
• The refresh token lasts 60 days, but again, you don’t need to worry – PICMI automatically refreshes it after * 45 days* to keep things running smoothly.
• If the refresh token ever expires, you’ll need to re-authorise PICMI by going through the connection process again.

Troubleshooting

If you notice any discrepancies between PICMI and Xero:

• Re-authorisation: If needed, re-authorise the integration by reconnecting your Xero account.
• Email field with sub-alias: If an employee's job has ended and some time has passed, you can’t create a new user with the same email address. To handle this, PICMI will automatically create the user using a sub-alias email of the original email adding the month and year (eg hone.smith+08-2024@example.com)

note

PICMI will automatically keep your token up to date by refreshing it before it expires (at about the half-way point)

General troubleshooting

• General integration troubleshooting
• Integration FAQs