The Square integration is generally reliable, but a few edge cases are worth knowing about.
"It says PENDING and the customer paid days ago"
Check Square first. If the payment shows COMPLETED in Square's dashboard, then Pistonlog missed the webhook (rare, but possible). Tap Refresh on the payment status to force-fetch from Square's Payments API — that normally syncs the status.
"Terminal payment didn't auto-update"
Known quirk: Terminal checkouts store the device-side checkout.id while Square's webhook events carry order_id. The two don't always match for terminal flows, so the automatic webhook update can miss. Same fix: tap Refresh on the payment status.
Failed sends (SMS or email)
If the SMS or email send fails after Pistonlog has created the Square payment link, the payment row is marked FAILED (not left stuck on PENDING). The credit isn't deducted for a failed SMS. Retry the send or pick a different method.
"I want to issue a refund"
Refunds aren't issued in-app. Refund directly from the Square dashboard, then record the situation in the jobcard's comments for the audit trail.
Refunded status doesn't auto-sync
Pistonlog's webhook handler currently processes payment.created and payment.updated events; it doesn't process refund.* events. So a Square dashboard refund won't automatically flip the Pistonlog payment row to REFUNDED. The refund is real in Square — Pistonlog's UI just won't reflect it until the next webhook revision adds refund handling.
Re-connecting Square
Tokens auto-refresh in the background (a daily cron job refreshes anything expiring within 7 days; individual payment calls top up tokens expiring within 5 minutes). You generally don't need to think about this. If Square ever revokes the integration on their side, the connection breaks until you reconnect from Settings → Integrations → Square.