Best Practice and Halo Connect Integration: What It Takes

Best Practice is the practice software in most Australian GP clinics. In September 2026, Medical Republic put its share of the GP market at about 80%, with Medical Director at 15% and everything else at 5%. If your software needs data from a GP practice, sooner or later you need Bp Premier.

I'm the sole engineer on 2Pay, which pays doctors in Australian medical practices. 2Pay reads billing data out of Best Practice to work out what each doctor is owed. This post covers what that involved: the connection, the data, the quirks, and the partner security review that sits around all of it.

The rules and limits at a glance

Sources: Best Practice's partner network announcement, the Halo Connect FAQ, Halo's SQL passthrough docs and Bp's Partner Cyber Security FAQs.

How do apps connect to Best Practice in 2026?

Only through Halo Connect. In October 2025, Best Practice announced that Halo Connect would be the only connection method for partners from 1 January 2026, with pairing codes required from 1 February 2026.

Halo Connect has two parts. Halo Cloud is a set of APIs hosted in Australia. Halo Link is a small connector that runs on the practice's own server, next to the Bp database. Your software never talks to the practice directly. It sends a SQL query to Halo Cloud, Halo Link runs it against the practice database, and the results come back the same way.

Switching it on is the practice's decision. The practice enables your product inside Bp Premier and gives you a site ID and a pairing code. You pair the site once, and every query after that is routed to that practice. Halo says it keeps no practice data, though results can be held briefly so you can collect async queries.

2Pay only reads. It never writes anything to Best Practice.

What data can a Best Practice partner read?

Only the tables Best Practice grants to your integration. For 2Pay that meant 61 billing tables, 753 columns and no patient table. 2Pay reads 10 of those 61 tables.

There are no patient names in 2Pay, by design. The import takes the payer type and record IDs, which is all a doctor's pay calculation needs.

Probe the stage system, don't guess the schema

Bp's table and column names aren't public, and an integrator only sees what Bp grants. So I set one rule: no field mapping gets written against an assumption.

Halo provides a stage site paired with a Bp database full of fake patients and fake billing. I ran read-only discovery queries against it, saved every result, and wrote the mappings and tests against that real output. The first import pipeline was merged on 8 June 2026, the same day as the first probe query. In July, a second round of probing confirmed the rules for paid status before 2Pay relied on them for money.

The saved output became test data. When Bp's behaviour surprised me later, I could check a real result instead of a guess.

The Best Practice data quirks to plan for

These are the behaviours that matter if you build against Bp billing data. Each one became a test.

1. Money is stored as whole cents. Divide by 100 into a decimal type, and never use floating point.
2. Text comes back padded with spaces to the column width. Trim every value you read.
3. Provider numbers come back masked through the API. Match doctors on Bp's internal user ID instead.
4. Not every user is a doctor. A flag marks billing providers, and reception and nursing staff don't have it.
5. Deleted rows stay in the table with a status flag. On the stage site, 15 of 25 payment rows were deleted. Skip that filter and you count money that was voided.
6. Paid status lives on each service line, not on the invoice.
7. The same column name can mean different things in different tables. One GST column holds an amount in cents. Another holds a yes or no flag. On stage, the amount column held 0 seventy-one times and 890 once. Check the values, not the name.
8. MBS item 0 means "not Medicare". WorkCover certificates and reports are billable lines with no MBS number.
9. The billed price comes from joining the practice's fee list to the standard schedule. It isn't stored in one column.
10. Bp has no setting for a practice's service fee percentage, so it became a 2Pay setting.
11. Recording a payment updates the service line's timestamp but not the invoice's. A sync that asks for "everything updated since" misses it unless you fetch the invoice again by ID.
12. One table has no "updated" timestamp at all, so it needs its own way of tracking what's new.
13. SQL Server's datetime type starts in 1753, but .NET's minimum date is the year 1. Sending it makes the query fail, so "since the beginning" is set to 1900.
14. A "successful" immediate query can stop at the 8 MB limit and still report the full row count. If a sync moved forward on that partial result, the missing rows would be skipped forever. 2Pay compares the counts and switches to an async query when they don't match.
15. Error text from upstream can include SQL and server details. It's logged for me and replaced with a plain message before a practice manager sees it.

