Fees and the Xero API


Introduction

Fees (including merchant fees charged by card providers) are something Xero users need to be able to take into account when managing their Xero solution. In this document, we describe common fees that might apply and how an app partner might account for these when integrating with Xero via the Xero Accounting API.

Disclaimer
The following are examples of how a developer might handle fees and is intended to be customised to your specific workflows and integration points with Xero. The discussion on fees below is only about fees for sales to customers, not for suppliers.


The Basics - what is a fee?

A fee is a business expense (or contra-income) that is incurred during a sale and decreases the business’ profit. Remember, profit = sale price - cost of goods - expenses (including overheads).

Fees generally are handled in one of the following ways.

  • Fees are on-charged to customers - eg shipping and handling fees. These may be on-charged at cost or with a margin.
  • Fees are consumed by the business - eg settlement discounts, shipping and handling fees.

Merchant fees are a common part of a sales transaction. These fees are levied by a 3rd party payment provider and depending on the agreement with the business owner; these may be added to the invoice amount OR paid by the business. Merchant fees illustrate the business owner has options; for example, shipping and handling fees may be charged to the customer if the amount is less than a certain order value or maybe consumed by the business owner if the invoice is above a certain amount. Fees incurred can be attributed to an individual sale (eg postage per sale) or considered a general expense and taken into account as part of the running of a business. Let’s dive deeper into ways to handle merchant fees.

Xero and Merchant Fees

Merchant Fees Paid by Customer.

Where the customer paying a Xero invoice has merchant fees added to the invoice amount, these fees are not required to be accounted for by the Xero org unless the Xero org incurs some expense directly related to the transaction (not common).

For instance, where the fees are 30c per transaction plus 1.5% of the total value, the Xero invoice for $1000 will result in the following:

  • Customer paying the invoice will pay $1000 + 0.30 + $15 = $1015.30
  • Payment Service will keep $15.30.
  • $1000 will be deposited into the Xero organisations bank account for payment of $1000 invoice - reconciliation should be simple based on invoice amount.
  • The customer receives a Xero invoice for $1000 but pays $1015.30. The customer (not the Xero org) will need to add a journal or raise and expense for merchant fees for $15.30.

Note: there are no fees that need to be accounted for by the Xero org in this example. There is complexity around the reconciliation of multiple invoices paid by customers that need to be deposited into the Xero organisations bank account but this is a manual process performed by an accounting partner with knowledge on how to do this in Xero.

Merchant Fees Paid by Customer and the Xero API.

Merchant fees levied by a payment provider on top of the invoice amount do not require any additional API calls as the fees are not treated as income by the Xero customer, and the payment provider remits the entire invoice amount. Settlement to the business owner’s bank account typically occurs within one week (depending on the commercial terms with the payment provider).

Merchant Fees Paid by Xero Organisation.

If the payment service charges the business owner the merchant fees, it is important to determine when the expense is paid - this may occur at:

  • Real time processing with invoice.
    This results in fees being deducted from the amount deposited in the business owner’s bank account.
  • Periodic processing as accounts payable.
    This could be a monthly bill from the payment provider delivered on a periodic basis. The amount deposited in the business owner’s bank account would match the amount of the invoice, so reconciliation is greatly simplified. The business owner reconciles invoice payments and a bill for fees independently of each other.
Merchant fees levied at the time of processing an invoice.

Real time processing of fees with invoice has the payment provider taking their fee out of the amount to be paid. Continuing with our example, a $1000 invoice paid by the customer will result in:

  • Customer pays $1000.
  • Payment Service will keep $15.30.
  • $984.70 ($1000 less $15.30) deposited into the business owner’s bank account for a $1000 invoice. Due to the amount deposited not matching the amount of the invoice, this raises reconciliation complexity - this can be managed by adding a merchant fee transaction for $15.30.
  • Customer receives a Xero invoice for $1000 and pays $1000.00 which will be reconciled against the payment as part of normal bank reconciliation.

Here are 2 ways of handling merchant fees via the Xero API

  • Use a SPEND money bank transaction to the same bank account where deposits from the payment provider are made.
  • Use an accounts payable invoice with the payment processor as the contact.
Account Mapping.

