PayFast and Xero: What the Native Integration Covers

PayFast is one of the payment gateways most South African online businesses land on. Xero is where most of those same businesses run their books. PayFast does have a native Xero integration, listed on the Xero App Store, and it's worth knowing exactly what it covers before you build anything on top of it.

This guide explains what the native integration does, what it costs, and the part it doesn't handle: reconciling your PayFast settlement deposits and separating out fees and VAT.

What the native integration does

Once connected, PayFast adds a "Pay Now" link to your Xero invoices. When a customer settles that invoice through the PayFast Pay Now link, PayFast automatically marks the invoice as paid in Xero and matches it to the customer record. It's listed on the Xero App Store, and PayFast documents the mechanics themselves in their support article on how the Xero integration works.

What it costs

There's no setup fee and no monthly fee for the integration itself. You pay PayFast's standard per-transaction fee on payments made through a Pay Now link on a Xero invoice.

Setting it up

The setup steps live in PayFast's own documentation, linked above, along with the listing on the Xero App Store. Both walk through connecting your Xero organisation to your PayFast account.

What it doesn't do

This is the part that matters if you're deciding whether you need anything beyond the native integration.

The native integration settles invoice payments. It does not reconcile the PayFast settlement deposit that lands in your bank account, and it does not split out PayFast's fees or the VAT on those fees. PayFast pays out a net amount after fees, on its own schedule, and that deposit still has to be matched against the gross invoice payments and the fee/VAT breakdown by hand.

Two situations still leave you with manual work:

• Payments that aren't against a Xero invoice. If you're taking payments through a website checkout, a payment link, or anything that doesn't start with a Xero invoice, the native integration has nothing to attach the payment to.
• Settlement reconciliation. Even where invoices are being marked paid automatically, someone still needs to match the PayFast payout in your bank feed against the gross payments it represents, and account for PayFast's fees and VAT separately.

Closing the gap with automation

For either of these, the practical route is PayFast's webhook system: the Instant Transaction Notification (ITN), which fires every time a payment event occurs on your PayFast account. The most practical tool for wiring it up is n8n.

How PayFast ITN webhooks work

When a customer completes a payment through PayFast, PayFast sends an HTTP POST request to a URL you specify. This is the ITN. It fires in the background, regardless of whether the customer lands on your thank-you page.

The ITN payload contains everything you need to create or update a Xero record:

• pf_payment_id: PayFast's unique reference for the transaction
• payment_status: COMPLETE, FAILED, PENDING etc.
• amount_gross: the amount the customer paid
• item_name: the product or description
• email_address: the buyer's email
• custom_str1 through custom_str5: fields you can use to pass your own references (invoice numbers, order IDs, customer codes)
• merchant_payment_id: your own payment reference if you set one

The most important of these is payment_status. You only want to act on COMPLETE transactions, not pending or failed ones.

For payments that aren't against an invoice

If you're selling via a website and Xero isn't involved until after payment, the automation can create a bank transaction, or create the invoice and apply the payment in one step, triggered directly by the ITN rather than waiting on the native integration.

For settlement and fee/VAT reconciliation

This is the automation that pairs with the native integration rather than replacing it: the ITN gives you the gross amount per transaction, and PayFast's payout reports give you the fee deducted per transaction. A workflow can pull both, calculate the VAT portion of the fee, and post the fee and VAT as separate line items against the settlement deposit in Xero, so the deposit that lands in your bank account reconciles to the cent instead of sitting as an unexplained variance.

The workflow structure

Step 1: Receive the webhook

n8n has a Webhook node that creates a URL you can set as your PayFast ITN URL. When PayFast fires the ITN, n8n receives the payload.

Step 2: Validate the payment status

Add an IF node: if payment_status equals COMPLETE, continue. If not, stop or log the event.

Step 3: Validate the PayFast signature

PayFast includes an m_payment_id and a signature hash in the ITN that you should verify before taking any action. This prevents fraudulent requests from outside PayFast hitting your webhook URL. The validation logic is covered in PayFast's documentation and can be handled in an n8n Code node.

Step 4: Create or reconcile the Xero record

Depending on which gap you're closing, either:

• Create a bank transaction or invoice-and-payment for a sale that never went through a Xero invoice
• Post the fee and VAT split against the settlement deposit for reconciliation

Step 5: Handle errors

Add error handling so failed API calls don't silently drop records. n8n can send a Slack or email notification if any step in the workflow fails, so you can investigate and re-run rather than discovering missing records at month-end.

The PayFast bank account in Xero

PayFast holds funds before paying them out to your bank account. This means you'll likely have two accounts to track in Xero: a PayFast clearing account (where incoming payments land) and your actual bank account (where PayFast payouts arrive).

The cleanest approach is to set up a PayFast bank account in Xero and record all incoming customer payments against it. When PayFast pays out to your FNB, Nedbank, or Standard Bank account, you record that as a transfer from the PayFast account to your bank account, with the fee and VAT split out as separate lines. This keeps your reconciliation clean and lets you see exactly what's sitting in PayFast at any point.

What you'll need for the custom layer

• A PayFast merchant account with ITN access (available on standard accounts)
• A Xero account with API access (available on all paid Xero plans)
• n8n: either self-hosted or a cloud instance
• A Xero OAuth 2.0 app configured in the Xero developer portal to generate API credentials

What this looks like in practice

The native integration handles the case it's built for: an invoice, a Pay Now link, a customer who pays it. Where the automation above adds value is the parts that native integration doesn't touch: sales that never start as a Xero invoice, and the settlement deposit sitting in your bank feed with fees and VAT still tangled up inside it.

If you want that reconciliation layer built and kept running rather than assembled yourself, it falls under Xero integration work.