Award a completed payment
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
Open Square customer scanning
On the Square checkout, open Review sale → Add customer → scan icon. The
business must have enabled Wallet-card identification and tested that
device.
3
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. Current customer consent
was required before Perkstar searched or linked: it either reused one
complete exact match or, if none existed, created the profile.
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.
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.
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.
For corrections and delayed events, continue to Refunds and troubleshooting.