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

# Refunds and troubleshooting

> Reconcile Loyverse refunds, diagnose delayed loyalty updates and disconnect the integration safely.

## Refunds and cancellations

Process a refund or cancellation against the **original Loyverse receipt**.
Perkstar reverses the applicable earning and restores redemption value supported
by that correction. A cancellation is treated as a full correction, and the
same update is safe to receive more than once.

A refund against a sale created before the Step 2 migration snapshot does not
automatically adjust Perkstar points. Historical purchases were represented by
the copied opening balance rather than separate Perkstar receipt credits, so
Perkstar does not reconstruct and then reverse an old sale. Contact
[Loyverse@perkstar.co.uk](mailto:Loyverse@perkstar.co.uk) if the business needs
an opening-balance correction for that historical refund.

If Perkstar cannot safely match the correction to its original sale or determine
the supported amount, it does not invent a points or money adjustment. Only the
affected customer's published balance is held at zero and a review issue appears
on the Loyverse integration page while other receipts continue syncing.

<Warning>
  Do not make a manual points or balance adjustment when a refund needs review.
  Record the customer, original receipt number and time, then contact
  [Loyverse@perkstar.co.uk](mailto:Loyverse@perkstar.co.uk).
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Step 2 shows excluded, errored or incomplete customers">
    Do not enable scanning or send invitations yet. Open the migration result,
    use the identifying issue list to correct duplicate contact details, invalid
    balances or customer-code conflicts in Loyverse, then run the guided refresh
    or retry. Perkstar keeps successful rows and their points safe; a retry does
    not grant the opening balance or approved welcome points twice. If
    invitations have already started, contact support before changing the source
    cohort.
  </Accordion>

  <Accordion title="Email or SMS invitations are unavailable">
    Invitations open only for the exact current migration after every eligible
    customer has copied successfully. The included service email can be used
    during an eligible trial. Paid SMS requires an active paid subscription and
    enough SMS credits; its preview shows the eligible audience, message
    segments and credit cost. Customers without a usable contact method cannot
    be invited remotely and need a staff-assisted handoff.
  </Accordion>

  <Accordion title="The card is not under Ready to connect">
    Use its **Edit** link under **Needs changes**. Confirm it is an active
    individual Points card, earns automatically, uses flexible Points-to-Cash
    with a positive minimum, displays a QR code and requires First name and
    Email. Save the guided changes and return to Loyverse setup.
  </Accordion>

  <Accordion title="Scanning says Customer not found">
    Confirm customer scanning is on, the customer joined the selected card, and
    the device camera or external scanner is enabled. Check the integration page
    for duplicate-email, customer-code or missing-details issues, correct the
    record and choose **Retry customer sync**.
  </Accordion>

  <Accordion title="A paid sale did not earn points">
    Confirm the correct customer was attached before payment, the connected card
    is active, the receipt is paid and the POS is online. Check connection
    status and the last recovery sync before retrying. Perkstar does not guess
    the customer for an unattached receipt.
  </Accordion>

  <Accordion title="The customer has points but Balance is zero">
    Flexible Points-to-Cash remains locked until the configured minimum is
    reached. The Wallet card shows the points still needed. Also confirm till
    redemption has finished activating.
  </Accordion>

  <Accordion title="A balance is too high or appears to earn twice">
    Immediately open **Loyverse Back Office → Settings → Loyalty**, save **0%**
    and leave it there. Do not manually edit Loyverse points while Perkstar till
    redemption is active. Record the receipt and contact Perkstar support.
  </Accordion>

  <Accordion title="A sale, refund or Wallet update is delayed">
    Keep the POS online and allow the receipt to sync. Perkstar uses real-time
    receipt notifications with a five-minute recovery path, and the Wallet
    display can update shortly after the loyalty ledger. Check the dashboard
    before repeating an action.
  </Accordion>

  <Accordion title="The page says Reconnect required">
    Stop redemption and reconnect the same Loyverse business only after checking
    its balances and managed customer codes. If Loyverse access was revoked
    first, manually clear any remaining Perkstar-published values before turning
    redemption back on.
  </Accordion>

  <Accordion title="The page says Balance review required">
    Perkstar stopped instead of guessing about a changed or uncertain Loyverse
    balance. During the first cutover, turn off customer card scanning, wait for
    every managed code to be restored, then run the safe recovery check in Step
    2\. If that check says the value cannot be verified, do not edit it; contact
    Perkstar support. During a later reactivation, review the unexpected old
    Loyverse points balance. Retry activation only after you have confirmed it
    is safe to return that old Loyverse balance to zero; contact support if the
    value may be genuine.
  </Accordion>
</AccordionGroup>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can a Stamp card be connected?">
    No. Loyverse requires the complete scan, automatic earn and flexible
    monetary redemption journey, so only compatible Points cards are available.
  </Accordion>

  <Accordion title="Can the customer redeem part of their balance?">
    Yes. Once the card's minimum has unlocked spending, staff can enter any
    eligible amount up to the available balance and ticket limit. Perkstar
    deducts the exact monetary point discount on the paid receipt.
  </Accordion>

  <Accordion title="Does Perkstar synchronise products or payments?">
    No. Products, inventory, employees, taxes and payment information are not
    synchronised. The integration exchanges only the business, customer,
    receipt, refund, QR identifier and balance information required for loyalty.
  </Accordion>
</AccordionGroup>

## Disconnect safely

<Warning>
  Disconnect inside Perkstar first. Perkstar needs working Loyverse access to
  release its scan identifiers, reconcile outstanding receipts and clear the
  balance values it published.
</Warning>

<Steps>
  <Step title="Turn off customer card scanning">
    Open **Perkstar → Settings → Integrations → Loyverse**, choose **Turn off
    card scanning** and wait until the managed customer scan codes are released.
  </Step>

  <Step title="Disconnect Loyverse in Perkstar">
    Choose **Disconnect Loyverse**. Perkstar keeps receipt reconciliation active
    while it clears and verifies published balances. Resolve any displayed
    refund review first.
  </Step>

  <Step title="Wait for Disconnected">
    Keep Loyverse authorised while clearing and verification finish.
  </Step>

  <Step title="Remove the app in Loyverse if wanted">
    Only after Perkstar reports **Disconnected** should you remove the app from
    Loyverse Back Office.
  </Step>
</Steps>

Disconnecting does not delete ordinary Loyverse customer profiles or the
business's own Perkstar cardholders. Perkstar deletes the Loyverse credentials
and locally held API-derived copies after disconnection, while retaining the
de-identified Perkstar loyalty and accounting ledger under its normal retention
rules.

Already revoked Perkstar from Loyverse? Manually clear any remaining
Perkstar-published points and managed customer codes before using Loyverse
loyalty again, then contact [Perkstar support](mailto:Loyverse@perkstar.co.uk) for
guidance.


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