Where the difference actually comes from

Every finance team that sells online eventually meets the same discrepancy. The sales ledger says the customer paid £120.00. The bank statement says £116.42 arrived, three days later, bundled with nineteen other orders and two refunds. The gap is the provider's fee, and someone is currently closing it by hand. A payment fees Xero integration is the piece of work that removes that manual step, and it is worth being precise about what it has to do before anyone writes code.

The mismatch is structural, not accidental. Card acquirers and wallets deduct their charges before settlement, so the payout is a net figure covering a batch of transactions over a settlement window. Xero, meanwhile, is a gross accounting system: the invoice or receipt records the full amount the customer was charged, and the fee is a separate cost of sale. Nothing in either system is wrong. The two simply describe different moments in the money's journey.

There are usually three timing layers at once. The order is captured on day one in Shopify or WooCommerce. The provider closes the batch at a fixed cut-off and initiates a payout on day two. The funds land in the bank on day three or four, and at month end some of that money is still in transit. If the integration only posts orders and lets the bank feed take care of the rest, that in-transit balance has nowhere to sit and reconciliation becomes an exercise in memory.

The other complication is that fees are not a single number. A typical settlement contains per-transaction percentage and fixed charges, refund handling costs, chargeback fees and reversals, currency conversion margins, and — separately, often as a monthly invoice — platform or gateway subscription charges. Treating all of these as one lump sum posted to a generic expense code destroys the ability to answer the question that prompted the project in the first place: what is this actually costing us per channel.

What a payment fees Xero integration must produce

The design target is simple to state and useful to hold everyone to during scoping: every payout that appears on the bank statement should match a single record in Xero to the penny, without a human adjusting anything. If that test passes, the ledger is right and the fee analysis follows from it.

In practice that means the integration is responsible for four postings rather than one, and each has a distinct trigger.

The ordering matters. Fee postings must not run ahead of the sales postings they relate to, or the clearing account will show credits against transactions that do not yet exist and anyone looking at it mid-run will reasonably conclude something is broken.

  • Gross sale into the clearing account — When an order is paid in Shopify or WooCommerce, the sales invoice or receipt is created in Xero at gross value, with the payment allocated to a merchant clearing account rather than the real bank account.
  • Fee deduction out of the clearing account — The provider's charge for that transaction, or for the batch, is posted as a spend transaction from the clearing account to a merchant fee expense code. This is the line that finance actually wants to analyse.
  • Payout as a transfer — The net settlement is recorded as a movement from the clearing account to the bank account, dated on the provider's payout date, so the bank feed has an exact counterpart to match against.
  • Adjustments and reversals — Refunds, chargebacks, reserve movements and negative settlements post to the clearing account with the same discipline, so the balance remains a true representation of money held by the provider.

Designing the clearing account so it proves itself

Set up one clearing account per provider and, where the provider settles separately by currency, one per currency. Mixing Stripe, PayPal and a Klarna-style deferred payment method in a single account removes the only diagnostic that matters: a clearing balance that should trend to a small, explainable figure. If the account is provider-specific, the balance at any moment equals transactions captured but not yet settled, plus any reserve the provider is holding. That is a number an operations manager can check against the provider's own dashboard in under a minute.

Create the clearing account in Xero as a bank account type rather than a current asset code. This is not cosmetic. Bank-type accounts allow bank transfers, receive-money and spend-money transactions, and give reconciliation tooling something to work with. The real bank account then reconciles against transfers only, which is what the statement line genuinely represents.

Post fees at the granularity the provider gives you. If the settlement report carries a fee per transaction, store it against the order reference, then post the aggregate for the batch with the detail available in the integration's own audit records. Posting several hundred individual spend transactions per day will make the ledger unusable and will consume Xero's API allowance for no benefit. A single fee transaction per payout, referencing the payout identifier, is almost always the right level. Keep the per-transaction breakdown in the integration database, where it can be queried when a channel margin question arises.

Whatever the granularity, every posting needs a deterministic reference derived from the provider's own identifiers — payout ID, balance transaction ID, order ID — so that a re-run produces a match rather than a duplicate. Xero will happily accept the same manual journal twice, and a reconciliation process that cannot survive being run again is not finished.

VAT, fee codes and the treatment that survives an inspection

