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

# Square refunds and troubleshooting

> Reconcile full and partial Square refunds, diagnose missing earning and disconnect the pilot integration safely.

## Refunds

Process the refund in Square against the **original payment**. Completed full
and partial refunds reverse the corresponding Perkstar credit. Partial refunds
use the proportional share supported by the original award and rounding rules;
combined corrections never reverse more than the original credit.

Square may report a refund while its payment or refund is still changing state.
Perkstar waits for a terminal completed record, handles out-of-order delivery,
and uses recovery reconciliation for missed notifications. Repeated delivery of
the same refund is safe.

<Warning>
  Do not make a manual loyalty correction while a Square refund is pending or
  under review. That can duplicate the automatic reversal. Record the original
  payment, refund time and Square location, then check the integration page.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="A completed payment did not earn">
    Confirm Square setup is complete, the explicit default programme is
    eligible, and the selling location is not paused or invalid. The payment
    must be completed and have a Square customer attached before payment. That
    profile must match an existing member of the routed Perkstar programme by
    email, phone, a previously established opaque link or the owned Wallet scan
    reference.
  </Accordion>

  <Accordion title="The Wallet QR does not find a Square Customer">
    Use **Review sale → Add customer → scan icon**, not the payment barcode
    screen. Confirm Wallet-card scanning is on, the default programme is an
    individual active QR programme, and First name and Email are required. If
    the connection predates customer write access, reconnect Square. On Square
    Terminal or Register, enable **Settings → Checkout → Customer Management →
    Scan customers using device camera**. A conflicting exact match or non-empty
    foreign reference is left unchanged and appears as an attention item in
    Perkstar.
  </Accordion>

  <Accordion title="Perkstar did not create a missing Square Customer">
    Square identification is optional and requires that customer's explicit
    Square Customer Directory consent before any exact search, link, creation or
    Wallet-reference publication. The member can grant or withdraw it from the
    Perkstar join or customer-preferences surface. Without consent, Perkstar
    leaves Square unchanged.
  </Accordion>

  <Accordion title="Square is authorised but setup says incomplete">
    OAuth alone does not start earning. Choose an eligible unrestricted default
    programme, review every Square location, and repair any incompatible
    override. A location-restricted programme also needs an allowed Perkstar
    reporting location linked to that Square location.
  </Accordion>

  <Accordion title="The customer exists in Square but still did not earn">
    Joining Square is not the same as joining Perkstar. Ask the customer to join
    the routed Perkstar programme first, use the same email or phone on both
    records, then attach the Square customer before a new payment. An earlier
    anonymous or unmatched payment is not credited retrospectively, and the
    unmatched contact is not retained.
  </Accordion>

  <Accordion title="A reward is not visible in Square">
    That is expected. Square Loyalty is not required or written. Scan the
    customer's Wallet pass with the Perkstar scanner, redeem in Perkstar, then
    apply the corresponding item or discount in Square.
  </Accordion>

  <Accordion title="A refund correction is delayed">
    Confirm the refund was completed against the original Square payment. Allow
    the terminal update and recovery reconciliation to finish before changing
    the member's balance manually. If an operational issue remains on the Square
    integration page, record the time and contact Perkstar support.
  </Accordion>

  <Accordion title="The page says reconnect required">
    Square access was revoked, expired or permanently failed. The retired grant
    cannot resume. Start a fresh connection through the direct Perkstar
    installer, then choose the default programme and review all location routes
    again.
  </Accordion>

  <Accordion title="My business cannot open the Square installer">
    Square is a production beta installed directly through Perkstar and is not
    currently listed in the Square App Marketplace. Confirm the organisation has
    Scale/POS Connect and that you are an owner or have **Edit operations**. If
    it still will not open, contact Perkstar support.
  </Accordion>
</AccordionGroup>

## Disconnect safely

An organisation owner or team member with **Edit operations** can disconnect
Square from **Settings → Integrations → Square**. New Square work stops
immediately. Perkstar revokes the Square grant and removes encrypted
credentials, merchant and location routing, opaque Square customer links,
Square-sourced operational data and retained webhook payloads.

Before local ownership evidence is purged, Perkstar attempts to clear only a
Square Customer `reference_id` whose live value and durable ownership record
both prove Perkstar set it. Foreign, merchant-edited and merely coincidental
values are never removed. Square Customer profiles, including consent-created
profiles, remain under the merchant's control.

Existing de-identified Perkstar-authored loyalty balances and ledger entries
remain so customers do not lose rewards already earned. A later reconnection is
a fresh installation and requires the default programme and every location
route to be configured again.

<Note>
  Email [support@perkstar.co.uk](mailto:support@perkstar.co.uk) with the
  Perkstar business name, approximate payment or refund time, and Square
  location name. Never send an access token, raw webhook body, payment-card data
  or customer contact details.
</Note>


## Related topics

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