HaloPSA Custom Integration: Connect Halo to the Benji Pays API

A HaloPSA Custom Integration lets Halo call the Benji Pays API directly. Once it's set up, your Halo runbooks can look up Benji Pays information, such as a customer's declined payments or open invoices, and act on it in Halo. For example, a runbook can open a ticket or put a client on credit hold.

This article covers:

• Creating a Benji Pays API key
• Adding Benji Pays as a Custom Integration in HaloPSA
• Adding integration methods (the individual API calls)
• Testing the connection
• 
  

Before You Start

You will need:

• A Benji Pays user with Company Admin access and access to the API page
• A HaloPSA agent with access to Configuration → Integrations → Custom Integrations
• Your Halo clients' Accounts ID filled in with the accounting system customer ID

Step 1: Create a Benji Pays API Key

1. Log in to Benji Pays.
2. In the left menu, click API. This opens the API Access page.
3. Make a note of the API base URL shown at the top of the page. You will need it in Step 2.
4. In Key name, enter a name that tells you what the key is for (e.g., HaloPSA Custom Integration).
5. Under Key expiration, choose how long the key should last (1 month, 3 months, 6 months or 1 year).
6. Under Permissions, select only what Halo needs. For the methods in this article, select View transactions and View invoices. Also select View customers if you plan to look up customers.
7. Click Generate API Key and enter the verification code sent to your email.
8. Click Copy to clipboard and keep the key somewhere safe until you finish Step 2.

Note: API keys expire. Set a reminder to generate a new key and update it in Halo before the expiry date shown in Your API keys.

Step 2: Add Benji Pays as a Custom Integration in HaloPSA

1. In HaloPSA, go to Configuration → Integrations → Custom Integrations.
2. Click Integrations, then click New.
3. Fill in the fields as shown below, then click Save.

Name

Benji Pays

Base Resource URL

https://api.benjipays.com/

Use the API base URL from the Benji Pays API Access page. Include the trailing slash (/). Method paths in Step 3 are added to the end of this URL.

See https://developer.benjipays.com for API documentation

Authorization

Select API Key. Then fill in the API key fields:

Step 3: Add Integration Methods

Each method is one call to the Benji Pays API. The methods below are the ones most runbooks need. Add only the ones you plan to use.

1. In HaloPSA, go to Configuration → Integrations → Custom Integrations → Methods.
2. Click New.
3. Fill in the fields for the method (see the examples below), then click Save.

Use these settings on every Benji Pays method:

Note: Don't add an x-api-key header. The method gets the key from the integration.

Method A: List Declined Transactions for a Customer

Returns a customer's declined payments, newest first.

Name: List declined transactions for customer

URL / path: v2/transactions

Query Params:

customerId is the customer's ID in your accounting system. It is the same value as the Accounts ID on the Halo client. <<accountingCustomerId>> is a runbook variable that you fill in when the runbook runs.

Method B: Declined Transactions Since a Date

Use this to ask "has this customer had a decline recently?" It returns at most one result.

Name: List declines for customer since date

URL / path: v2/transactions

Query Params:

startDate accepts a date (2026-09-16) or a UTC date and time (2026-09-16T20:49:23Z).

Output Variables:

Method C: List Open Invoices for a Customer

Name: List open invoices for customer

URL / path: v2/invoices

Query Params:

Method D: Get an Invoice by ID

Name: Get invoice by id

URL / path: v2/invoices/<<invoiceId>>

Use the invoice ID from your accounting system.

Output Variable Tips

Output variables save part of the Benji Pays response so later runbook steps can use it.

• Benji Pays list responses return results in data and paging details in pagination. For example, response^data is the list of results and response^pagination^total! is the total count.
• Add ! to the end of a variable to remove the surrounding quotes, e.g. <<accountingCustomerId!>>. Use it when inserting a value into a URL, a number field or JSON.
• Set Data type to Array for lists (like response^data), so a runbook can loop over them or check whether they're empty.
• Output variable names must be unique across all of your Halo integration methods.

Step 4: Test the Connection

1. Open Method A (List declined transactions for customer).
2. Click Test.
3. When prompted for accountingCustomerId, enter the Accounts ID of one of your Halo clients.
4. Check the result:

• Response Status 200 with a data list means the integration is working. An empty list ("data": []) just means that customer has no declines.
• 401 Unauthorized means the API key is wrong, expired or deleted. Generate a new key in Benji Pays and paste it into the Value field on the integration.
• 403 Forbidden means the key is missing a permission. For transactions, make sure the key has View transactions.

Using the Methods in a Runbook

Once the methods are saved, you can use them as steps in a HaloPSA runbook (Configuration → Integrations → Custom Integrations → Runbooks). For example:

• A per-client runbook that checks a client for open Payment Decline tickets, opens one if none is open, and sets the client's Credit Hold custom field.
• A scheduled runbook that runs daily, finds clients with a Benji Pays decline in the last 10 days (Method B), and starts the per-client runbook for each one.

If a runbook needs to be started by another runbook, or by a POST from outside Halo, set its start option to Can only be started from Halo and from a public endpoint.

Reach out to Benji Pays support if you'd like help designing a runbook.

Quick Tips:

• Keep the API key on the integration only (Authorization → API Key, Add to → Header). Never add it as a method header or query parameter.
• Give the key only the permissions your methods need.
• Before a key expires, generate a new one in Benji Pays and paste it into the integration's Value field. You don't need to change the methods.
• If a method returns data for the wrong customer or none at all, check that the Halo client's Accounts ID matches the customer's ID in your accounting system.
• Several Halo clients can share the same Accounts ID. Runbooks that look up clients by Accounts ID will act on each of them.