Integration with Xero: payments
Payment integration is an optional component of the Case Manager Xero integration and you can choose whether to use it.
Before you run this process for the first time contact Support to set up the technical connections between your Case Manager database and your Xero database. You also need to have the web version enabled and turn on a system setting, see Set up Xero integration for details. You should carefully read through this page before implementation, including the notes at the bottom.
Once payment integration has been set up, you should stop adding payments in Case Manager.
You should also stop journalling payments in Case Manager, see below for details.
As indicated in the diagram below, payment information for Case Manager invoices is entered in Xero.
Each time a payment is added to a Case Manager invoice Xero automatically sends the payment information to Case Manager, where a matching payment transaction is created against the invoice. Case Manager invoices are identified in Xero as any invoice with the "CM-" prefix in its invoice number.
Naturally information about payment changes or deletions against such invoices is also sent to Case Manager.
Thus, in this integration, Xero payments are considered to be the originals and the Case Manager payments are the copies. An invoice payment change in Xero (adding, editing or deleting a payment) is mirrored automatically in Case Manager.
The integration is achieved with Xero's Webhooks technology. It aims to send the payment's details as soon as possible, so you should be able to go immediately to Case Manager and see the matching payment.
Below is a Xero payment and the matching payment in Case Manager.
- The payment date is the same for both.
- The Reference number is optional in Xero.
- The Contact is the invoice contact's company, as detailed in Invoice mapping.
- Inv # has CM- added to the invoice number.
- The invoice's due date is calculated and displayed, see Invoice mapping.
- Xero's Total is the invoice total.
- The payment amount is the same for both.
- In Case Manager the payment is identified as a Xero payment in the Notes: field.
If a value has been entered in Xero it will be displayed in the Reference number field in the Case Manager payment.
- Only Xero invoices prefixed with "CM-" are eligible for synchronisation of payments.
- There are two ways to create payments in Xero: paying an invoice or performing a bank reconciliation. They both have the same outcome from the point of view of Case Manager.
- If you edit a cash payment in Xero and apply it against a Case Manager invoice this is interpreted as a new Xero payment against the invoice and the payment will be sent to Case Manager.
Note that Xero Credit Notes are not considered to be payments and they will not be exported to Case Manager.
When you delete a payment in Xero it is sensible to check that the corresponding Case Manager payment has been deleted.
Payment matching and mirroring
Xero payments are the originals and the Case Manager payments are the copies. An invoice payment change in Xero (adding, editing or deleting a payment) is mirrored automatically in Case Manager.
The first step at Case Manager is to match arriving Xero payments to any existing Case Manager payments. The first time a match is found, a note is made in the Case Manager payment.
The next step is to mirror payment amounts (or to delete payments altogether) so that the Case Manager payment fully mirrors the Xero payment.
There are three situations where full mirroring does not occur:
When you modify or delete a payment in Xero that has been journaled in Case Manager
- When a Case Manager payment was part of a multi-invoice payment in Case Manager
- When a manually entered Case Manager payment does not match any Xero payment in date and amount
The Case Manager payment is undisturbed: neither matched or mirrored.
The Case Manager payment is undisturbed.
Once payment integration is under way you would be very unlikely to encounter these situations.
However, be aware that when you are transitioning from double-entering payments in Case Manager and in Xero to entering payments only in Xero there may be times when they occur.
When you add a part payment in Xero, the invoice's entire collection of part payments is sent to Case Manager for review. Usually you do not need to be concerned about the details, however they may be relevant when transitioning from double-entering your payments.
Case Manager correlates this collection of Xero part payments with its existing invoice payments:
- A Xero part payment matching an existing and previously imported payment (in amount and date) is discarded.
- A Xero part payment matching an existing and manually entered payment (in amount and date) is discarded.
- A Xero part payment that does not match any existing payment (in amount and date) is entered in Case Manager as a new imported payment.
Because the existing payment is updated to note this match, it will be treated as an imported payment in the future.
Note that if the manually entered payment was part of a multi-invoice payment it cannot be updated at all.
- In Case Manager any remaining, previously imported part payments that are not matched are deleted (unless already journaled).
- In Case Manager any remaining manually entered part payments that are not matched are left undisturbed.
The assumption is that they are not matched because they have now been deleted from Xero.
When a payment arrives in Case Manager from Xero with a payment date in the future, Case Manager consults the value of your forward dating system setting:
If the Xero payment date is greater that the specified number of days into the future, the payment will not be added to Case Manager.
If you do need to enter such a payment in Xero you should temporarily disable this setting in Case Manager first.
If Webhooks cannot contact Case Manager for any reason it retries regularly for 24 hours. It then disables the system on the assumption that a server is down. However, any un-sent payment details are not lost. When the system is back up again all the un-sent information is sent over to Case Manager.
For the technically-minded, further information about Xero's Webhooks function is available here.