For a feel of the data, one stage invoice totalled 30,245 cents: MBS item 23 at $65.00, item 721 at $173.40 and item 30071 at $64.05.

Immediate or async queries?

Halo recommends async queries as the default, and immediate queries only for time-sensitive work. 2Pay does the opposite, for its own reasons.

2Pay imports twice a day, at 6 am and 6 pm Sydney time, and only asks for what changed. Those updates are small, so an immediate query gets them in one round trip. A full import, when a practice first connects, pulls the last 30 days and can be large. That goes async, and so does any immediate query that comes back cut short. Async jobs are checked every two seconds for up to about five minutes.

A practice server that's switched off is a normal event, not an outage. Halo reports it as its own failure state, so plan for it. Halo's post on async queries explains the trade-offs from its side.

Imported history must never be payable

When a practice connects, 2Pay imports past invoices for reporting and aged debt. Only invoices after a set start date can enter a pay run.

Review of the first version found that historical invoices could slip into collection. Left alone, it would have debited doctors for billing from before 2Pay existed. One date setting now separates the two. The same review caught two other real bugs before the code was merged.

Once an invoice is in a pay run, it's also frozen. Later imports can't change its price, its doctor or its dates.

What security evidence does Best Practice ask partners for?

A grey box penetration test every two years, a cyber certification every year, and Critical or High findings fixed within two business days. That's from Bp's Partner Cyber Security FAQs, which add a few details worth knowing early:

• Grey box means the tester gets logins and inside knowledge, so they check how the app is built, not just its front door.
• CREST accredited testers are strongly recommended. Others are allowed if Bp can validate their qualifications.
• The scope is every app and integration service that talks to Bp Premier through Halo Connect.
• Significant changes to sign-in, permissions, architecture or data flows need a new test.

The public page doesn't say which certification it accepts. Ask Best Practice what evidence it wants before you write any of it. For 2Pay, that question was still open in September, after most of the work was done.

The grey box test

The test ran through August 2026 against 2Pay's staging environment, never production. It was credentialed, with full access to the source code and infrastructure, and it tested from five positions: no login, doctor, practice manager, platform admin, and an admin acting for a practice. It used the OWASP Top 10 2021 as its coverage model and OWASP ASVS 4.0.3 Level 2 as its standard.

It found nine issues, five of them rated High. All five High findings were fixed and retested by 6 September 2026.

I did the test myself. Hireadev isn't CREST accredited, and I'm also the person who writes the code. The report says both things on its first pages and includes the tester's background, so Best Practice can validate it. Being upfront about that builds more trust than hiding it.

The most useful lesson was about background jobs. 2Pay's scheduled jobs run with no logged-in user, so they need a way to work across practices. The top finding was that a web request could reach that same path. An automated security scanner suggested a fix that only let admins through. That fix would have stopped nightly settlement in production, because the scheduler isn't an admin. It isn't anyone. The real fix tells a background job with no user apart from a web request that has a user but no practice.

That pattern repeated across the build. The scanner opened 110 pull requests between June and September 2026. Many found real problems. None was merged as written, and several would have broken production.

SMB1001 Gold

2Pay's certification target is SMB1001 Level 3, called Gold, issued through CyberCert. SMB1001 is written by Dynamic Standards International for small and medium businesses. Gold has 27 requirements in the 2026 edition, up from 22 in the 2023 edition. It isn't an external audit. A company director attests to it by formal deed, and it lasts 12 months.

