Award a completed payment
Standard customer attachment
1
Enrol the customer in Perkstar
The customer joins the business’s Perkstar programme and adds its pass to
Apple Wallet or Google Wallet before their first eligible Square sale.
2
Find the customer in Square
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.
3
Attach and verify
Confirm the intended Square Customer is attached to the sale before taking
payment. Perkstar does not guess the buyer of an anonymous sale.
4
Complete payment normally
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.1
Open Square customer scanning
In the Square checkout, open Review sale → Add customer → scan icon.
2
Scan once and verify the customer
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.
3
Complete payment normally
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 and/or after
checkout enabled. 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.
How earning is calculated
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.
Redeem a reward
Redemption is intentionally completed in Perkstar. Square Loyalty is not required, and rewards are not copied into Square.1
Scan the Perkstar Wallet pass
The customer presents their Apple Wallet or Google Wallet pass. Staff scan
it with the Perkstar scanner and confirm the correct member.
2
Redeem in Perkstar
Choose the available reward and complete the redemption. Wait for Perkstar
to confirm it so the member’s balance and audit trail remain authoritative.
3
Apply the matching Square adjustment
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 emptyreference_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.