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.
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.
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.
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.
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:
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 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).
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 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:
Here are 2 ways of handling merchant fees via the Xero API
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).
Here are 2 ways of handling merchant fees via the Xero API
This approach follows the same pattern as the SPEND money approach except in how fees are reflected in Xero.
NOTE: in both scenarios above, the original customer invoice is not altered to reflect the contra (-ve) amount. This is due to 2 reasons:
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
Then on a periodic basis (eg monthly), the payment provider can then either:
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.
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.
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.