> ## 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. It is not
  currently listed in the Square App Marketplace while Perkstar collects the
  required five active-seller evidence.
</Warning>

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

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

## 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 include `CUSTOMERS_WRITE` must reconnect before the
feature can be enabled; ordinary payment earning remains safe 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 Wallet-card
    scanning**.
  </Step>

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

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

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

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

## 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. Opt the synthetic member into Square customer identification before testing
   either a unique existing Square Customer exact match or consented creation.
3. In Square, open **Review sale → Add customer → scan icon**, scan the Wallet
   QR, and confirm the correct Square Customer is attached before payment.
4. Confirm Perkstar credits the expected stamps, points or cashback once and
   refreshes the Wallet pass.
5. Refund part of that original payment and confirm the supported proportional
   correction appears once.
6. Refund the remainder and confirm the total correction never exceeds the
   original award.
7. 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.

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


## Related topics

- [Square](/integrations/square/index.md)
- [Set up Acuity](/integrations/acuity/setup.md)
- [Set up Loyverse](/integrations/loyverse/setup.md)
- [Square refunds and troubleshooting](/integrations/square/refunds-troubleshooting.md)
- [Earn and redeem with Square](/integrations/square/earning-redemption.md)