Payment processing charges from UK and EU providers are generally treated as exempt financial services rather than standard-rated supplies, so the default tax rate on the fee expense code should reflect that rather than reclaiming VAT that was never charged. The qualification is important: the same provider may also bill for fraud tooling, invoicing modules or subscription software, and those elements may be standard rated or fall under the reverse charge where the supplier is established outside the UK. The safe rule during discovery is to read the provider's actual invoices for the last three months and map each charge type explicitly, rather than applying one tax rate across everything the provider deducts.

Use a dedicated merchant fee code, separate from ordinary bank charges. Bank charges are a general overhead; merchant fees vary directly with revenue and belong with cost of sales for anyone doing contribution analysis. If the business sells through several channels, add a tracking category for channel and populate it on the fee transaction as well as the sales transaction — otherwise the fee sits in a single undifferentiated total and the channel margin report is only half built.

Foreign currency deserves an explicit decision rather than a default. Where a provider collects in euros or dollars and settles in sterling, there are two separate items: the conversion itself, and the margin the provider takes for performing it. Recording the payout at the sterling amount received against a foreign-currency clearing account will leave a realised exchange difference, which is correct and should be posted to a gains or losses code. Recording it at the provider's quoted rate and ignoring the difference will leave a residue in the clearing account that grows quietly for months.

The edge cases that decide whether it holds in production

Refunds are the first test. A refund of a full order usually returns the customer's money but not always the original processing fee, and may add a refund handling charge. The integration must post the credit note against the sale, the money out of the clearing account, and any additional fee separately. If the sale and the refund fall in different settlement periods, the clearing account handles the timing without intervention — which is the whole point of the design.

Chargebacks behave differently again. The provider deducts the disputed amount and a dispute fee, then may return the amount weeks later if the case is won. Both movements are clearing account transactions tied to the dispute identifier, and the reversal must be recognisable as the same case rather than appearing as unexplained income. Negative payouts, where deductions exceed takings for a quiet period, need handling too: the provider debits the bank account, and the transfer runs in the opposite direction.

Reserves and rolling holds are common for newer merchant accounts and for sectors the acquirer considers higher risk. Money withheld is still the business's money and belongs in the clearing account balance, not written off. Where the provider reports reserve movements as distinct balance transactions, post them; where it does not, expect a persistent clearing balance and document why it exists so that the next person to review the account does not chase it.

Finally, plan for the reporting lag. Settlement detail is often available only after the payout has been initiated, and occasionally a day later. An integration that posts the transfer on payout date but fetches fee detail on a separate schedule will produce brief periods where the clearing account is out by the fee amount. That is acceptable if it is understood; it is not acceptable if the month-end close runs during one of those windows. Set the reconciliation job to complete for a period before the period is closed, and give finance a simple report showing clearing balance by provider with the expected in-transit figure alongside it.

Scoping the work so the acceptance test is unambiguous

Discovery for this kind of build is mostly document gathering rather than architecture. Obtain three months of settlement reports, the corresponding bank statements, the provider's fee schedule, and the existing chart of accounts. Identify every distinct charge type that appears, including the ones that occur once a quarter. Agree the clearing account structure, the fee codes, the tax treatment per charge type and the tracking dimensions in writing before anything is built, because these are the decisions that are expensive to change once six months of postings exist.

The acceptance test should be a replay, not a demonstration. Run the integration against a historic month in a Xero demo organisation and compare the resulting clearing account movements against the real bank statement line by line. Every payout should match to the penny; the closing clearing balance should equal the provider's reported in-transit and reserve figures. Any residue is a mapping gap, and it is far cheaper to find it in a replay than in a live close.

Two operational safeguards belong in scope. First, an alert when the clearing balance exceeds an agreed threshold or ages beyond the provider's normal settlement window, since that is the earliest signal of a missed payout or a changed report format. Second, a documented manual procedure for the day the provider introduces a new charge type — the integration should route unrecognised fee categories to a holding code and flag them rather than guessing. On handover, the mapping table, the fee code decisions and the reconciliation report belong with the code, so that the finance team can maintain the arrangement without needing the original developer on the telephone.

Key points

  • Use a separate clearing account per payment provider, created as a bank-type account in Xero, so the balance always equals funds captured but not yet settled plus any reserve.
  • Post four distinct records — gross sale, fee deduction, net payout transfer and adjustments — each keyed on the provider's own identifiers so re-runs match rather than duplicate.
  • Map every charge type to a fee code and tax treatment during discovery, and accept the build only when a replayed historic month reconciles to the bank statement to the penny.