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

# Earn and redeem with Square

> Identify a member with one Wallet-card scan, award the routed programme and redeem through Perkstar without Square Loyalty.

Square provides the completed sale and refund signals. Perkstar owns the member,
loyalty balance, Wallet pass and reward redemption.

## Award a completed payment

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

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

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

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

<Warning>
  A customer must already belong to the routed Perkstar programme. An anonymous
  payment does not earn. The optional pre-payment scan does not change the
  payment webhook boundary: an unrelated attached Square customer who does not
  match an existing Perkstar member is not enrolled, and the unmatched contact
  is not retained.
</Warning>

## How earning is calculated

| Programme          | Square payment result                                   |
| ------------------ | ------------------------------------------------------- |
| Ordinary Stamp     | One stamp for the completed customer-attributed payment |
| Spend-based Stamp  | Whole thresholds met × stamps configured per threshold  |
| Visit-based Stamp  | The configured stamps per visit                         |
| Spend-based Points | The configured points rate applied to the paid amount   |
| Visit-based Points | The configured points per visit                         |
| Cashback           | The active tier's percentage applied to the paid amount |

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.

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

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

  <Step title="Apply the matching Square adjustment">
    Add the corresponding complimentary item or discount in Square using the
    business's normal till procedure, then complete checkout.
  </Step>
</Steps>

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

## 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 empty `reference_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](/integrations/square/refunds-troubleshooting).


## Related topics

- [Square refunds and troubleshooting](/integrations/square/refunds-troubleshooting.md)
- [Square](/integrations/square/index.md)
- [Set up Square](/integrations/square/setup.md)
- [Acuity appointments and rewards](/integrations/acuity/appointments-rewards.md)
- [Post a transaction (stamp / redeem / adjust)](/api-reference/transactions/post-a-transaction-stamp-redeem-adjust.md)