> ## 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. # Earn with Square and redeem in Perkstar > Attach an existing Square Customer, award the routed Perkstar programme and understand the separate Perkstar redemption boundary. Square provides the completed sale and refund signals. Perkstar owns the member, loyalty balance, Wallet pass and reward redemption. A seller can start earning through Square's standard customer-attachment path. Wallet QR identification is optional. Customers can redeem eligible rewards themselves from their pass, or staff can use Perkstar Scanner. Neither path requires Square Loyalty or a Square QR scanner. ## Award a completed payment ### Standard customer attachment The customer joins the business's Perkstar programme before their first eligible Square sale. Adding the pass to Apple Wallet or Google Wallet lets them view updates and present the card; installation is not required for email or phone matching to an active enrolment. Use Square's normal customer search and choose the existing Square Customer whose email address or phone number exactly matches the Perkstar member. If both fields are present, their exact matches must identify the same member. Confirm the intended Square Customer is attached to the sale before taking payment. Perkstar does not guess the buyer of an anonymous sale. Perkstar reads the completed Square payment, follows the location's programme route, credits the existing member once and queues their Wallet pass update. ### Optional Wallet QR attachment On a tested compatible device, staff can replace the normal customer search with one Wallet QR scan. The business must first enable Wallet-card identification, and that customer must have given current consent. In the Square checkout, open **Review sale → Add customer → scan icon**. Scan the QR code on the customer's Perkstar Wallet pass and confirm the correct Square Customer is attached before payment. Perkstar either reused one complete exact match or, only if none existed, created the profile. The payment follows the same customer-attributed earning path as a customer attached through Square's standard search. Wallet QR compatibility depends on the Square app and device. Terminal or Register running Square Point of Sale needs both **Scan customers using device camera** and **Show Add customer button during checkout** enabled. Attaching a customer only after checkout is not sufficient for Perkstar earning. Keep Square for Retail or Restaurants current. Test a Handheld or physical scanner against a QR displayed on a phone before relying on it; otherwise use the standard Square customer search. A customer must already belong to the routed Perkstar programme. An anonymous payment does not earn. The optional Wallet QR path does not change the payment boundary: an unrelated attached Square customer who does not match an existing Perkstar member is not enrolled, and the unmatched contact is not retained. ## How earning is calculated | Programme | Square payment result | | - | - | | Ordinary Stamp | One stamp for the completed customer-attributed payment | | Spend-based Stamp | Whole thresholds met × stamps configured per threshold | | Visit-based Stamp | The configured stamps per visit | | Spend-based Points | The configured points rate applied to the paid amount | | Visit-based Points | The configured points per visit | | Cashback | The active tier's percentage applied to the paid amount | The Square location either inherits the merchant's explicit default programme, uses its configured override, or deliberately pauses loyalty. Payment and webhook redelivery are idempotent, so the same completed payment cannot credit twice. ### Amount, timing and limits * Spend earning uses Square's `Payment.amount_money`, excluding the separately reported staff tip. It is not a pre-tax subtotal: Perkstar does not inspect individual products, tax lines or category exclusions. See Square's [Payment definition](https://developer.squareup.com/reference/square/objects/Payment). * Square and the Perkstar business must use the same currency. There is no currency conversion. Spend-points rates include the programme's configured spend unit and are rounded to two decimal places; spend-stamp thresholds are rounded down. Cashback is stored in whole minor currency units. * The earning unit is a **payment**, not an order or a calendar-day visit. Split-tender payments can produce more than one visit award; spend-stamp thresholds are evaluated separately for each payment. Do not promote one-award-per-basket or combined split-tender thresholds. * Processing is asynchronous: Square notifications are persisted, then the background worker and Wallet updates run. A Connected badge is not proof of a sale being credited. Offline sales cannot earn before Square receives the payment and Perkstar processes it. * Cancelled, failed, zero-value and anonymous payments do not earn. This integration follows payment completion, not appointment attendance or no-show status. It does not import historical sales from before installation. Programme rewards, daily stamp limits and applicable promotion rules remain Perkstar rules. Confirm the exact merchant programme, expected amount and reward threshold in the final test; do not infer them from the Square basket. ## Redeem a reward Redemption is completed in Perkstar. **Square Loyalty is not required**, and rewards are not copied into Square. Choose either of these two workflows; do not redeem the same reward through both. ### Option 1: the customer redeems from their pass The customer opens their Apple Wallet or Google Wallet pass details and chooses **Available rewards → Redeem**, or opens **My Account** and selects an available reward. They need an internet connection. Wait until staff are ready to honour the reward; simply showing an available reward is not a redemption. The customer selects the reward and the correct location if prompted, then slides to redeem. Perkstar validates eligibility, records the redemption and consumes the relevant reward or points. Wait for the live **Redeemed** confirmation; an error or pending screen is not confirmation. Staff check the business, reward and live countdown on the customer's screen, then apply the agreed complimentary item or discount in Square using their normal till procedure. The fresh confirmation lasts three minutes. A screenshot, an available-reward screen or an expired confirmation must not be accepted as a fresh redemption. This is customer-led redemption: staff do not need to open Perkstar Scanner for the supported reward. Staff still verify and fulfil it; Perkstar does **not automatically apply a Square discount** or link the redemption to a Square basket. The live screen is a staff check, not Square payment validation. ### Which Square-earned rewards can customers redeem themselves? | Perkstar reward | From the pass | | - | - | | Stamp card | Available, unexpired stamp reward vouchers, including eligible bonus rewards | | Points card using **Reward tiers** | A configured reward tier the customer's available points cover | | Points status-tier benefit or a separately granted offer | When shown as available and its programme rules allow it | | Points redeemed as a cash amount | Staff-assisted redemption; the pass does not let customers choose a monetary debit | | Cashback balance | Staff-assisted redemption; the pass does not let customers spend the cashback balance | Self-redemption uses the existing card and reward configuration; there is no Square-side self-redemption switch. The programme and enrolment must be active, and the reward must be available under its expiry, location and usage rules. Other Perkstar card types can have their own pass-redemption options, but that does not make them eligible for Square payment earning. Sliding to redeem consumes the reward in Perkstar immediately; it is not a reservation awaiting Square checkout. Closing the screen or letting the three-minute confirmation expire does not restore it. If checkout is cancelled, the confirmation expires before service, or a staff member is unsure whether it was already honoured, check the customer's Perkstar activity and resolve it with an authorised team member. Do not redeem again or apply a second discount. A Square refund corrects the supported earning from that payment; it does not automatically restore a separately redeemed Perkstar reward. ### Option 2: staff redeem using Perkstar Scanner The customer presents their Apple Wallet or Google Wallet pass. Staff scan it with Perkstar Scanner and confirm the correct member. Choose the available reward and complete the redemption. Wait for Perkstar to confirm it so the member's balance and audit trail remain authoritative. Add the corresponding complimentary item or discount in Square using the business's normal till procedure, then complete checkout. Do not create a parallel reward or loyalty balance in Square. Perkstar is the source of truth, and Square is the till where staff apply the matching item or discount after a confirmed Perkstar redemption. ## Customer matching and privacy For optional scan setup, current customer consent is required before Perkstar searches the connected Square directory, creates or links a profile, or publishes a reference. For a consenting customer, it exact-searches by stable reference, email and available phone without importing the directory. A unique existing customer can be linked; only if none exists may Perkstar create a profile from the member's name and contact details. Perkstar writes the stable Wallet scan value only into an empty `reference_id`, preserves every foreign value, and later releases only a value it can prove it owns. The customer can change this choice by opening the customer-account link on the back of their Wallet pass, then choosing **Preferences → Square customer identification**. For an ordinary attributed payment, Perkstar still reads only the attached Square customer. Its email address or phone number is transient matching input for an existing Perkstar member. A successful match creates an opaque identity link scoped to that Square merchant and installation. Contact details from an unmatched Square profile are discarded and are not used for marketing. If exact email and phone evidence points to different Perkstar members, neither field silently outranks the other. The payment awards nothing and remains queued for a safe retry while Perkstar opens a merchant-visible **Customer match** case. Correct the duplicate or member contact details; do not manually adjust a balance while the case is open. The case summary and support link contain only the safe operational wording and Perkstar case ID, not customer contact details or Square identifiers. For corrections and delayed events, continue to [Refunds and troubleshooting](/integrations/square/refunds-troubleshooting). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.