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

Corrections are based on the original credited amount, not a fresh calculation
using today's programme rules or a returned item's category. Points corrections
round to two decimal places; stamps and cashback minor units round down until
the cumulative refunded amount justifies the next unit. For example, half of a
one-stamp payment can reverse zero stamps; a full refund reverses that stamp.
Square refunds are payment-level: there is no item-by-item or tip-only refund
allocation. Review those adjustments with support before promising an exact
loyalty outcome.

If the customer has already used the loyalty value, Perkstar does not force a
negative balance. It records a case requiring review. A refund also does not
undo a discount that staff already applied at the till. Check any earned or
redeemed rewards as part of that review.

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.

The five-minute recovery job discovers missed **refunds**. For payments,
recovery relies on Square's webhook retries and Perkstar's durable inbox; there
is no general automatic historical payment import. Contact support if a
completed, attributed payment is still absent—do not manually add loyalty
while a delayed payment may still be processed.

<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 running Square Point of Sale, open **Settings →
    Checkout → Customer Management** and enable both **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. Keep Square for Retail or
    Restaurants current. Test a Handheld or physical scanner against an
    on-screen Wallet QR before relying on it. If the device cannot scan the
    member there, use Square's normal customer search to attach the matching
    Square Customer before payment. 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 surface. To change it later, they open the customer-account
    link on the back of their Wallet pass, then choose **Preferences → Square
    customer identification**. 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. The customer
    can redeem an eligible reward from their pass and show staff the live
    confirmation, or staff can redeem using Perkstar Scanner. Staff then apply
    the corresponding item or discount in Square; it is not automatic. Follow
    the [redemption
    guide](/integrations/square/earning-redemption#redeem-a-reward) for
    eligibility, confirmation checks and cancelled-checkout handling.
  </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">
    If the seller is still listed with **Reconnect**, automatic token renewal
    failed or the current access expired. Reauthorise that same Square seller
    through the direct Perkstar installer. Perkstar replaces its credential in
    place and retains the saved default programme and location routes. If the
    connection was revoked or explicitly disconnected and the seller row was
    removed, start a fresh installation and configure the default programme and
    routes again.
  </Accordion>

  <Accordion title="My business cannot open the Square installer">
    Square is available as a production beta through Perkstar's direct installer
    and is not currently listed in the Square App Marketplace. A Marketplace
    listing is not required. 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.

Disconnect only after all expected refunds have settled. Once the Square
payment link and credentials are removed, a later Square refund for a payment
from the disconnected installation cannot be reversed automatically in
Perkstar; contact support for a reviewed correction. If access is revoked in
Square before disconnecting in Perkstar, Perkstar may also be unable to clear a
Wallet QR reference it previously owned. The merchant can clear that stale
`reference_id` from the Square Customer record or ask support for guidance.

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


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