The document set took about five weeks, alongside the grey box test and its fixes: 19 policies and standards, an attestation register and a remediation plan. They cover access control, patching, backups, incident response, invoice fraud, secure development, suppliers and more.

Gold's slowest controls aren't documents:

• DMARC email protection set to quarantine or reject, not just monitoring. Getting there safely takes seven to eight weeks of staged changes.
• Endpoint detection on every work device, including personal laptops used for work.
• Cyber insurance actually in place.
• Staff training actually delivered, not just planned.

Start those first. And write the attestation so it's true on the day you sign it. An insurer and a partner will read the same answers, and an overstated one can void a policy at the moment you need it.

How long does it take to get from stage to production?

For 2Pay, about four months from working on the stage site to asking for production keys. The code was the quick part. The partner steps take longer.

1. Join the Best Practice Partner Network. Halo only issues stage access to partners the practice software vendor has approved.
2. Get Halo stage access. Halo sets up a stage subscription, free for six months.
3. Build and prove the integration against the stage site. 2Pay had stage access by 8 June 2026.
4. Meet Bp's security requirements: the grey box test and a cyber certification. 2Pay's test report was issued on 6 September 2026.
5. Get production ready with Halo: sign the order form, meet its security prerequisites and agree a rollout plan.
6. Give Halo a fixed Australian IP address for its allowlist. 2Pay sent one with its production key request on 2 October 2026, and that address is locked so it can't be released by accident.
7. Go live one practice at a time. Each practice enables 2Pay in Bp Premier and creates a pairing code, and 2Pay pairs the site.

Halo's integrator guide covers steps 2 and 5 in more detail.

If I did it again, I'd start the partner and paperwork steps on day one and run them alongside the build.

For your IT person

How the 2Pay side is built:

• A thin layer keeps Bp's shape out of the rest of the system. A transport client talks to Halo. A query runner handles immediate and async queries, polling, paging and decoding. One file holds every Bp SQL query. Pure mapping functions turn rows into staged records, and importers upsert by Bp's own keys. A Bp schema change touches a handful of files.
• Halo returns results as base64-encoded JSON arrays. Async results come back as numbered pages, each its own base64 block.
• Three triggers start an import: a full import when a practice connects, a manual re-import with a 15-minute cooldown, and the scheduled update twice a day.
• One import runs per practice at a time, enforced by a filtered unique index. Before that, long imports could starve payment jobs that shared the same Hangfire workers.
• Hangfire jobs run with no user and no tenant, so every read sets the practice explicitly and every write stamps it. This is where tenant isolation is most likely to break, so it has the most tests.
• When a practice also enters data by hand, a manual invoice links to its Halo copy only on Bp's invoice ID plus a matching doctor, date and lines. Anything close goes to a review queue and stays out of pay runs. The same invoice always leaves exactly one payable copy.
• All containers run in private subnets in AWS Sydney. Their only way out is a NAT gateway with a fixed Elastic IP, which Halo allowlists. A CloudFormation stack policy, termination protection, Retain policies and an explicit deny in the deploy role all stop that IP being released.
• The Halo subscription key lives in AWS Secrets Manager, one per environment. Outside production, every imported doctor email is replaced with one test address, so a test import can never email a real doctor.
• Every import writes an audit row with who started it, record counts, bytes and errors.

Every pull request runs blocking checks: Semgrep, .NET and npm vulnerability audits, Gitleaks over the full git history, cfn-lint, a Trivy container scan and the full test suite. Each build also produces a CycloneDX software bill of materials. Dependabot runs weekly, GitHub Actions are pinned to commits, and deploys use OIDC roles with no long-lived AWS keys.

About the 2Pay build

More from the same build: PayTo and NPP with Monoova: lessons from a real build.

Hireadev is run by Ryan Brooker in Brisbane. If your software needs to work with Best Practice or other practice systems, see system integrations and software for medical clinics. The 2Pay backend is built in .NET. To talk about your project, book a free 30-minute chat.