---
title: Setting up Xero integration
description: "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. ``` White-label domainIf…"
url: "https://paiyroll.com/kb/setting-up-xero-integration/"
updated: "2026-03-05"
category: Integrations
---

# Setting up Xero integration

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.

```
White-label domainIf you access paiyroll® using a white-label custom domain, e.g. acme.paiyroll.com, please ensure you first log in with our standard URL login.paiyroll.com for the instructions below
```

## 1. Add Report Definition

After logging in, from the Home screen:

- **Setup** > **Report Definitions**
- Scroll down to the bottom and click **+Add…**

![](https://paiyroll.com/wp-content/uploads/2024/04/image-63-1024x485.png)

On the **Create Report definition** view:

- Select the **Company**
- Select the **Template** for **GB Xero Journal** (scroll all the way to the top in the section **GB - Accounting**)
- Scroll down to the bottom and click **Add**

![](https://paiyroll.com/wp-content/uploads/2024/06/image-6-1024x306.png)

The Xero Report Definition has now been added.

## 2. Grant

After adding the Report definition, the 2nd step requires you to **Update** it and Grant Access.

- You would normally be on the **Report definitions**view**,** if not, then **Setup** > **Report Definitions**
- On the **GB Xero journal**row, click **Update**
- Click **Grant...**

![](https://paiyroll.com/wp-content/uploads/2024/06/image-7-1024x111.png)

Next, you will need to log into Xero:

![](https://paiyroll.com/wp-content/uploads/2024/04/log_in_xero.png)

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**

![](https://paiyroll.com/wp-content/uploads/2024/04/wants_access.png)

### 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:

![](https://paiyroll.com/wp-content/uploads/2024/06/image-1-1024x79.png)

### 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. A default mapping is already available to get you started; in many cases, you may be able to use this without modification, and this step will not be required.

In other cases, depending on how your Xero accounts have been configured, you may need to change or configure the Journal mapping to map between Xero and paiyroll® as described in this section.

- You would normally be on the View Report definitions, if not, then**Setup** > **Report Definitions**
- Click **Update**

Your account codes and account names will be downloaded from your bookkeeping system. To configure each journal's Debit and Credit line:

1. Select the relevant Pay frequency tab – for example, **m1** (monthly) below
2. Notice there are 2 different **Add** buttons at the bottom of the **Debit **and **Credit** accounts.
3. 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).
   - Select the **Narrative**. The **Narrative** includes all Pay Definitions and all Busses. You may wish to select a single Pay Definition, but at other times, it will be more convenient to select a Buss that includes all Pay Definitions connected to that Buss. (In our example below, 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 negative and some positive. In this case, click **Negate**:

![](https://paiyroll.com/wp-content/uploads/2024/05/image-36-1024x737.png)

After configuring the journal mapping, click **Update** to save the changed configuration.

### Delete Unused schedules

You should delete any unused schedules by selecting the schedule and clicking delete:

![](https://paiyroll.com/wp-content/uploads/2024/06/image-11-1024x724.png)

## 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:

- **Pay runs** (left main menu)
- 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, no errors will be displayed.

To see the actual data that will be posted as a journal,

- **Pay runs**
- Click **View** on the Pay run to see the pay run view
- Select the **Reports** tab
- Click **View** on the **GB Xero Journal**
- The Balance, debits, credits and line items will all be displayed:

![](https://paiyroll.com/wp-content/uploads/2024/04/image-60-990x1024.png)

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, you must identify the cause and reconfigure the journal mapping using the above steps. See this section on [journals](https://paiyroll.com/kb-category/journals/).

## Payrun Approval - Posting to Xero

The payroll journal will not be posted to Xero until the Pay run is approved.

When you have completed all payrun pre-approval checks and you are certain everything is correct, follow the usual steps to approve the pay run:

- Pay runs > **Approve**
- **Yes**: Approve as final (no updates were made after previous pay run)
- Tick **Confirm**
- Click **Done**

After a short while, the next Pay run will start.

Your journal has been automatically posted to Xero! This will be visible in Xero and the approved pay run.

## Revoking Access

You can revoke access at any time from paiyroll®:

- **Setup** > **Report Definitions**
- Update the **GB Xero Journal**
- 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 updates will not work. Continue by clicking the **Home** icon or your browser back button

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:

![](https://paiyroll.com/wp-content/uploads/2024/07/image-1024x808.png)

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
```

![](https://paiyroll.com/wp-content/uploads/2024/06/image-26-1024x158.png)
