/
Payment Gateway Setup For Xero Integration

Payment Gateway Setup For Xero Integration

Overview

This page outlines the way to setup your xero and your payment gateway to ensure smooth transaction flows.

Direct Debit or Credit Card Gateways

Setup

Platform

Action

Information

Platform

Action

Information

Xero

Ensure You have a Clearing Account

Create it as a Bank account (Account Type = Bank, no bank feed connected). Name it after the gateway, e.g. "Payrix Clearing Account" or "IntegraPay Clearing Account". A placeholder BankAccountNumber is required but not meaningful — e.g. PAYRIX-CLEARING.

Pracbill

Add Clearing Account

Use the account from Step 1

⚠️ Important: the clearing account MUST be a Bank-type account in Xero — not a Current Asset.

Xero requires Bank type for overpayment transactions (RECEIVE-OVERPAYMENT bank transactions and AROVERPAYMENTPAYMENT records). Overpayments are a normal occurrence — any time a customer pays more than a single invoice (pays two invoices with one payment, pays the wrong amount, prepays, etc.). If the clearing account is a Current Asset account, those overpayment flows fail silently and leave the ledger in an inconsistent state that is time-consuming to clean up.

⚠️ You cannot convert an existing Current Asset clearing account to Bank.

Xero blocks the conversion with the error "Cannot update Account Type to Bank". If a department already has a Current Asset clearing account in use, the fix is:

  1. Create a new Bank-type clearing account in Xero (different code from the existing one).

  2. Update PracBill's department configuration to point at the new account.

  3. If historical transactions are stuck on the wrong account, contact the PracBill team — a migration is required.

⚠️ Do NOT connect a bank feed to the clearing account.

It's a holding/clearing account only. Connecting a feed creates ghost statement lines that break the settle-to-real-bank flow.

Reconciliation Process

  1. Make Payment in Pracbill

  2. Once payment has been proven successful, that night Pracbill will push the payment to Xero. It will mark the invoice as paid with the transaction against the clearing account.

  3. Reconcile gateway settlement against the clearing account. ( You do not allocate the payments against the invoices there, only “Create” The payment into the Clearing Account ), Below is an example Bank Feed Rule to assist.

  4. Create a ledger entry for any bank fees that have been charged in that process.

Why a Bank-type clearing account (and not a Current Asset)

Xero's official guidance — see their Developer documentation "Handling payment processor receipts" — specifies a Bank-type account for payment-gateway clearing, configured with no bank feed. The reasons are structural to the Xero data model:

  • Overpayments: when a customer pays more than the invoice(s), Xero creates a RECEIVE-OVERPAYMENT bank transaction. The API only allows these on Bank-type accounts. A Current Asset account will reject the create call, and PracBill's push will error.

  • Refunds of overpayments: AROVERPAYMENTPAYMENT records (applying or refunding overpayment credit) similarly require Bank type.

  • Cleanup flexibility: if something goes wrong downstream and records need to be moved or undone, Bank-type accounts support the full range of Xero API operations. Current Asset clearing accounts box you into manual-only cleanup via the Xero UI.

A Current Asset clearing account will appear to work for simple invoice payments, but the first overpayment will break the flow — and those breakages can silently accumulate over months before anyone notices, leading to hundreds of orphaned records that take a manual cleanup project to unwind.

‌