> ## 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.

# Set up Square

> Install the Square production beta, approve limited customer access, configure routing and enable optional Wallet-card identification.

Complete setup before taking a customer test payment. Authorising Square is the
first step; earning remains paused until the merchant has an explicit eligible
default programme and its location routing is valid.

<Warning>
  Square is a **production beta** installed directly through Perkstar. Use
  Perkstar's direct installer; it is not currently listed in the Square App
  Marketplace, but a Marketplace listing is not required to connect or use the
  integration.
</Warning>

<Note>
  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.
</Note>

## 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

| Programme | Eligible earning rule |
| - | - |
| Stamp | Ordinary Stamp, spend-based or visit-based earning with a valid rate |
| Points | Spend-based or visit-based automatic earning with a positive rate |
| Cashback | A configured first tier with a positive cashback percentage |

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

You can also find Square from **Integrations → Marketplace** in Perkstar's
navigation. On a phone, open the menu first. Search for **Square**, open its
details and choose **Setup**. After connecting, use **Integrations → My
integrations** to return to management. This is Perkstar's integration catalogue,
not a claim that the app is listed in Square's App Marketplace.

<Steps>
  <Step title="Open the Perkstar installer">
    [Connect Square](https://dashboard.perkstar.co.uk/install/square), then sign
    in or create your Perkstar account. Select the eligible Scale organisation
    you want to connect if asked.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Choose the programme and locations

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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 include `CUSTOMERS_WRITE` must
reconnect before the feature can be enabled; ordinary attached-customer earning
remains available while it is off.

<Steps>
  <Step title="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.
  </Step>

  <Step title="Enable Wallet-card scanning">
    In **Settings → Integrations → Square**, review the matching, creation and
    reference-ownership acknowledgement, then choose **Enable scanning**.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

### Square device and app checklist

| Square setup | Required preparation |
| - | - |
| Square Point of Sale on Terminal or Register | Open **Settings → Checkout → Customer Management**. Enable **Scan customers using device camera** and **Show Add customer button during checkout**. **Show Add customer button after checkout** is optional; after-checkout attachment alone is not sufficient for Perkstar earning. Attach the customer before payment. |
| Square for Retail or Square for Restaurants | QR and barcode customer scanning is enabled automatically. Keep the app and device current, then test an on-screen Wallet QR on every device. |
| Square Handheld or a physical scanner | Compatibility depends on the installed Square app and hardware. Enable any **Scanning for screens** option and test the exact device. Do not promise Wallet QR customer attachment until that test passes. |

Square's current instructions are in its [customer QR and barcode scanning
guide](https://squareup.com/help/gb/en/article/7387-identify-customers-at-your-counter-with-qr-codes).
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 `posBarcodeValue` into an empty
  Square Customer `reference_id`.
* A non-empty `reference_id` is 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.

1. Confirm the test customer has already joined the routed Perkstar programme.
2. Use Square's normal customer search to attach a Square Customer whose email
   or phone exactly matches the synthetic Perkstar member.
3. Complete a small payment and confirm the standard attached-customer path
   credits the expected stamps, points or cashback once and refreshes the Wallet
   pass.
4. Refund part of that original payment and confirm the supported proportional
   correction appears once.
5. Refund the remainder and confirm the total correction never exceeds the
   original award.
6. 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.
7. If optional Wallet QR identification was enabled, turn it off and confirm
   only proven Perkstar-owned references are cleared.
8. Before offering redemption, agree the actual priced reward item or discount
   and train staff on the chosen workflow: customer self-redemption from the
   pass for supported rewards, or Perkstar Scanner. Test one genuinely
   available reward, verify Perkstar's saved redemption and remaining balance,
   and check the matching Square item/discount and currency. Do not manually
   set a balance to manufacture a successful test or incur charges without
   permission. A pass redemption does not automatically discount Square.

Continue with the [staff earning and redemption guide](/integrations/square/earning-redemption).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.