In order to apply a payment against an invoice via the API, the small business owner must select which bank account in Xero they receive funds from their payment processor. Additionally, you’ll want to correctly categorize any fees. We recommend providing a mapping interface to the business owner to map fees to the appropriate expense account code in Xero. You can retrieve a chart of accounts via Xero’s API. This same configuration screen can be used to select the bank account where payments are deposited (you’ll use this for spend money bank transactions).

Spend money approach

Here are 2 ways of handling merchant fees via the Xero API

  • Customer makes a $1,000 payment via payment provider.
  • Payment provider applies a payment by calling PUT on the Payments endpoint for the $1000 invoice. Because the amount outstanding on the invoice was $1000, the invoice is marked with a Status of PAID
  • Payment provider makes an additional PUT call to BankTransaction endpoint for a SPEND Money of $15.30. The line item detail on the bank transaction should specify the mapped account code for the fee (expense, overhead, etc).
  • The deposit from the payment provider results in an inflow of $984.70, which will be matched to the $1000 invoice minus teh SPEND money transaction of $15.30.
Accounts payable approach.

This approach follows the same pattern as the SPEND money approach except in how fees are reflected in Xero.

  • Customer makes a $1,000 payment via payment provider.
  • Payment provider applies a payment by calling PUT on the Payments endpoint for the $1000 invoice. Because the amount outstanding on the invoice was $1000, the invoice is marked with a Status of PAID
  • Payment provider creates accounts payable invoice.
    • Perform a GET on contact to see if they exist as a supplier in Xero and if not, create a new contact.
    • Make a PUT call to create a supplier Invoice (ACCPAY) with a Status of AUTHORISED with a line item of $15.30 and mapped account code.
    • Make a PUT call to apply a payment on the newly created supplier invoice.

NOTE: in both scenarios above, the original customer invoice is not altered to reflect the contra (-ve) amount. This is due to 2 reasons:

  1. The customer paid $1000 and therefore may need to claim the entire amount for taxation purposes.
  2. The alteration of an invoice after it is paid is not allowed in some taxation juridictions.

Merchant Fees Levied on a Periodic Basis and the Xero API.

Merchant Fees accumulated and sent on a periodic basis, the payment service provider at time of processing the Customer Invoice will do the following:

Customer makes payment via payment service for $1000

  • Customer makes a $1,000 payment via payment provider.
  • Payment provider applies a payment by calling PUT on the Payments endpoint for the $1000 invoice. Because the amount outstanding on the invoice was $1000, the invoice is marked with a Status of PAID.
  • Payment service will track fees to the business owner.

Then on a periodic basis (eg monthly), the payment provider can then either:

  1. Create a SPEND money transaction via a PUT call to BankTransaction the Xero API for fees in that period from; OR
  2. Create a supplier Invoice (ACCPAY) with a Status of AUTHORISED for the fees for that period.

Business owner wants to charge a customer surcharge fee

Sometimes, a business owner may want to charge their customers a surcharge fee to cover costs. It is a fee that the payment service does not keep, it goes to the business owner. It is up to the payment service’s discretion as to whether to offer this type of fee. The business owner would configure the surcharge amount in the payment service, this could be configured in a variety of ways e.g. flat fee, a percentage or a flat fee + percentage.

If a customer chooses to use the payment service to pay an invoice, the payment service should POST a line item to the existing invoice the customer is paying. Note: do not add a new invoice for this process. The line item should be for the surcharge amount, the POST should be done before the payment is processed. Invoices that are paid or partially paid cannot be edited.

The payment service will need to make it obvious to the customer that the surcharge is being added to the invoice and they will be paying an updated amount.

They payment service would then proceed with the rest of the payment processing.

Uncompleted payments

Please keep in mind that if a customer was to start the payment process but not complete it, the additional line item would still exist on the invoice. That is why it is important to have good messaging in the payment process so the customer understands the extra charge.

Compliance

Each country has different requirements that you must comply with. For example, in Australia, once an Invoice has been delivered for product, it cannot be altered so the suggested workflow for a business owner charging a surcharge to a customer would not be acceptable in that region. It is your responsibility as an app to ensure you are compliant with the relevant laws for the regions in which you operate.