> For the complete documentation index, see [llms.txt](https://help.alternativepayments.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.alternativepayments.io/integrations/psa-integration-guides/halopsa/halopsa-integration-set-up-guide.md).

# HaloPSA Integration Set-Up Guide

**Your step-by-step guide to integrating HaloPSA successfully.**

***

### How to Set up your HaloPSA Integration

Connecting HaloPSA with Alternative Payments is quick and seamless, allowing you to maintain your existing workflows while enhancing payment flexibility for your customers. Follow these steps to get started:

{% hint style="warning" %}
**Native QBO sync conflict:** If your HaloPSA instance has the native QuickBooks Online invoice sync enabled, you must disable it before connecting to Alternative Payments. Running both syncs simultaneously can cause duplicate or conflicting invoice data.
{% endhint %}

#### **1. Navigate to Configuration > Integrations > HaloPSA API.**

On your HaloPSA home screen, follow the below path:

1. Configuration
2. Integrations
3. HaloPSA API

**2. Create a new application. You can name it “Alternative”.**

Click “View Applications” and create a new application in the top right corner of the screen

<figure><img src="/files/WtdVdps3kWrzQPhXNjIU" alt=""><figcaption></figcaption></figure>

Name the Application “Alternative”

#### **3. Choose “Client ID and Secret (Services)” as the authentication method.**

<figure><img src="/files/gTwBQidnLOV6o9BDibmv" alt=""><figcaption></figcaption></figure>

**4. Generate a new Client Secret**

<figure><img src="/files/KiG3Fg6CnkoQaFvRboFr" alt=""><figcaption></figcaption></figure>

**5. Choose “Agent” as login type**

* Select “Agent” for the login type
* Choose the Agent to log in as that has Admin permissions or [create a new API agent](https://help.alternativepayments.io/integrations/psa-integration-guides/halopsa/creating-a-new-halopsa-agent)

#### 6. Configure Permissions & "Save” the Application in HaloPSA

* Toggle to the “Permissions” tab

<figure><img src="/files/trVoJEBR3mkJpe8SmDfR" alt=""><figcaption></figcaption></figure>

* Click “Edit” in the top left corner, select the following boxes and then hit Save

1. Admin:webhooks
2. Read:customers
3. Edit:customers
4. Read:invoices
5. Edit:invoices
6. Read:contracts
7. Edit:contracts
8. Read:timesheets
9. Read:tickets
10. Read:calendar

#### **7. Fill out the Alternative Payments form**

Within your Partner dashboard, click on "Connect" within the HaloPSA module and fill out the form with the following details:

* App Domain
* Client ID
* Client Secret
* Invoices Created Since (optional, not required for secondary integration set up)
* Invoice Number Field (HaloPSA ID or Third Party Invoice Number)

<figure><img src="/files/K6vUfyOYfSQfFLMztFSW" alt=""><figcaption></figcaption></figure>

Click “Continue” and your integration set-up is complete!

***

### **How to ensure agreement subtypes sync into Alternative Payments**

1. Within HaloPSA, navigate to Configurations and then Agreements.
2. From Agreements, scroll down and select *Agreement subtype*.
3. Create any applicable agreements and any invoices associated with this agreement subtype will be synced into Alternative Payments where you'll be able to configure a contract-based auto-pay rule.

<figure><img src="/files/iYeHQV6viycT2DZq8PHN" alt=""><figcaption></figcaption></figure>

***

### **Customer Filters**

When you connect HaloPSA to Alternative Payments, the system normally syncs **all customers** from your Halo account. The Customer Filter gives you granular control by allowing you to:

* **Select specific customer top levels** to sync
* **Exclude certain customer top levels** from syncing
* **Filter both customer and their associated invoices** - only customer matching your selected Top Levels will be synced along with their invoices

#### How It Works

When you apply customer type filters:

1. **Customers** - Only customers that match your selected customer Top Level will be synced
2. **Invoices** - Only invoices belonging to filtered customers will be synced

{% hint style="info" %}
**Note:** Filters apply to both initial sync and ongoing synchronization
{% endhint %}

#### How to Set Up Customer Filters

1. Connect your HaloPSA integration
2. Click on `Finish Setup`

<figure><img src="/files/87Eks4i3u5rNOqdhgP4s" alt=""><figcaption></figcaption></figure>

3. Select any customer Top Levels needed, this field is not required<br>

   <figure><img src="/files/X9yLq4AFhMQPEw02GyoC" alt="" width="339"><figcaption></figcaption></figure>

{% hint style="info" %}
**Tip:** You can manage your filters anytime by clicking on `Manage filters` option\
\ <img src="/files/xOzqveFyJ7IWjQD1KeEX" alt="" data-size="original">
{% endhint %}

***

### Initiating Manual Syncs

For partners using HaloPSA as the primary integration, the functionality to initiate manual syncs is available. Click on the three dots and you'll see the option to "Fetch new data" "Fetch unpaid invoices."

![](/files/lrTh0ZrkVVAMBXaSV8db)

1. **Fetch New Data:** This option allows for the sync of all invoices and customers created or updated within the last hour.
2. **Fetch Unpaid Invoices:** Partners can now initiate a manual sync for all unpaid invoices to capture any invoice updates to unpaid invoices if needed.
3. **Limitations:**
   * The Fetch New Data can be initiated once per hour.
   * The Fetch Unpaid Invoices can be executed once every 12 hours.

**Love our platform?** Rate us on [Channel Program](https://channelprogram.com/v/alternativepayments) and check out our [Referral Program page](https://www.alternativepayments.io/referral-partners/)!


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.alternativepayments.io/integrations/psa-integration-guides/halopsa/halopsa-integration-set-up-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.