Square

Square's distinguishing feature in this list is the counter. On the Square side sit the card reader and point-of-sale terminal in the premises, the online payment surface, the customer directory, the item catalog, orders, invoices and refunds. On the AppBO side sit the contact, the appointment, the pipeline and the workflows, which until now have had no idea what happened when the customer actually walked in and paid.

Connecting them closes that loop. A client books through an AppBO calendar, attends, and pays at the desk on a Square reader; with the integration, that payment lands on their contact record, so the follow-up sequence knows they came and paid rather than merely that they were booked. Reactivation campaigns can target people who have not transacted in months, not just people who have not opened an email. Lifetime value includes the counter, which for any business with premises is most of it.

It is the right choice when a meaningful share of revenue is taken in person, or when Square is already the operational till and replacing it is not on the table. The integration work is mostly about identity: Square's till flow is optimized for speed, which means the person at the counter is often recorded thinly or not at all, and a payment with no customer attached cannot reach a contact. Getting a reliable identity key captured at the point of sale is the difference between a useful integration and a stream of orphaned transactions.

1. Confirm the Square account is set up for the locations involved. Square models each physical site as a location, and a transaction belongs to one. If you have more than one site, know which locations are in scope before connecting.
2. Decide what the integration is for: recording in-person sales against contacts, taking online payments, issuing invoices, or all three. The identity handling differs for each.
3. In the AppBO sub-account, open the payments settings and start the Square connection. Complete Square's authorization flow, signing in to the Square account that owns those locations, and approve the permissions requested.
4. Confirm which Square account and which locations the connection resolved to before relying on it. A multi-location merchant can easily authorize the wrong one.
5. Decide which system owns the item catalog. Square's catalog drives the till; the platform's products drive its own checkout. Pick one as authoritative for reporting and accept that the other is a mirror.
6. Solve identity at the counter, which is the real work. Decide what staff capture on every transaction (attaching a Square customer, or at minimum an email or phone) and make it part of the till routine. An unattributed sale is a sale the platform cannot see.
7. Choose the match key between the Square customer and the AppBO contact, normally phone or email, and normalize it: phone in E.164, email lower-cased. Counter-entered data is the least clean data in any business.
8. Add custom fields on the contact for the payment method or channel, the Square payment identifier, and the location, so a sale can be traced back and reconciled.
9. Configure online payments if you are using them, attaching Square to the order form or funnel checkout step, and test the hosted payment experience on a phone as well as a desktop.
10. Build the automation on the payment event. A completed in-person sale should be able to tag the contact, update the opportunity, and start a post-visit sequence: review request, rebooking prompt, aftercare instructions.
11. Build the refund and void paths. Counter refunds happen for ordinary reasons several times a week, and whatever the sale triggered must be reversible.
12. Verify in Square's sandbox first where the connection supports it: complete a payment, confirm the record reaches the platform, confirm the workflow ran and the custom fields populated.
13. Then verify on real hardware. Take one small live payment on the actual reader at the actual counter with a real card, and confirm it lands on the right contact at the right location. Hardware behaves differently from a sandbox API call.
14. Test the orphan case on purpose: take a payment with no customer attached and observe what the platform does with it. Design the handling you want rather than discovering it later.
15. Put reconciliation on a schedule (Square's own reporting against platform records, by location) and watch the orphaned-transaction rate as an operational metric. If it climbs, the till routine has slipped.

Square to the platform

• Completed payments with amount, currency, status, the Square payment identifier and the location.
• The payment method used (card present at the reader, card not present online, wallet or other tender), which is how you tell counter sales from web sales.
• Customer details from Square's directory where a customer was attached: name, email, phone.
• Order and line-item detail where the catalog is used, which lets automation branch on what was actually bought.
• Refunds and voids against prior payments.
• Invoice outcomes where Square invoicing is in use.

Platform to Square

• Payment requests for online checkout and order forms: amount, currency and reference.
• Customer records created or matched in Square's directory when a payment originates in the platform.
• Invoice or payment-link requests where that flow is used.
• Refund requests against a prior payment, where initiated from the platform.

What does not move

• Card data. It is captured by the reader or Square's hosted fields and never reaches the platform.
• Hardware and terminal state. Reader pairing, tipping prompts and receipt printing are configured in Square.
• Inventory counts, unless you have deliberately chosen to synchronize a catalog; the platform is not a stock system.
• Shift, timecard and staff management data from the point of sale.
• Transactions taken before the connection existed, and transactions at locations the authorization did not cover.
• Any attribution for a sale where no customer was attached at the till. There is nothing to match on.

Scenario: a clinic books appointments in AppBO and takes payment at the desk on a Square reader. The post-visit sequence must only run for people who actually paid.

1. A patient books a consultation through an AppBO calendar. The contact exists with a cell number stored in E.164 and an email.
2. They attend. At the desk, the receptionist searches Square's customer directory by phone, finds the customer record created by a previous visit, attaches it to the sale, and takes the payment on the reader.
3. Square completes the card-present payment and emits the transaction with its payment identifier, the location and the attached customer.
4. The platform receives the payment, matches the Square customer's phone to the contact's phone, and records the transaction against that contact.
5. The payment workflow fires: it writes Square: card present to the channel field, stores the payment identifier and the location on custom fields, marks the appointment attended, and moves the opportunity to Completed.
6. The workflow then waits two hours and sends the aftercare email, waits three days and sends a review request by SMS, and schedules a rebooking prompt for six weeks out. None of this would have fired for a no-show, because it is driven by the payment rather than the booking.
7. The next patient pays in a hurry and the receptionist attaches no customer. The platform receives a payment it cannot match. Rather than discarding it, the integration records it in a holding view and raises a task so somebody can attribute it from the day's appointment list.
8. That afternoon a staff member attributes the orphan to the right contact, which records the sale and starts the same post-visit sequence a few hours late.
9. A week later the first patient requests a partial refund. It is processed at the desk in Square, which emits a refund event.
10. A workflow on the refund tags the contact refunded, removes them from the rebooking sequence, and raises a task for the practice manager to note the reason on the contact.
11. At month end the clinic reconciles Square's location report against the platform's payment records. The totals agree, and the orphaned-transaction count is two out of several hundred. Low enough that the till routine is working, and tracked so that it stays that way.

Rate limiting

Square publishes its own API limits, and they are per endpoint; check the current documentation rather than assuming, and back off on throttled responses. The more realistic limit for a busy counter is burst: a lunchtime rush produces a dense cluster of payment events, so whatever consumes them must cope with a spike rather than an average.

Retries and idempotency

Square's payment APIs accept an idempotency key and you should always send one. A retried payment request without it can charge the customer twice, which at a counter means an argument in front of a queue. Event notifications are delivered at least once and retried, so dedupe on the event or payment identifier. Refunds need the same care: a retried refund without idempotency can return the money twice.

Field mapping traps

Amounts are in the currency's smallest unit; verify against a real transaction before trusting your mapping. Counter-entered contact data is messy (phone numbers without country codes, mistyped emails, names in the wrong field) so normalize aggressively before matching. Location identifiers matter: a multi-site merchant that ignores location cannot tell which site earned what, and attributing all revenue to one site will be noticed by whoever runs the other.

Unattributed transactions

This is the characteristic Square problem and it is operational, not technical. A payment taken with no customer attached has nothing to match to a contact, and it will happen whenever the counter is busy. Build the handling deliberately: hold the transaction, surface it for attribution, and measure the rate. Do not silently drop it, and do not guess the contact from timing alone.

Duplicate creation

Duplicate Square customers accumulate quickly at a counter when staff create a new record rather than searching for the existing one, and each duplicate can produce a second AppBO contact. Train the search-first habit, and periodically merge duplicates in Square's directory rather than only in the platform.

Sandbox versus live

Square's sandbox covers the API well but cannot reproduce the hardware. A flow that tests perfectly against the sandbox can still surprise you on a physical reader: tipping prompts, partial authorizations, offline mode. Always finish testing with one real transaction on the real terminal, and be careful with live credentials in a test environment: a live key on a test page takes real money.

Offline mode and timing

Readers can take payments while connectivity is down and upload them later. Those transactions arrive late and out of order, so a workflow that assumes a payment is recent may act on stale information. Compare the payment's own timestamp rather than the arrival time.

Auth expiry

The Square authorization can be revoked by an administrator, can lapse if tokens are not refreshed, and does not cover locations added after the grant. A new site will simply not appear until it is re-authorized. Monitor for a location whose transactions have stopped arriving, which is the usual first symptom.

What commonly breaks

• Payments taken with no customer attached, leaving revenue unattributable.
• A new Square location added and never authorized, silently missing from reporting.
• Phone numbers stored inconsistently, so counter sales match no contact.
• Offline payments arriving late and triggering workflows out of sequence.
• Counter refunds with no reversal path in the platform.
• Duplicate customers in Square's directory multiplying into duplicate contacts.
• Smallest-unit amount errors in online checkout mappings.