# xLoyalty – Clover Integration

### Technical & Setup Documentation (v1)

The xLoyalty Clover Connector integrates Clover POS with the xLoyalty platform, enabling merchants to reward their customers with loyalty points and redeem them directly during checkout.

Important: All loyalty rules (earn and redeem) are configured inside xLoyalty only. Clover never stores or calculates loyalty rules.

## 1. Architecture Overview

    Clover POS
       │
       │  (Orders / Customers / Discounts API)
       ▼
    xLoyalty Clover Connector (PHP)
       │
       │  REST Calls
       ▼
    xLoyalty Platform & Database

## 2. Requirements

### Server

- PHP 5.6
- MySQL
- HTTPS / SSL
- cURL enabled

### Clover

- Clover Developer account
- Clover App created in Developer Portal
- Sandbox merchant for testing

## 3. File Structure

    /clover
      config.php
      db.php
      index.php
      link_xloyalty.php
      redeem_loyalty_api.php
      clover_client.php
      cron_sync.php

## 4. Installation

### Step 1 — Upload

Upload the folder to:

`https://club.xloyalty.io/clover/`

### Step 2 — Configure Clover

In Clover Developer Portal set:

`Site URL: https://club.xloyalty.io/clover/index.php`

### Step 3 — Launch

1. Install the app
2. Open from Clover POS
3. Connect Clover merchant to xLoyalty account

## 5. Loyalty Logic

### Earning Points

Handled through `transaction_loyalty_api.php`.

### Redeeming

Handled through `redeem_loyalty_api.php`.

Full redemption by default — all available points can be used.

## 6. Redeem Flow

1. Cashier opens xLoyalty app in Clover
2. Connector gets customer + order info
3. Calls `redeem_loyalty_api.php`
4. Receives discount value and points spent
5. Applies discount using Clover discounts API

## 7. Permissions

- Merchant (read)
- Orders (read/write)
- Payments (read)
- Customers (read/write)

## 8. Privacy

- No unnecessary tracking
- Data only shared with xLoyalty platform
- Used strictly for loyalty functionality