> ## Documentation Index > Fetch the complete documentation index at: https://developers.perkstar.co.uk/llms.txt > Use this file to discover all available pages before exploring further. # Square > Connect Square to Perkstar for customer-attributed earning, location-aware programme routing and matched refund corrections. Square Use completed Square payments to reward customers who have already joined a Perkstar programme. With optional Wallet-card identification enabled, staff open **Review sale → Add customer → scan icon** and scan the customer's Perkstar Wallet QR code. Square attaches the safely matched or consent-created customer before payment, and Perkstar applies the routed programme's earning rule and updates their Wallet pass. Square is a **production beta** available to eligible Scale businesses through Perkstar's direct installer. The integration is not currently listed in the Square App Marketplace; Perkstar is collecting the five active-seller evidence required before submission. Identify an existing member with one Wallet-card scan. Exact matching, consented profile creation and reference ownership all fail closed. Route the Square location to an eligible Stamp, Points or Cashback programme and credit a completed payment exactly once. Full and partial refunds against the original Square payment reverse the corresponding Perkstar credit safely. ## System boundaries Perkstar is the loyalty system of record. Square supplies merchant, location, completed-payment, refund and attached-customer signals. If the business enables customer identification, current customer consent gates every Square search, link and reference publication. For a consenting customer, Perkstar may exact-match an existing Square Customer, create one from their name and contact details only if no match exists, and put that member's stable Wallet scan value in an otherwise empty Square Customer `reference_id`. Rewards are still redeemed with the Perkstar pass and scanner, then staff apply the corresponding item or discount in Square. **Square Loyalty is not required.** Perkstar never creates or updates Square payments, loyalty balances or rewards, and it does not request Square Loyalty permissions. Customer write access is used only for the optional identification flow described above. | Event | What Perkstar does | | --------------------------------------------------- | ------------------------------------------------------------------------------------- | | Staff scans a prepared Perkstar Wallet QR | Square finds and attaches the linked Square Customer | | Completed payment with an attached matched customer | Applies the selected programme's earning rule once | | Anonymous payment | Ignores it because no customer can be identified | | Attached customer who has not joined Perkstar | Discards the unmatched contact without retaining or enrolling it | | Full or partial refund | Reverses the supported share of the original Perkstar credit once | | Reward redemption | Records redemption in Perkstar; staff complete the matching till adjustment in Square | ## What you need * A Perkstar **Scale** plan or another plan that includes POS Connect. * Owner access or a team role with **Edit operations** in Perkstar. * Permission to approve apps for the intended Square production account. * At least one active, earn-ready Stamp, Points or Cashback programme. * Customers enrolled in Perkstar before the payment you want to reward. * For one-scan identification: an individual default programme with a QR code and required First name and Email fields. Connect safely, choose the default programme and review every location. Give staff the exact customer, payment and reward workflow. Reconcile corrections, diagnose missing credit and disconnect safely. ## Data use For payment earning, Perkstar reads the Square merchant and location profile, completed payments and refunds, and only the customer attached to a payment. Email or phone is used transiently to find an existing Perkstar member. If no member matches, the contact is not retained, enrolled or used for marketing. Optional Wallet-card identification does nothing in Square without current customer consent. For a consenting customer, it performs complete exact searches by the stable scan reference, email and, when available, phone. If the searches resolve to one Square Customer, Perkstar links that profile. If none resolves, Perkstar may create a Square Customer from first name, optional surname, email and optional phone. Perkstar writes the stable Wallet scan value only when `reference_id` is empty, never overwrites a value owned by the merchant or another system, and releases only a value for which it has durable ownership evidence. After a successful match, Perkstar stores an opaque Square customer link scoped to that merchant and connection. It also stores encrypted OAuth credentials, card and location routing, and the operational and loyalty records required to deduplicate earning and reconcile refunds. See [Set up Square](/integrations/square/setup) for the permissions and test procedure. Need help with a pilot connection? Email [support@perkstar.co.uk](mailto:support@perkstar.co.uk) with the Perkstar business name, approximate payment or refund time, and Square location name. Never send an access token, raw webhook payload, payment-card data or customer contact details. ## Related topics - [Square](/integrations/square/index.md) - [Square refunds and troubleshooting](/integrations/square/refunds-troubleshooting.md) - [Earn and redeem with Square](/integrations/square/earning-redemption.md) - [Set up Square](/integrations/square/setup.md) - [Integration gallery](/integrations/index.md)