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

> Prepare a compatible Points card, set Loyverse earning to 0%, connect the businesses and test the complete journey.

Complete every step before serving customers. Perkstar keeps earning and till
redemption off until the required card, scanning and balance checks are ready.

## Before you connect

* Confirm Perkstar and Loyverse use the same currency. Till redemption requires
  a currency with two decimal places.
* Sign in as a Perkstar owner or manager and use a plan that includes Loyverse.
* Make sure you can approve apps for the intended Loyverse business.
* Finalise the connected Points card's earning and Points-to-Cash rules before
  moving customers. Perkstar copies the current Loyverse points balance; it
  does not rebuild value from receipt history.
* Keep every POS device online while configuring and testing it.

<Warning>
  Perkstar will not clear an existing Loyverse points balance until its direct
  migration has recorded every eligible customer and copied the current points
  exactly. Activation then validates the same snapshot, clears the old balances
  twice and publishes only each customer's spendable Perkstar balance.
</Warning>

## Prepare the Points card

The card picker shows eligible cards under **Ready to connect**. Cards under
**Needs changes** cannot be selected and include an **Edit** link explaining
what to fix.

A compatible card must be:

* active and unarchived;
* a Points card for individual customers, not a group-enrolment card;
* configured to earn automatically by spend or visit, rather than by manual
  points entry;
* configured with an ongoing Points-to-Cash balance and a valid conversion;
* set to flexible spending with a positive minimum balance before spending;
* configured to display a QR code; and
* configured to require **First name** and **Email** on the sign-up form.

<Note>
  Stamp cards, reward-level Points cards, set-amount Points-to-Cash cards,
  group-enrolment cards and manual-earning cards cannot be connected. Flexible
  Points-to-Cash is required because a cashier can enter any eligible amount up
  to the available balance.
</Note>

## Set Loyverse earning to 0%

<Steps>
  <Step title="Open Loyverse Back Office">
    Sign in to the same Loyverse business you will connect to Perkstar.
  </Step>

  <Step title="Open Loyalty settings">Go to **Settings → Loyalty**.</Step>

  <Step title="Save zero percent">
    Set the loyalty earning percentage to **0%**, then select **Save**.
  </Step>
</Steps>

This setting applies across the Loyverse account. Perkstar cannot read or change
it through the Loyverse API, so you must confirm it during activation and leave
it at 0% while the integration is live. See [Loyverse's loyalty
instructions](https://help.loyverse.com/help/how-customer-loyalty-program).

## Connect and activate

<Steps>
  <Step title="Connect the correct businesses">
    [Start the Loyverse
    connection](https://dashboard.perkstar.co.uk/install/loyverse), sign in to
    Perkstar and choose the business if asked. Authorise access to Loyverse
    business details, customers and receipts. On return, check the Loyverse
    business name and currency before continuing.
  </Step>

  <Step title="Choose the Points card">
    Select the intended card under **Ready to connect**, then choose **Use this
    card with Loyverse**. Use the guided **Edit** link if a card is under
    **Needs changes**.
  </Step>

  <Step title="Move existing customers and points">
    In **Step 2**, choose **Check existing Loyverse customers**. Review the
    customer count, total points and any named issues. The owner can keep the
    copied balances exactly as they are—the default—or approve the card's
    configured welcome points for eligible existing customers. Perkstar shows
    the maximum points and cash-equivalent exposure before anything starts.
    Confirm the data-transfer instruction and, where shown, approve replacing
    the exact existing customer codes. Then choose **Copy customers and
    points**. Perkstar copies `total_points` as the opening membership balance;
    it does not recalculate old purchases. Follow the [customer migration and invitation
    guide](/integrations/loyverse/customer-migration-invitations) for the full
    transition journey.
  </Step>

  <Step title="Tell customers about the move">
    Only after Step 2 says the migration is complete, open its results. For the
    first rollout, send one controlled included-email or paid-SMS test to an
    eligible owner-controlled membership, then complete the till checks below
    before releasing the remaining included service email, paid SMS, or both.
    Perkstar does not message customers automatically. Every message opens the
    exact migrated membership so the preserved balance stays attached to the
    right person.
  </Step>

  <Step title="Enable customer card scanning">
    Read and confirm the customer data-sharing notice, then choose **Enable
    customer card scanning**. Customers moved in Step 2 remain bound to their
    exact Loyverse profiles. Perkstar publishes each managed Wallet QR
    identifier and shows live progress as **X of Y customers ready**. Resolve
    every listed conflict before till redemption is available. For customers who
    join after cutover, Perkstar links one unambiguous exact-email profile or
    creates an eligible profile when none exists.
  </Step>

  <Step title="Configure every POS device">
    In Loyverse POS, open **Settings → General** and enable **Use camera to scan
    barcodes**, unless the device uses a compatible external scanner. Tap **Add
    customer**, scan a test Wallet card and confirm the correct customer opens.
    Repeat this on every new or replacement device.

    On a Teya Android terminal running Loyverse, try the built-in camera first.
    A SUNMI Blink or another compatible 2D scanner can be used in USB
    HID/keyboard mode when the terminal or dock provides USB host/OTG access.
    Test the exact terminal, dock and scanner together before buying or rolling
    out hardware.
  </Step>

  <Step title="Enable till redemption">
    Confirm separately that every device can scan, Loyverse is set to 0%, and
    existing balances may be replaced. Choose **Enable till redemption** and
    allow about 20 minutes for a small customer list. A list of around 550
    customers typically takes 30–90 minutes; lists above 2,000 can take several
    hours. Activation includes a required 15-minute safety wait between two
    complete balance checks. You can leave the page after starting because
    Perkstar continues safely in the background. Keep Loyverse earning at 0% and
    do not let staff redeem or manually edit old Loyverse points from the Step 2
    snapshot until activation finishes. Do not serve customers until the page
    says scanning, earning and redemption are connected.
  </Step>
</Steps>

## Customer information used for scanning

During the one-time transition, Perkstar reads the existing Loyverse customer
directory, exact customer IDs, contact details, current points balances and
customer codes so the business can preserve its loyalty members and value.
When scanning is enabled, Perkstar sends the customer's name, email address,
optional phone number and managed Wallet scan identifier to Loyverse. Customer
reference IDs, receipts, redemptions and balance data are exchanged to run the
integration. The business must instruct this transfer, tell customers about the
sharing and have an appropriate lawful basis. No marketing consent is inferred.

* [Perkstar privacy policy](https://dashboard.perkstar.co.uk/privacy)
* [Integration recipients](https://dashboard.perkstar.co.uk/dpa/sub-processors)

## Test before going live

Use a synthetic customer and record the expected result for the connected
card's exact earning and conversion rules.

1. Scan the Wallet card through **Add customer**, attach the customer and
   complete one paid sale without redemption.
2. Confirm points were added once and the Wallet fields updated.
3. Complete another sale and redeem a smaller amount, such as £1.25 from a
   larger available balance.
4. Confirm precisely that amount was deducted—not pennies and not the complete
   balance.
5. Refund the second sale against its original receipt and confirm the eligible
   correction was applied once.

If setup stops or a button remains unavailable, follow the on-screen
**Before you can continue** list. The Loyverse page can also send a redacted
setup snapshot to Perkstar support and returns a reference number. That
snapshot contains milestones, permission state and aggregate counts only—not
customer contact details, individual balances, access tokens or raw provider
responses.

Continue with the [staff checkout guide](/integrations/loyverse/checkout).


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