Square payment import (fallback)

What this is for

Square sends payment notices to the clinic portal as soon as a card payment completes (webhooks). If a notice is delayed or missed, a background job checks Square about every 15 minutes for each clinic that has Square connected. It looks for completed payments that were not already saved, then:

• Applies the invoice amount from the payment note to the matching bill (the card processing fee is left off the bill).
• Saves an unmatched payment only when the charge looks like a portal payment (a bill number in the note, Square reference, or checkout order) but no bill matches, so staff can match it by hand.
• Ignores ordinary Square sales (for example front-desk card charges) that have no bill number. Those are not stored in the portal.

The same Square payment is never counted twice.

Before you start

• Square is connected for this clinic, and a location is chosen.
• Webhooks are the main path; this import is only a safety net.

What staff see

• Matched charges update the bill and appear in payment history with a Square receipt id.
• Portal-looking charges that cannot be matched appear on the unmatched payments list until someone resolves them.
• Unrelated Square sales do not appear in the portal.

What it does not do

• It does not move money between clinics. Each clinic only reads its own Square seller.
• It does not replace the webhook. The job is a fallback.
• It does not put the card fee on the client bill when the note includes an owed= amount.

Tips

• If a client paid and the bill still looks open, wait for the next import window or check the unmatched list.
• Prefer fixing webhook delivery first; the 15-minute import is for gaps, not day-to-day matching.