Skip to main content

Practice management payments

Practice management software often serves multiple billing entities sharing the same front desk: individual providers with their own merchant accounts, or a mix of in-person and phone-based payment collection. This guide covers the Handpoint features that fit that model — applicable to medical, dental, optometry, veterinary, mental health, and similar multi-provider practices.

Multi-MID: one integration, one device, multiple providers​

Multi-MID lets a single Handpoint integration route transactions to separate merchant accounts — one per provider — without separate API keys or separate terminals.

How it works: Handpoint configures a main MID for the practice and sub-MIDs for each provider. Your software maps each provider to an externalId (Cloud API) or MerchantAuth (Android PAX) and includes it on every transaction.

POST https://cloud.handpoint.com/transactions
ApiKeyCloud: YOUR_MERCHANT_API_KEY
Content-Type: application/json

{
  "operation": "sale",
  "amount": "15000",
  "currency": "USD",
  "terminal_type": "PAXA920",
  "serial_number": "082104578",
  "transactionReference": "3c9de220-b14a-4a0c-9d2e-b3c1088e5a91",
  "merchantAuth": [{ "externalId": "dr-patel" }]
}

Omit merchantAuth / MerchantAuth to fall back to the practice's main MID.

Provisioning

Sub-MIDs are configured by Handpoint Integration Support. Each provider needs a separate merchant account with the acquirer before a sub-MID can be created.

See Multi-MID Reference for the full setup checklist and reconciliation guidance.

Card-present at the desk​

For patients paying at the front desk, use either:

  • Cloud API — your practice management software initiates the transaction over HTTP; a PAX terminal sits at the desk and prompts the patient. No Android development required.
  • Android SDK on PAX — your check-in or billing application runs on the PAX terminal itself; the billing UI and card payment are on one device.

Both paths support Multi-MID. The choice depends on where your software runs, not on the payment flow.

Phone payments (MOTO)​

For patients who call in to pay, use a stored card token from a prior in-person transaction:

POST https://cloud.handpoint.com/transactions
ApiKeyCloud: YOUR_MERCHANT_API_KEY
Content-Type: application/json

{
  "operation": "moToSale",
  "amount": "15000",
  "currency": "USD",
  "terminal_type": "PAXA920",
  "serial_number": "082104578",
  "cardToken": "TOKEN_FROM_PRIOR_TOKENIZATION",
  "merchantAuth": [{ "externalId": "dr-patel" }],
  "transactionReference": "new-uuid-here"
}

The merchantAuth field works the same on MOTO calls as on card-present transactions — provider routing is preserved regardless of payment channel.

To obtain a cardToken, use a saleAndTokenizeCard operation during a card-present visit. The token is in the result as cardToken.

Acquirer requirement

MOTO requires EPI for North American merchants. EmerchantPay supports MOTO for EU merchants. See the Acquirer Capabilities Matrix.

Pre-authorization for uncertain costs​

For appointments where the final amount is not known upfront (extended visits, supply usage, additional procedures), pre-authorization places a hold at check-in and captures the actual amount when the visit closes.

The patient presents their card at arrival; the front desk sends a preAuthorization through the terminal. When the provider closes the visit, your system captures the exact amount from the server — no card re-presentation required.

# At check-in — card-present
POST https://cloud.handpoint.com/transactions
{ "operation": "preAuthorization", "amount": "30000", "merchantAuth": [{ "externalId": "dr-patel" }], ... }

# At checkout — back-office, no terminal
POST https://cloud.handpoint.com/preauthorization/capture
{ "originalGuid": "TRANSACTION_ID_FROM_PREAUTH", "capturedAmount": "27500" }
Hold expiry

Card networks release holds in 7–30 days depending on the issuer. Always capture or release within that window, or the hold disappears and you cannot collect.

See Pre-Authorization Guide for code examples and acquirer support.

Reconciliation by provider​

Use the Transaction Feed API to produce per-provider reports:

  • Cloud API transactions — filter by externalId
  • Android PAX transactions — filter by merchantId (the sub-MID value)

Both channels write to the same feed. A single query scoped to externalId: "dr-patel" returns every card-present and MOTO transaction for that provider, regardless of how it was taken — giving the practice a unified settlement view without maintaining a separate ledger.