The guide aims to describe how to build an integration to Xero to handle the write back process for general lending. The goal of the write back is to maintain the financial position in Xero for the customer at any point of the lending cycle. This will be achieved by recording the loan liability, the interest and/or fees, repayments, and facilitating the reconciliation of bank accounts.
For the purposes of this guide we will presume a lending provider called ‘Awesome Lender’ is partnering with Xero and building the integration between their product and Xero.
After a customer has connected Awesome Lender to their Xero organisation we need to give them the option for Awesome Lender to flow relevant transactions to Xero so that their financial position is up-to-date and maintained.
The following transactions will need to be automatically posted to Xero (if the customer chooses to):
Prerequisite; a bank account will need to be created by Awesome Lender automatically in Xero to act as a container for transactions related to the Awesome Lender activity. More details below.
For each drawdown post a Bank Transfer between the Awesome Lender bank account in Xero and the nominated ‘real’ bank account in Xero where the loan drawdown will be deposited to.
For each repayment post a Bank Transfer between the nominated ‘real’ bank account in Xero and the Awesome Lender bank account.
Record Interest and/or fees in Xero by posting a ‘spend money’ Bank Transaction to the Awesome Lender bank account with the line item recorded against an expense account. The customer must be able to choose which Expense Account, or get the option to setup a new Expense Account.
Prerequisite; Awesome Lender Bank Account Container
Upon connection to a customers Xero organisation you will need to create a new Bank Account in Xero to act as the container of the Awesome Lender transactions. This can be created by calling the FeedConnections endpoint on the BankFeeds API, which has a dual purpose. Calling this endpoint will create the bank account, and register it to receive statement data from Awesome Lender by returning a FeedConnectionId that can later be used with the Statements endpoint.
To give context to this integration design we will use a running example throughout. The Xero customer has been granted a line of credit from Awesome Lender and wishes to borrow £10k. In the first month the interest charge is £23.66 and the customer will repay £1k.
1. Loan Drawdown
Recording the Drawdown
Once the drawdown has been initiated this will need to be recorded in the Awesome Lender Bank Account in Xero. This can be achieved by creating a Bank Transfer between the recipient bank account and the Awesome Lender bank account. Using our example the £10k advance would be recorded as a bank transfer like this with a -10k in the Awesome Lender Bank Account and +10K in the recipient bank account:
Reconciling the Drawdown
Having created the bank transfer there is now a record in each bank account to be reconciled: 1) Reconciling the Awesome Lender bank account - this can be facilitated by posting a statement line into the bank account. You would simply post a statement line with the same date and amount using the statements endpoint. Doing so would allow the user to reconcile the Awesome Lender bank account:
2) Reconciling the main bank account - this will occur when the bank feed comes through to Xero (note; no action required from you for this, the standard bank feed will run to achieve this):
At this point the advance of £10k has been reflected in the main bank account as a +ve £10k, and in the Awesome Lender bank account as a -ve £10k. The balance of the Awesome Lender bank account reflects the loan liability, i.e. what is owed to Awesome Lender.
Recording a payment is done in the same way as the initial advance. This can be achieved by simply creating a BankTransfer between the recipient bank account and the Awesome Lender bank account. Using our example a repayment of £1k would be recorded as a bank transfer like this with a +1k in the Awesome Lender Bank Account and +-1K in the recipient bank account:
Recording the Fee
Interest can be recorded in Xero by posting a ‘spend money’ BankTransaction in the Awesome Lender bank account. This is much like an invoice and has some mandatory fields, an important one to call out is account code. This is the Chart of Account code the interest should be booked to and is a choice the customer will need to make, usually in a setting area on your side. See our Integration Best Practices for tips on how to capture this choice from the customer. The spend money transaction would look like this:
Reconciling the Repayment and Fee
To finish off, there are now two things that need to be reconciled; the repayment, which exists in both the Awesome Lender bank account, and the main bank account, and the fee, which exists only in Awesome Lender bank account.
Reconciling the Awesome Lender can be achieved by posting two statement lines into the bank account. You would simply post a statement line with the same date and amount for each of the outstanding transaction using the statements endpoint, one for the repayment, and one for the fee. Doing so would allow the user to reconcile the Awesome Lender bank account:
Lastly, reconciling the main bank account - this will occur when the bank feed comes through to Xero (note; no action required from you for this, the standard bank feed will run to achieve this):
At the end of all this; the loan liability has reduced to 9023.66, the fee of £23.66 has been recorded as an expense, and the main bank account is reconciled.
The process would be repeated until each repayment reduces the balance of the Awesome Lender bank account to £0, i.e. the loan is repaid. For lending solutions that offer flexible drawdowns and repayments this process can be used for all activity, essentially the Awesome Lender bank account would act as both a statement of activity and a current representation of the loan balance.
The customer will need an area in your product/portal where they can:
For 1 - This could be a simple checkbox that if deselected deactivates all the options on the page. You would need to clearly explain to the customer what this option entails, i.e. you’ll be recording the loan liability, fee and marking the nominated invoice(s) as paid. Ideally you would link to a guide or video that explained how things will be recorded in Xero.
For 2- You can call the Accounts endpoint in our API and GET a list of Bank Accounts. This would be where Type=BANK.
For 3 - You can call the Accounts endpoint in our API and GET a list of Expense Accounts. This would be where Class=EXPENSE.
For 2 and 3 - Note that SystemAccounts must be excluded. The easiest way to do this is to filter them out on your side, if any of the returned accounts have a value in the SystemAccounts field exclude them from the drop down.
For 4- There are two options for helping the user create a new account. Either provide them a deep link to the Chart of Accounts area in Xero, and a refresh button on your side to re-populate the dropdowns after they’ve created the new account in Xero. Or, create the account for them in Xero via the API. This would involve asking the user for an account code and name to use. See our Integration Best Practices for more detail.