Description
This document outlines the procedure for setting up billing integration between Converge and an MSP's HaloPSA instance. The results of the billing integration in place is to synchronise your customers' billing data from our most recent invoice into licensing updated within your HaloPSA.
This process can occur either on demand, or scheduled to run automatically at the end of our invoicing run.
The Process
Purpose: This document describes how the system synchronizes billing between Converge and HaloPSA to maintain accuracy and consistency in billing while removing friction re-work for our partners.
1. Establish a connection between HaloPSA and Converge
1.1 Authorisation
In order to allow Converge to access the Halo API, you must first allow the application access to it. This is done by registering the application in the Halo API settings in the Halo Web Application.
In the web application, whilst logged in as a Halo administrator, go to Configuration > Integrations > Halo API.
The following page shows you the setting required for the Halo API.
Here you will be able to choose “Application” button to redirect the all applications page.
The following page will show all applications that you have allowed to access the Halo API. Select the "+ New" button to add to this list.
Here, you will have the opportunity to select the Authentication method that you wish to utilize for your application. These methods align with the flows provided in OAuth.
Additional settings will become accessible depending on your selection. All methods require a Client ID, which will be provided to you. When using Converge, please select 'Authorisation Code', and ensure that you complete all required
information:
· Application Name: converge
· Login Redirects URLs: https://converge.mp/accounts/
Please remember to copy the Client ID to your clipboard for the subsequent step.
Finally, click on the 'Save' button to preserve all your initial settings in HaloPSA.
1.2 Connecting Converge
Access Converge https://converge.mp/accounts/
After configuring the Converge application on HaloPSA, you may now return to the Converge portal and connect it using the login form. Please follow the setup instructions below:
In Converge, navigate to the Accounts tab > Halo PSA.
The following page enables you to verify whether your Converge account is connected to Halo. If it is not connected, please complete all necessary information to initiate the connection from Converge to Halo.
· Tenant: this refers to the name of your tenant that you select when establishing your account on Halo. You can observe it in the browser URLs when accessing your Halo account.
· Client ID: This is the client ID that you were included on in the previous step when you set up an application on Halo.
Subsequently, click on the "Connect" button. If your application is valid, you will be shown a Halo logon screen.
Please log in using your Halo account (if you have logged in previously, the application will automatically connect without displaying the login form).
If successful, you will observe that the HaloPSA page on Converge is reloaded, and a new tab labeled "Report" will become visible.
2. Loading the data
Upon establishing the connection as described in step 1 above, Converge will automatically retrieve invoice data from the server corresponding to the current month. This data collection occurs after the successful completion of the 'Invoice Run' process—usually around the 5th of each month, or on the following business day if the 5th coincides with a weekend or holiday.
Additionally, you can view both the total number of successful synchronisations and the total number of failures; this reflects the count of data that has been successfully synced to HaloPSA or not.
Please be advised that you will have the ability to view the data, but you will not be permitted to make any modifications.
When you are prepared, you may click the "Sync" button to transmit the data to you HaloPSA instance.
3. Push invoice to HaloPSA
The sync progress will be shown on the screen. The “Sync” button will remain disabled until the process is complete (or fail).
Once the processing is finished, you will observe that the status of the data has changed and the counter has been updated.
4. Mapping Customer/License
4.1. Setup Customers
Click the Customers tab in the options above the customer details.
Here you can select which Converge customers are to be linked to the relevant HaloPSA customer.
Each Converge customer can only be connected to one HaloPSA customer.
4.2. Setup Product/License
Click the License tab in the options above the customer details.
Here you can select which Converge products are to be linked to the relevant HaloPSA license.
○ 3. HaloPSA Integration rules and actions for synchronisation
■ Step 1 – Confirm Customers Exist in HaloPSA:
● Fetch the complete list of customers (clients) from Halo PSA for the partner.
● Try to match each customer in our system to a customer in Halo by customer name.
● If a customer cannot be found in Halo, all their products are skipped and not synchronised.
■ Step 2 – Determine Product Actions
● Fetch the complete list of software licenses from Halo PSA for the partner.
● For each product in our records:
○ Check if it already exists in Halo:
■ Look for a software license record in Halo where: The license belongs to the matched customer and the license name matches the product code.
○ Determine what to do based on quantity:
■ If no matching license exists:
● If the product quantity is greater than zero → Create a new license in Halo.
● If the product quantity is zero → Skip (no action).
● If a matching license does exist:
● If the quantity is greater than zero → Update the existing license to reflect the current data.
● If the quantity is zero → Delete the license in Halo.
○ Data to synchronise for each license: Product code, Quantity, Price, Billing cycle.
■ Step 3 – Clean Up Old Records
● Any software license in HaloPSA that belongs to the current customer, and does not have a corresponding product in our system will be deleted to keep the data consistent.
○ 4. Synchronisation:
● The system securely connects to the Halo PSA API using the partner’s credentials.
● Each create, update, or delete action is sent to Halo.
● If Halo responds with a temporary error (such as too many requests), the system waits and retries automatically.
● If credentials are invalid, the system refreshes them before retrying.
Error Handling and Logging:
● Critical Failures:
■ If the system cannot fetch customers or licenses from Halo, the entire process stops and is marked as failed.
■ An error message is logged for review.
■ Due to the limitation of the HaloPSA, which allows a maximum of 500 requests every 5 minutes, there are occasions when Converge is unable to transmit data to them, resulting in a synchronization failure. Once the processing is complete, you may initiate the process again by clicking the "Sync" button.