Follow the 3 steps in this guide to set up a fully configured integration that will post journals automatically upon pay-run approval.
If you only need to refresh an existing report definition Token, start at step 2.
1. Add Report Definition #
- Company setup > Report Definitions.
- Scroll down to the bottom and click Add…
- Select the Company
- Select the Template for GB Xero Journal (at the top in the section GB – Accounting)
- Scroll down to the bottom and click Add
2. Grant #
After adding the Report definition, the 2nd step requires you to Update it and Grant Access
- You would normally be on the View Report definitions, if not then Company Setup > Report Definitions
- On the GB Xero journal row Click Update
- Click Grant…
Next, you will need to log into Xero:
You will likely be asked to authenticate your login via your phone.
Select the organisation in Xero you wish to allow access to and then click Allow access
Set Organisation #
If you are a bureau and have multiple companies, you must set the Organisation in paiyroll® to match the Xero organisation.
A single-company employer will use the default:
Update #
We recommend clicking Update to save the Report definition at this stage.
3. Configure the Journal Mapping #
After Granting the Report definition, you can proceed to the 3d step and Configure the Journal.
- You would normally be on the View Report definitions, if not then Company Setup > Report Definitions
- Click Update
Your account codes and account names will be downloaded from your bookkeeping system. A default mapping is already to get you started. Depending upon your Xero accounts, you may need to change or configure the Journal mapping. To configure each journal Debit and Credit line:
- Select the relevant Pay frequency tab – for example m1 (monthly) below
- Notice there are 2 different Add buttons at the bottom of the Debit accountd and the Credit accounts.
- Add a new journal row entry in either Credits or Debits using the row along the Add button:
- Select the Account (e.g. 900 -Deductions). If the account does not exist, you will need to type it in first in the Account section. In our example here we have added “; 900 – Deductions“)- note the semicolon “;” separator
- Select the Narrative. The Narrative includes all Pay Definitions and also all busses – you may wish to select a single Pay Definition but at other times, it will be more convenient to select a Buss which includes all Pay Definitions connected to that Buss. (In our example we select DWP DEA.
- Click Add.
- Sometimes it will be necessary to switch plus values to minus and vice-versa by ticking the Negate box as some values are held as negative and some positive. In this case, click Negate
When you have configured the journal mapping, click Update.
Delete Unused schedules #
You should delete any unused schedules by selecting the schedule and clicking delete:
Verify the journal operation #
Once you have set up the Xero integration, you should verify that everything is working correctly with an interim pay run:
- Go to Pay runs
- Pay run Redo and wait a few seconds until the Approve button changes from Wait
If everything is correct, and the journal balances meaning it can be posted successfully, there will be no errors displayed.
To see the actual data that will be posted as a journal,
- Click View on the Pay run to see the pay run view
- Select the Reports tab
- Click View on the GB Xero Jounral
- The Balance, debits, credits and line items will al be displayed:
Each time you do a pay run redo, all the Xero journal items will be recomputed and available for you to see.
If there is an error, now or in the future, and the journal does not balance and you will need to identify the cause and reconfigure the journal mapping using the above steps. See this section on journals.
Revoking Access #
You can revoke access at any time from paiyroll®:
- Company setup > Report Definitions
- Click on the Revoke button
- After you have revoked Access, the Revoke button will be greyed out. This will confirm that the connection is no longer active.
- Once you have Revoked access, the report will be inactive and Update will not work. Simply continue by clicking the Home icon
You can also revoke access from Xero:
- Company > Settings
- Connected apps
- Click Disconnect
Troubleshooting #
Missing Accounts #
If you find the specific account has not been downloaded, this may be due to not being configured correctly in the bookkeeping app. We recommend you correct this in your bookkeeping application and configure the account as a credit or debit and re-grant.
How to add a new Xero Credit account #
Below is how to add a new account code 5310 – ensure you select Current Liability Account Type:
Alternatively, you can type the account in manually (but if you do a re-grant you will lose it next time). If you need to expand the window to see and edit the accounts, click and drag down the control in the corner to resize the accounts window. The example below shows where to resize and how a new account has been entered (noting the separating semicolons).
; 4445 - Others debtors