Direct-install readiness uses the standard Square customer-search path:
connect, finish programme and location routing, then complete matched-payment
and refund checks. Optional Wallet QR device acceptance and a Perkstar reward
redemption are not prerequisites for Square earning.
Before you connect
- Use the Scale plan or another plan that includes POS Connect.
- Sign in as the organisation owner or a team member with Edit operations.
- Be authorised to approve apps for the intended Square production account.
- Prepare at least one active, unarchived, earn-ready Perkstar programme.
- Ask a test customer to join that Perkstar programme before the test sale.
- To use one-scan identification, make the default programme individual, use a QR barcode, and require First name and Email on its sign-up form.
Eligible programmes
Discount, Multipass, Membership, Coupon, Gift and Ticket cards cannot receive
Square payment earning. A programme restricted to selected Perkstar locations
cannot be the global default; route it only from a Square location linked to one
of its allowed Perkstar locations.
Connect the merchant
1
Open the Perkstar installer
Connect Square, then sign
in or create your Perkstar account. Select the eligible Scale organisation
you want to connect if asked.
2
Review the data-use notice
Confirm the merchant you intend to connect and read how customer matching,
storage and disconnect work. Choose Continue to Square only if you are
authorised for that Square business.
3
Approve the four limited permissions
Sign in to the correct Square production account and approve
MERCHANT_PROFILE_READ, CUSTOMERS_READ, CUSTOMERS_WRITE and
PAYMENTS_READ. Customer write access supports optional Wallet-card
identification only. Perkstar does not request payment write or Square
Loyalty permissions.4
Verify the returned merchant
Back in Perkstar, check the Square business name, merchant identifier,
country and currency. If the wrong merchant was authorised, disconnect it
before configuring or taking a test payment.
Choose the programme and locations
1
Choose the explicit default programme
Open Settings → Integrations → Square and select the programme that
should receive payments by default. No organisation-primary or first-card
fallback is used.
2
Review every Square location
Each location can inherit the default programme, use another eligible
programme, or pause loyalty. Do not leave an active selling location in an
invalid route.
3
Link reporting locations where needed
Link the Square location to the corresponding Perkstar location for
reporting. This link is required before a location-restricted programme can
be selected as that Square location’s override.
4
Resolve the setup warning
The Square page reports setup as incomplete while the default programme or
any location route is ineligible. Correct every warning before testing.
Attach the customer before payment
The standard workflow does not require Wallet QR identification. Staff use Square’s normal customer search and attach the existing Square Customer before payment. The customer must already belong to the routed Perkstar programme, and the attached Square profile’s email address or phone number must exactly match that member. When both fields are supplied, every exact match must identify the same member. If email and phone point to different members, Perkstar awards nothing, keeps the payment queued for retry and opens a merchant-visible Customer match case until the duplicate or contact data is corrected. Anonymous or unmatched payments do not earn.Enable optional Wallet QR identification
This optional feature lets Square identify a consenting Perkstar member from the QR code already displayed on their Apple Wallet or Google Wallet pass. Existing Square connections that do not includeCUSTOMERS_WRITE must
reconnect before the feature can be enabled; ordinary attached-customer earning
remains available while it is off.
1
Prepare the default programme
Use an active, unarchived individual programme. Select QR as its barcode
format and make First name and Email required on the sign-up form.
2
Enable Wallet-card scanning
In Settings → Integrations → Square, review the matching, creation and
reference-ownership acknowledgement, then choose Enable Wallet-card
scanning.
3
Let each customer choose
Perkstar offers optional consent on the join surface. To change the choice
later, the customer opens the customer-account link on the back of their
Wallet pass, then chooses Preferences → Square customer identification.
Current consent is required before any Square directory search, link or
Wallet-reference publication. For a consenting customer, Perkstar
exact-matches an existing Square Customer or, only if none exists, may
create one from their first name, optional surname, email and optional
phone.
4
Configure and test every Square device
In Square, open Review sale → Add customer → scan icon, scan a test
member’s Wallet QR and confirm the correct Square Customer is attached
before payment. Follow the device checklist below.
Square device and app checklist
Square’s current instructions are in its customer QR and barcode scanning
guide.
A physical scanner must be able to read a QR code displayed on a phone. If
Wallet QR scanning is unavailable, staff use Square’s normal customer search to
attach the matching Square Customer by email or phone before payment.
Safe matching and reference ownership
- Without current Square-directory consent, Perkstar does not search, link or publish a Wallet reference.
- For a consenting customer, Perkstar exhausts exact searches by the stable Wallet reference, email and, when available, phone. Conflicting or incomplete results are left unchanged for review.
- A unique existing Square Customer can be reused. Only if no exact match exists may Perkstar create a profile from the disclosed fields.
- Perkstar writes only the enrolment’s stable
posBarcodeValueinto an empty Square Customerreference_id. - A non-empty
reference_idis never overwritten, even if it resembles a Perkstar value without recorded ownership. - Turning the feature off, customer withdrawal, erasure or Square disconnect releases only a live reference value that Perkstar can prove it owns. The merchant’s Square Customer remains.
Test before serving customers
Use a synthetic member and record the expected result from the selected programme’s exact earning rules.- Confirm the test customer has already joined the routed Perkstar programme.
- Use Square’s normal customer search to attach a Square Customer whose email or phone exactly matches the synthetic Perkstar member.
- Complete a small payment and confirm the standard attached-customer path credits the expected stamps, points or cashback once and refreshes the Wallet pass.
- Refund part of that original payment and confirm the supported proportional correction appears once.
- Refund the remainder and confirm the total correction never exceeds the original award.
- If the business enables optional Wallet QR identification, opt the synthetic
member in, test either a unique existing Square Customer exact match or
consented creation, then scan the Wallet QR on every supported device and
confirm the intended Square Customer is attached before payment. Also test a
Square Customer with a non-empty foreign
reference_id; Perkstar must not overwrite it. - If optional Wallet QR identification was enabled, turn it off and confirm only proven Perkstar-owned references are cleared.