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.
Enable one-scan customer identification
This optional feature lets Square identify a 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 payment earning remains safe 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 customers choose
Perkstar offers optional consent on the Perkstar join and preferences
surfaces. 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. They can withdraw that choice later.
4
Configure and test every Square device
In Square, open Review sale → Add customer → scan icon, then scan a test
member’s Wallet QR. On each Square Terminal or Register, enable Settings →
Checkout → Customer Management → Scan customers using device camera.
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.
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.
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.
- Opt the synthetic member into Square customer identification before testing either a unique existing Square Customer exact match or consented creation.
- In Square, open Review sale → Add customer → scan icon, scan the Wallet QR, and confirm the correct Square Customer is attached before payment.
- Confirm Perkstar 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.
- Test a Square Customer with a non-empty foreign
reference_id; Perkstar must not overwrite it. Turn scanning off and confirm only proven Perkstar-owned references are cleared.